How to use API (command line)
Introduction
This HowTo demonstrates basic communication with the O3as API by using cURL tool. Though cURL is a command-line tool, libcurl library is implemented in many programming languages (e.g. pycurl for Python). The examples below could also help understanding how the API calls can be implemented in your program using other means (e.g. urllib in Python).
Note
O3as API is based on the Open API 3 and Swagger, which provides Swagger UI, visual documentation allowing to interact with the API in a friendly way via web. The O3AS API Swagger UI webpage is accessible at https://api.o3as.fedcloud.eu/api/v1/ui/.
Tip
For the complete description of the REST API, please, check O3API Endpoints and https://api.o3as.fedcloud.eu/api/v1/ui/.
Info about available models
Get list of all available models
curl -X 'GET' 'https://api.o3as.fedcloud.eu/api/v1/models' -H 'accept: application/json'
List models with a certain pattern
e.g select models with ‘refC2’ in the name:
curl -X 'GET' \
'https://api.o3as.fedcloud.eu/api/v1/models?select=refc2' \
-H 'accept: application/json'
Get information about a particular model
e.g. about CCMI-1_ACCESS_ACCESS-CCM-refC2:
curl -X 'GET' \
'https://api.o3as.fedcloud.eu/api/v1/models/CCMI-1_ACCESS_ACCESS-CCM-refC2' \
-H 'accept: application/json'
Get default plot styles of selected models
e.g for CCMI-1_ACCESS_ACCESS-CCM-refC2
, CCMI-1_CCCma_CMAM-refC2
, CCMI-1_CHASER-MIROC-ESM-refC2
curl -X 'POST' \
'https://api.o3as.fedcloud.eu/api/v1/models/plotstyle' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
"CCMI-1_ACCESS_ACCESS-CCM-refC2",
"CCMI-1_CCCma_CMAM-refC2",
"CCMI-1_CHASER-MIROC-ESM-refC2"
]'
Creating plots
Get list of possible plots
curl -X 'GET' \
'https://api.o3as.fedcloud.eu/api/v1/plots' \
-H 'accept: application/json'
Create tco3_zm plot
This example shows how to retrieve a total column ozone (zonal mean) figure either in PDF or JSON format. The query parameters used in the example are shown in the table below.
Tip
For the explanation of parameters, please, check O3API Endpoints
Query parameter |
Value |
---|---|
begin |
1959 |
end |
2100 |
month |
[9,10,11] |
lat_min |
-90 |
lat_max |
90 |
ref_meas |
SBUV_GSFC_merged-SAT-ozone |
ref_year |
1980 |
Request body (for the list of models) |
e.g. all refC2 models |
Example for PDF (tco3_zm.pdf
is created)
curl -o tco3_zm.pdf -X 'POST' \
'https://api.o3as.fedcloud.eu/api/v1/plots/tco3_zm?begin=1959&end=2100&month=9,10,11&lat_min=-90&lat_max=90&ref_meas=SBUV_GSFC_merged-SAT-ozone&ref_year=1980' \
-H 'accept: application/pdf' \
-H 'Content-Type: application/json' \
-d '[
"CCMI-1_ACCESS_ACCESS-CCM-refC2",
"CCMI-1_CCCma_CMAM-refC2",
"CCMI-1_CESM1-CAM4Chem_refC2_r1i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r2i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r3i1p1",
"CCMI-1_CESM1-WACCM_refC2_r1i1p1",
"CCMI-1_CESM1-WACCM_refC2_r2i1p1",
"CCMI-1_CESM1-WACCM_refC2_r3i1p1",
"CCMI-1_CHASER-MIROC-ESM-refC2",
"CCMI-1_CNRM-CERFACS_CNRM-CM5-3-refC2",
"CCMI-1_CNRM-CERFACS_MOCAGE-refC2",
"CCMI-1_ETH-PMOD_SOCOL3-refC2",
"CCMI-1_GSFC_GEOSCCM-refC2",
"CCMI-1_MESSy_EMAC-L90MA-refC2",
"CCMI-1_MOHC_HadGEM3-ES-refC2",
"CCMI-1_MRI_ESM1r1-refC2",
"CCMI-1_NIES_CCSRNIES-MIROC3.2-refC2",
"CCMI-1_NIWA_NIWA-UKCA-refC2",
"CCMI-1_U-CAMBRIDGE_UMUKCA-UCAM-refC2",
"CCMI-1_U-LAQUILA_CCM-refC2",
"CCMI-1_U-LEEDS_UMSLIMCAT-refC2"
]'
Example for JSON (tco3_zm.json
is created)
curl -o tco3_zm.json -X 'POST' \
'https://api.o3as.fedcloud.eu/api/v1/plots/tco3_zm?begin=1959&end=2100&month=9,10,11&lat_min=-90&lat_max=90&ref_meas=SBUV_GSFC_merged-SAT-ozone&ref_year=1980' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
"CCMI-1_ACCESS_ACCESS-CCM-refC2",
"CCMI-1_CCCma_CMAM-refC2",
"CCMI-1_CESM1-CAM4Chem_refC2_r1i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r2i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r3i1p1",
"CCMI-1_CESM1-WACCM_refC2_r1i1p1",
"CCMI-1_CESM1-WACCM_refC2_r2i1p1",
"CCMI-1_CESM1-WACCM_refC2_r3i1p1",
"CCMI-1_CHASER-MIROC-ESM-refC2",
"CCMI-1_CNRM-CERFACS_CNRM-CM5-3-refC2",
"CCMI-1_CNRM-CERFACS_MOCAGE-refC2",
"CCMI-1_ETH-PMOD_SOCOL3-refC2",
"CCMI-1_GSFC_GEOSCCM-refC2",
"CCMI-1_MESSy_EMAC-L90MA-refC2",
"CCMI-1_MOHC_HadGEM3-ES-refC2",
"CCMI-1_MRI_ESM1r1-refC2",
"CCMI-1_NIES_CCSRNIES-MIROC3.2-refC2",
"CCMI-1_NIWA_NIWA-UKCA-refC2",
"CCMI-1_U-CAMBRIDGE_UMUKCA-UCAM-refC2",
"CCMI-1_U-LAQUILA_CCM-refC2",
"CCMI-1_U-LEEDS_UMSLIMCAT-refC2"
]'
Create tco3_return plot
The example shows how to retrieve a total column ozone (return years) figure either in PDF or JSON format. The query parameters used in the example are shown in the table below.
Tip
For the explanation of parameters, please, check O3API Endpoints
Query parameter |
Value |
---|---|
month |
[9,10,11] |
lat_min |
-90 |
lat_max |
90 |
ref_meas |
SBUV_GSFC_merged-SAT-ozone |
ref_year |
1980 |
Request body (for the list of models) |
e.g. all refC2 models |
Example for PDF (tco3_return.pdf
is created)
curl -o tco3_return.pdf -X 'POST' \
'https://api.o3as.fedcloud.eu/api/v1/plots/tco3_return?month=9,10,11&lat_min=-90&lat_max=90&ref_meas=SBUV_GSFC_merged-SAT-ozone&ref_year=1980' \
-H 'accept: application/pdf' \
-H 'Content-Type: application/json' \
-d '[
"CCMI-1_ACCESS_ACCESS-CCM-refC2",
"CCMI-1_CCCma_CMAM-refC2",
"CCMI-1_CESM1-CAM4Chem_refC2_r1i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r2i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r3i1p1",
"CCMI-1_CESM1-WACCM_refC2_r1i1p1",
"CCMI-1_CESM1-WACCM_refC2_r2i1p1",
"CCMI-1_CESM1-WACCM_refC2_r3i1p1",
"CCMI-1_CHASER-MIROC-ESM-refC2",
"CCMI-1_CNRM-CERFACS_CNRM-CM5-3-refC2",
"CCMI-1_CNRM-CERFACS_MOCAGE-refC2",
"CCMI-1_ETH-PMOD_SOCOL3-refC2",
"CCMI-1_GSFC_GEOSCCM-refC2",
"CCMI-1_MESSy_EMAC-L90MA-refC2",
"CCMI-1_MOHC_HadGEM3-ES-refC2",
"CCMI-1_MRI_ESM1r1-refC2",
"CCMI-1_NIES_CCSRNIES-MIROC3.2-refC2",
"CCMI-1_NIWA_NIWA-UKCA-refC2",
"CCMI-1_U-CAMBRIDGE_UMUKCA-UCAM-refC2",
"CCMI-1_U-LAQUILA_CCM-refC2",
"CCMI-1_U-LEEDS_UMSLIMCAT-refC2"
]'
Example for JSON (tco3_return.json
is created)
curl -o tco3_return.json -X 'POST' \
'https://api.o3as.fedcloud.eu/api/v1/plots/tco3_return?month=9,10,11&lat_min=-90&lat_max=90&ref_meas=SBUV_GSFC_merged-SAT-ozone&ref_year=1980' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
"CCMI-1_ACCESS_ACCESS-CCM-refC2",
"CCMI-1_CCCma_CMAM-refC2",
"CCMI-1_CESM1-CAM4Chem_refC2_r1i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r2i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r3i1p1",
"CCMI-1_CESM1-WACCM_refC2_r1i1p1",
"CCMI-1_CESM1-WACCM_refC2_r2i1p1",
"CCMI-1_CESM1-WACCM_refC2_r3i1p1",
"CCMI-1_CHASER-MIROC-ESM-refC2",
"CCMI-1_CNRM-CERFACS_CNRM-CM5-3-refC2",
"CCMI-1_CNRM-CERFACS_MOCAGE-refC2",
"CCMI-1_ETH-PMOD_SOCOL3-refC2",
"CCMI-1_GSFC_GEOSCCM-refC2",
"CCMI-1_MESSy_EMAC-L90MA-refC2",
"CCMI-1_MOHC_HadGEM3-ES-refC2",
"CCMI-1_MRI_ESM1r1-refC2",
"CCMI-1_NIES_CCSRNIES-MIROC3.2-refC2",
"CCMI-1_NIWA_NIWA-UKCA-refC2",
"CCMI-1_U-CAMBRIDGE_UMUKCA-UCAM-refC2",
"CCMI-1_U-LAQUILA_CCM-refC2",
"CCMI-1_U-LEEDS_UMSLIMCAT-refC2"
]'
Info on skimmed data
o3skim component produces skimmed data which are further processed by the o3api to build plots for the Ozone assessment (e.g. total column ozone (zonal mean) and total column ozone (return years)).
Get list of plot types with the available skimmed data
curl -X 'GET' 'https://api.o3as.fedcloud.eu/api/v1/data' -H 'accept: application/json'
Get skimmed data used to build tco3_zm plot
Tip
For the explanation of parameters, please, check O3API Endpoints
Query parameter |
Value |
---|---|
begin |
1959 |
end |
2100 |
month |
[9,10,11] |
lat_min |
-90 |
lat_max |
90 |
Request body (for the list of models) |
e.g. all refC2 models |
tco3_zm_skimmed.json
is created:
curl -o tco3_zm_skimmed.json -X 'POST' \
'https://api.o3as.fedcloud.eu/api/v1/data/tco3_zm?begin=1959&end=2100&month=9,10,11&lat_min=-90&lat_max=90' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
"CCMI-1_ACCESS_ACCESS-CCM-refC2",
"CCMI-1_CCCma_CMAM-refC2",
"CCMI-1_CESM1-CAM4Chem_refC2_r1i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r2i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r3i1p1",
"CCMI-1_CESM1-WACCM_refC2_r1i1p1",
"CCMI-1_CESM1-WACCM_refC2_r2i1p1",
"CCMI-1_CESM1-WACCM_refC2_r3i1p1",
"CCMI-1_CHASER-MIROC-ESM-refC2",
"CCMI-1_CNRM-CERFACS_CNRM-CM5-3-refC2",
"CCMI-1_CNRM-CERFACS_MOCAGE-refC2",
"CCMI-1_ETH-PMOD_SOCOL3-refC2",
"CCMI-1_GSFC_GEOSCCM-refC2",
"CCMI-1_MESSy_EMAC-L90MA-refC2",
"CCMI-1_MOHC_HadGEM3-ES-refC2",
"CCMI-1_MRI_ESM1r1-refC2",
"CCMI-1_NIES_CCSRNIES-MIROC3.2-refC2",
"CCMI-1_NIWA_NIWA-UKCA-refC2",
"CCMI-1_U-CAMBRIDGE_UMUKCA-UCAM-refC2",
"CCMI-1_U-LAQUILA_CCM-refC2",
"CCMI-1_U-LEEDS_UMSLIMCAT-refC2"
]'
Get skimmed data used to build tco3_return plot
Tip
For the explanation of parameters, please, check O3API Endpoints
Query parameter |
Value |
---|---|
begin |
1959 |
end |
2100 |
month |
[9,10,11] |
lat_min |
-90 |
lat_max |
90 |
Request body (for the list of models) |
e.g. all refC2 models |
tco3_return_skimmed.json
is created:
curl -o tco3_return_skimmed.json -X 'POST' \
'https://api.o3as.fedcloud.eu/api/v1/data/tco3_return?begin=1959&end=2100&month=9,10,11&lat_min=-90&lat_max=90' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
"CCMI-1_ACCESS_ACCESS-CCM-refC2",
"CCMI-1_CCCma_CMAM-refC2",
"CCMI-1_CESM1-CAM4Chem_refC2_r1i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r2i1p1",
"CCMI-1_CESM1-CAM4Chem_refC2_r3i1p1",
"CCMI-1_CESM1-WACCM_refC2_r1i1p1",
"CCMI-1_CESM1-WACCM_refC2_r2i1p1",
"CCMI-1_CESM1-WACCM_refC2_r3i1p1",
"CCMI-1_CHASER-MIROC-ESM-refC2",
"CCMI-1_CNRM-CERFACS_CNRM-CM5-3-refC2",
"CCMI-1_CNRM-CERFACS_MOCAGE-refC2",
"CCMI-1_ETH-PMOD_SOCOL3-refC2",
"CCMI-1_GSFC_GEOSCCM-refC2",
"CCMI-1_MESSy_EMAC-L90MA-refC2",
"CCMI-1_MOHC_HadGEM3-ES-refC2",
"CCMI-1_MRI_ESM1r1-refC2",
"CCMI-1_NIES_CCSRNIES-MIROC3.2-refC2",
"CCMI-1_NIWA_NIWA-UKCA-refC2",
"CCMI-1_U-CAMBRIDGE_UMUKCA-UCAM-refC2",
"CCMI-1_U-LAQUILA_CCM-refC2",
"CCMI-1_U-LEEDS_UMSLIMCAT-refC2"
]'