Royal Belgian Institute for Space Aeronomy
Application Programming Interface (API) for BIRA-IASB data

How to use this data with a command-line HTTP-client

The data on this is meant to be downloaded by a script, while using machine-to-machine-like command-line based HTTP clients (e.g. curl or wget).

Starting on the top-level, you see the available services. 

    $ curl  https://api.aeronomie.be/api/runners | jq . -

    "data": {
        "geoms_to_netcdf": {
            "type": "url",
            "url": "https://api.aeronomie.be/api/runners/geoms_to_netcdf",
            "attributes": {
                "title": "geoms_to_netcdf",
                "description": "Converts GEOMS hdf files to NetCDF, with CF conventions enabled",
                "method": "POST",
                "request": "geoms_to_netcdf"
            }
        },
        "geoms_qaqc": {
            "type": "url",
            "url": "https://api.aeronomie.be/api/runners/geoms_qaqc",
            "attributes": {
                "title": "geoms_qaqc",
                "description": "Runs the CAMS-27 quality checker on a GEOMS hdf file",
                "method": "POST",
                "request": "geoms_qaqc"
            }
        },
        "co2m": {
            "type": "url",
            "url": "https://api.aeronomie.be/api/runners/co2m/co2m_sites_db",
            "attributes": {
                "title": "co2m",
                "description": "OPeNDAP access to the station metadata shown on the co2m.aeronomie.be website",
                "method": "GET",
                "request": "co2m/co2m_sites_db{extension?}",
                "where": {
                    "extension": ".*"
                }
            }
        },
        "cams_opendap": {
            "type": "url",
            "url": "https://api.aeronomie.be/api/runners/cams_opendap",
            "attributes": {
                "title": "cams_opendap",
                "description": "OPeNDAP access to the detailed comparison results used in the CAMS2-82 validation workpackages, uses NDACC/SONDE/TCCON and COCCON data",
                "method": "GET",
                "request": "cams_opendap/{dapurl?}",
                "where": {
                    "dapurl": ".*"
                }
            }
        }
    }
}
Pick the service of your choice (e.g. cams_opendap) 
    $ curl https://api.aeronomie.be/api/runners/cams_opendap | jq . -
{
    "directories": [
        {
            "name": "evdc",
            "last_modified": "2023-07-12T07:26:15.191912+00:00"
        },
        {
            "name": "ndacc",
            "last_modified": "2023-05-04T13:47:17.452304+00:00"
        },
        {
            "name": "tccon",
            "last_modified": "2023-07-19T10:36:55.466030+00:00"
        }
    ],
    "files": []
}

Available data

cams_opendap

OPeNDAP access to the detailed comparison results used in the CAMS2-82 validation workpackages, uses NDACC/SONDE/TCCON and COCCON data
URL: /api/runners/cams_opendap/{dapurl?}
Fields
Example
 curl https://api.aeronomie.be/api/runners/cams_opendap/ndacc/ch4/ftir/ftir_ch4_ghgan.nc4  -O -J

co2m

OPeNDAP access to the station metadata shown on the co2m.aeronomie.be website
URL: /api/runners/co2m/{extension?}
Fields
Example
 curl "https://api.aeronomie.be/api/runners/co2m/co2m_sites_db"  -O -J

cp_l2

OPeNDAP access to L2 retrieval atmospheric data used in the ACTRIS Central Processor
URL: /api/runners/cp_l2/{dapurl?}
Fields
Example
 			
# Python example 1: requests
			
## List available prior files
			
import requests
			
print(requests.get('https://api.aeronomie.be/api/runners/cp_l2').json())
			
			
			
## Choose a site, request data for one day or one time as a simple json or a NCO json
			
instrument='bremen/bruker125HR'
			
print(requests.get(f'https://api.aeronomie.be/api/runners/cp_l2/{instrument}/O3.nc4.json?DATETIME,summary_FITRMS

cp_prior

OPeNDAP access to apriori atmospheric data used in the ACTRIS Central Processor
URL: /api/runners/cp_prior/{dapurl?}
Fields
Example
 				# Python example 1: requests
## List available prior files
import requests
print(requests.get('https://api.aeronomie.be/api/runners/cp_prior').json()) 
			
## Choose a site, request data for one day or one time as a simple json or a NCO json
site='jungfraujoch' 
print(requests.get(f'https://api.aeronomie.be/api/runners/cp_prior/{site}/ERA5T.nc4.json?H2O,T&time=\"2026-04-01"').json())
print(requests.get(f'https://api.aeronomie.be/api/runners/cp_prior/{site}/ERA5T.nc4.ncojson?H2O,T&time=\"2026-04-01%2008:00\"').json())
			
# Python example 2: xarray
## Get the unit of the time variable
tunit=requests.get(f'https://api.aeronomie.be/api/runners/cp_prior/{site}/ERA5T.nc4.ncoattrjson?time').json()['variables']['time']['attributes']['units']
print(tunit)
import cftime
t=cftime.date2num(cftime.datetime(2026,4,12,8),tunit) #convert time to a unit for the selection
## Select or slice on time
ds=xr.load_dataset(f'https://api.aeronomie.be/api/runners/cp_prior/{site}/ERA5T.nc4?H2O,T&time={t}')
ds=xr.load_dataset(f'https://api.aeronomie.be/api/runners/cp_prior/{site}/ERA5T.nc4?H2O,T&time>={t}')
			
## Directly slice on time with a string (experimental)
import xarray as xr;urllib
ds=xr.load_dataset(f'https://api.aeronomie.be/api/runners/cp_prior/{site}/ERA5T.nc4?H2O,T&time>'+urllib.parse.quote('"2026-04-01 08:00"'))
			
## Interpolate to your measurement time
ds.interp(time='2026-04-01 09:22',method='linear')
			
			
#Terminal example 1: list available sites & request data with http-client
curl -s  https://api.aeronomie.be/api/runners/cp_prior | jq ".directories[].name"
			
#terminal get one time and print H2O profile in a 8 column format
curl -s  --compressed "https://api.aeronomie.be/api/runners/cp_prior/jungfraujoch/ERA5T.nc4.json?H2O,T&time=\"2026-04-01%2008:00\"" | jq -r ".H2O[0] | _nwise(8) | @tsv"
			
# Terminal example 2: nccopy
nccopy  "https://api.aeronomie.be/api/runners/cp_prior/jungfraujoch/ERA5T.nc4?H2O,T&time>"$(echo '"2026-04-01 08:00"' | jq -Rr @uri) recent_era5t.nc4
ncdump -h recent_era5t.nc4
			
# Terminal example 3: download entire file
curl -s https://api.aeronomie.be/api/runners/cp_prior/jungfraujoch/ERA5T.nc4 -O -J

geoms_qaqc

Runs the CAMS-27 quality checker on a GEOMS hdf file
URL: /api/runners/geoms_qaqc
Fields
testfile
required
file
max:1024000
mimetypes:application/x-hdf,application/x-netcdf
Example
 curl -X POST -d --form testfile=@"yourLocalHDFfile.h5"  -H Accept: application/json https://api.aeronomie.be/api/runners/geoms_qaqc

geoms_to_netcdf

Converts GEOMS hdf files to NetCDF, with CF conventions enabled
URL: /api/runners/geoms_to_netcdf
Fields
testfile
required
file
max:1024000
mimetypes:application/x-hdf,application/x-netcdf
Example
 curl   --form testfile=@"yourLocalHDFfile.hdf" -H "Accept: application/json,application/x-netcdf4" https://api.aeronomie.be/api/runners/geoms_to_netcdf -O -J
Royal Belgian Institute for Space Aeronomy