CCL-CCTF API Web Service

Introduction

• Overview
  The Mises en Pratique for the metre and the second are currently published in the BIPM website as PDF files ("Recommended values of standard frequencies"). The CCL and CCTF communities expressed the needs to have access to these data in a machine-readable format. More about this matter can be found in A.J. Lewis and al.(2022), "A digital framework for realising the SI-a proposal for the metre" , Metrologia 59 044004.
  To answer to this need the BIPM Time Department started a digitalization project allowing an automatized process based on a a dedicated database and API.
  In the first release of this project the data currently available in PDF files will be provided in XML format.

• Scope
  This application programming interface (API) is providing to machines the access to the list of recommended values of standard frequencies for applications including the practical realization of the definition of the metre and secondary representations of the definition of the meter and the second.

• Technical aspects
  The following API using GET method, the access to the data is using HTTP/HTTPS protocol.
  This can be obtained using utilities to transfer data from a server (such as cURL, wget or any programming languages supporting HTTP protocol).
  A dedicated shared script to be run as client has been created for a very easy access to all the available XML files. The current version is to be considered as a prototype for extensive testing and feedbacks from users are welcome.

• Ouput format
  Data are provided in standard exchange format : XML
  ( The XML schema has been defined by the National Physical Laboratory and posted on Zenodo : https://zenodo.org/record/6412020 ).

Technical documentation

Client download

To allow an quick and easy generation of the XML documents, a small bash script client has been developped.
This script allows to automatically download all available XMLs files with results corresponding to all reference frequencies for the meter and the second for the current date.
You can download this script: Documentation + Source code (TAR and ZIP).
It has been validated under Linux. For Windows use WSL, MSYS2, etc. to emulated the Linux environment.

URL parameters for query (syntax and arguments)

The API using GET method uses URL general syntax below :

 https://webtai.bipm.org/api/ccl-cctf/v1.0/xml_auto.html?target=127I2|552+THz&date=2022-11-15 

or ( to prevent use of '|' character in command line ) :

 https://webtai.bipm.org/api/ccl-cctf/v1.0/xml_auto.html?target=127I2&freq=552+THz&date=2022-11-15 

• "target=" and "date=" arguments are compulsory
• date= stands for the date "YYYY-MM-DD" for which the valid results will be returned
  
• target stands for the couple (specie | frequency), where specie is the chemical element and frequency is the short-name of the frequency as expressed in BIPM webpage which contains all 'Mises en Pratique' for the realization of the meter and the second.
  The list of all available (specie|frequency) couples can be accessed here : >> See list specie|frequency available <<

Examples of requests

It is required to use utilities supporting HTTP protocol to get the data, such as cURL , wget or other programming languages such as Python, Perl,etc.

Below you can find examples of commands:

#!/usr/bin/perl
use LWP::UserAgent;
my $ua = LWP::UserAgent->new;
my $response = $ua->get("https://webtai.bipm.org/api/ccl-cctf/v1.0/xml_auto.html?target=127I2|552+THz&date=2022-11-15") ;
if ($response->is_success) { print $response->decoded_content; }

import requests
r = requests.get("https://webtai.bipm.org/api/ccl-cctf/v1.0/xml_auto.html?target=127I2|552+THz&date=2022-11-15")
print(r.text)

References

• [1] A J Lewis et al., "A digital framework for realising the SI-a proposal for the metre", 2022 Metrologia 59 (4) 044004
• [2] A J Lancaster et al., "NPL MeP standard frequencies XML schema", 2022
• [3] D Hutzschenreuter et al., "SmartCom Digital-SI (D-SI) XML exchange format for metrological data version 1.3.1", 2020

Historical changes