BIPM Time Dept database
BIPM Time Department Data Base
readme

BIPM Time Department API Web Service

Overview

To answer the need of providing machine readable data, the BIPM Time Department started providing access to machine readable data through automatized process.

Results are still available using FTP protocol, this remains unchanged. In addition to the historical FTP access, it is proposed an application programming interface (API) using GET method which gives access to machine readable data regarding various time scales. The method to access these data is using HTTP/HTTPS protocol: This can be done using utilities to transfer data from a server (such as cURL, wget or any programming languages supporting HTTP protocol). Data are provided in standard exchange format, such as JSON, CSV and text.

Execution documentation

Changes between versions 1.0 and 0.2-beta

Custom requests syntax and arguments

The API using GET method uses URL general syntax below :
https://webtai.bipm.org/api/v1.0/get-data.html?arg1=xxxx&arg2=yyyy ...
Using as many arguments as needed by your query.

Get values [Scale-local realizations of UTC]

Target product URL request
[UTC-UTC(lab)] https://webtai.bipm.org/api/v1.0/get-data.html?scale=utc&lab=labo
[UTCr-UTC(lab)] https://webtai.bipm.org/api/v1.0/get-data.html?scale=utcr&lab=labo
[UTC-UTC(lab)] and [UTCr-UTC(lab)] https://webtai.bipm.org/api/v1.0/get-data.html?scale=utc+utcr&lab=labo
list of laboratories lab https://webtai.bipm.org/api/v1.0/get-data.html?list

Get values [UTC-GNSS time scales ]

Target product URL request
[UTC-GPS Time] https://webtai.bipm.org/api/v1.0/get-data.html?scale=gps
[UTC-GLONASS Time] https://webtai.bipm.org/api/v1.0/get-data.html?scale=glonass
[UTC-Galileo Time] https://webtai.bipm.org/api/v1.0/get-data.html?scale=galileo
[UTC-Beidou Time] https://webtai.bipm.org/api/v1.0/get-data.html?scale=beidou
[UTC-GPS Time] and [UTC-GLONASS Time]
and [UTC-Galileo Time] and [UTC-Beidou Time]
https://webtai.bipm.org/api/v1.0/get-data.html?scale=gnss

Get values [UTC-prediction of UTC broadcast by GNSS]

Target product URL request
[UTC-bUTC_GPS] https://webtai.bipm.org/api/v1.0/get-data.html?scale=b_gps ( or ?scale=butc-gps )
[UTC-bUTC_GLO] https://webtai.bipm.org/api/v1.0/get-data.html?scale=b_glonass ( or ?scale=butc-glo )
[UTC-bUTC_GAL] https://webtai.bipm.org/api/v1.0/get-data.html?scale=b_galileo ( or ?scale=butc-gal )
[UTC-bUTC_BDS] https://webtai.bipm.org/api/v1.0/get-data.html?scale=b_beidou ( or ?scale=butc-bds )
[UTC-bUTC_GPS] and [UTC-bUTC_GLO]
and [UTC-bUTC_GAL] and [UTC-bUTC_BDS]
https://webtai.bipm.org/api/v1.0/get-data.html?scale=b_gnss ( or ?scale=butc-gnss )

HTTP utilities / examples

It is required to use utilities supporting HTTP protocol to get the data, such as cURL (https://curl.se/) , wget (https://www.gnu.org/software/wget/) or other programming languages such as Python, Perl, etc.

Below you can find examples of commands:

Using wget

wget -O utc-utc_aos.json "https://webtai.bipm.org/api/v1.0/get-data.html?scale=utc&lab=AOS"

Using cURL

curl -k --url "https://webtai.bipm.org/api/v1.0/get-data.html?scale=utc&lab=AOS" > utc-utc_aos.json

Using Perl

#!/usr/bin/perl

use LWP::UserAgent;
my $ua = LWP::UserAgent->new;
my $response = $ua->get("https://webtai.bipm.org/api/v1.0/get-data.html?scale=utc&lab=AOS") ;
if ($response->is_success) { print $response->decoded_content; }

Using Python

import requests
r = requests.get("https://webtai.bipm.org/api/v1.0/get-data.html?scale=utc&lab=AOS")
print(r.text)

Using Matlab

(Example contributed by A. Wallin, VTT)

clear all
close all
data = webread("https://webtai.bipm.org/api/v1.0/get-data.html?scale=utc&lab=MIKE")
mjd = data.data.x;
phase_ns = data.data.y;
figure()
plot(mjd,phase_ns,'o')

Ouput files format

txt file format

The format of txt is in fixed format. Since version 1.0, txt files are formatted as :
- %6d %10.1f %10.1f\r\n for a single scale request ( MJD, value, uncertainty )
- %6d %10s %10s\r\n for a 2-scales request ( MJD scale1, scale2)
- # character is used to identify comments/headers which are not data to be processed.

Additional metadata

Since version 0.2, for each data serie, additional metadata are available in the JSON files to facilitate the use of data

Parameter Description
xmin: value minimal xaxis value of the serie (in Modified Julian Date)
xmax: value maximal xaxis value of the serie (in Modified Julian Date)
x_tot: value number of x data in the serie
ymin: value minimal yaxis value of the serie (in Nanoseconds)
ymax: value maximal yaxis value of the serie (in Nanoseconds)
y_tot: value number of y data in the serie

Execution error codes

In version 0.2, error codes have been reinforced, with messages to provide details on the issue.

Error code Type of error
0 Successful execution
1 Error accessing ftp2.bipm.org, contact BIPM Time Department
2 Error accessing data, check API query sent then contact BIPM
3 Error in content of the file, contact BIPM
4 Error in user query

Final status of execution are reported using specific keys :

key values
errorcode Error codes defined upper
success true or false
message message describing the error

In TXT and CSV output files, these keys are reported only in case of failure of the process, line starting with a #.
In JSON files they are always available.
Always ensure that your query syntax is valid and that data have been published, then contact BIPM to report observed troubles.

Change log

Historical changes

Version Date Feature/Change
Version 0.1 16/12/2021 First testing version
Version 0.2-beta 02/06/2021 - Format change : left alignment of MJD column in TXT files
- New features in JSON file
- Execution error codes improved and debug messages added
Version 1.0 (stable) 22/05/2024 Backward compatible with v0.2-beta
Added features :
- GNSS times Galileo and Beidou
- prediction of UTC broadcast by GNSS
- uncertainties
- insensitive case arguments supported
- Security improvement for the BIPM
31/07/2024 New argument formatting supported for 'UTC broadcast by GNSS time scales'

Home FTP results API UTC Sitemap Contact us Webmaster