How to use API (command line)

Introduction
Info about available models
Creating plots
Info on skimmed data

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

Table: Query parameters to create a tco3_zm plot (in bold are required parameters)
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

Table: Query parameters to create a tco3_return plot (in bold are required parameters)
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

Table: Query parameters for retrieving skimmed data used to build a tco3_zm plot (in bold are required parameters)
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

Table: Query parameters for retrieving skimmed data used to build a tco3_return plot (in bold are required parameters)
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"
]'