Odin/SMR Data Access

Introduction

The primary way of accessing data from the Odin/SMR mission is through the Odin/SMR web-API. Data is also available for download as NetCDF files, accessible at http://odin-l2netcdf.s3-website.eu-north-1.amazonaws.com/.

The Odin web-API is a so called REST API, where the user makes a GET request to an API-endpoint, a URI provided by the API. The result of the request is a so called JSON-object. JSON is a text-based data exchange standard with key-value pairs, which can be interpreted by most modern programming languages, including MATLAB and Python. For instance, in Python the JSON structure is mapped to a so called dictionary object.

While the API can be accessed directly in a web browser, this is not recommended. The user will typically access the data by making requests using a script or computer program, some examples of which are given below.

The root URI of the API is http://odin.rss.chalmers.se/rest_api/v5. In the following, endpoints will be described relative to this root.

Data format specification

The various data structures that are returned by the API and used in the NetCDF files are documented in these PDF documents:

• Algorithm Theoretical Basis Document: Level 1 Processing,
• Level 2 Data - Format and overview.

Endpoints for data access

Since the Level 1 data requires specialised knowledge about the Odin/SMR instrument, only access to the Level 2 data is covered here. For information on how to access Level 1 data, please see the L1 ATBD.

Getting project information

The Level 2 data sets are organised under "projects". To get a list of available projects, a request to the /level2/projects/ endpoint is made. General information about a particular project can then be acquired by a request to the /level2/{project}/ endpoint, where {project} is a project name from the project list.

Each project may contain a number of different data products. To get a list of the available products for a given project, make a request to the /level2/{project}/products/ endpoint. The main entry points for getting data from the API are the locations, area and date endpoints, introduced below.

Example query for project ALL-Strat-v3.0.0:

/level2/ALL-Strat-v3.0.0/products/

Python code example:

import requests

API_ROOT = "http://odin.rss.chalmers.se/rest_api/v5"
PROJECTS_ENDPOINT = "/level2/projects/"
PRODUCTS_ENDPOINT = "/level2/{project}/products/"


def get_projects():
    """Function for getting projects from the Odin REST API"""

    # Construct request URI:
    request_url = API_ROOT + PROJECTS_ENDPOINT

    # Get data:
    response = requests.get(request_url)

    # Return data:
    return response.json()


def get_products(project="ALL-Strat-v3.0.0"):
    """Function for getting products from the Odin REST API"""

    # Construct request URI:
    request_url = API_ROOT + PRODUCTS_ENDPOINT.format(project=project)

    # Get data:
    response = requests.get(request_url)

    # Return data:
    return response.json()


PROJECTS = get_projects()
PRODUCTS = get_products("ALL-Strat-v3.0.0")

Look up data by location

The locations endpoint lets you filter data to within a specified radius (km) around one or more locations. The endpoint also requires the user to specify a date limit and one of either a pressure or an altitude interval. If one or more products are specified, only data for these will be returned, otherwise data for all available data products will be returned. This endpoint is using pagination. Thus, a single request to this endpoint does not necessarily return all data matching your filter, but in this case the response contains information about where you can get next page of data, as shown in the Python code example below.

The locations endpoint is located at /level2/{project}/locations.

Please note the lack of a trailing / in this endpoint.

Example query for project ALL-Strat-v3.0.0, product O3 / 545 GHz / 20 to 85 km at a single location:

/level2/ALL-Strat-v3.0.0/locations?product=O3%20%2F%20545%20GHz%20%2F%2020%20to%2085%20km&min_altitude=20000&max_altitude=85000&start_time=2015-01-03&end_time=2015-01-04&radius=2600&location=90,0

Python code example:

import requests

API_ROOT = "http://odin.rss.chalmers.se/rest_api/v5"
LOCATIONS_ENDPOINT = "/level2/ALL-Strat-v3.0.0/locations"


def get_arctic_ozone(start_date, end_date):
    """Function for getting ozone data from the Odin REST API"""

    # Set up parameters:
    parameters = {
        "product": "O3 / 545 GHz / 20 to 85 km",
        "location": "90,0",
        "radius": 2600,
        "min_altitude": 20000,
        "max_altitude": 85000,
        "start_time": start_date,
        "end_time": end_date,
    }

    # Construct request URI:
    request_url = API_ROOT + LOCATIONS_ENDPOINT

    # Get data:
    response = requests.get(request_url, params=parameters)
    data = [response.json()]

    # Note that this endpoint is paginated,
    # and the loop below retrieves data from all pages:
    while "next" in response.links:
        response = requests.get(response.links["next"]["url"])
        data.append(response.json())

    return data


DATA = get_arctic_ozone("2015-01-03", "2015-01-04")

Look up data by area

The area endpoint lets you filter data to within a specified area bounded by latitude and/or longitude limits. The endpoint also requires the user to specify a date limit and one of either a pressure or an altitude interval. If one or more products are specified, only data for these will be returned, otherwise data for all available data products will be returned. The area endpoint is, as the locations endpoint, using pagination.

The area endpoint is located at /level2/{project}/area.

Please note the lack of a trailing / in this endpoint.

Example query for project ALL-Strat-v3.0.0, product O3 / 545 GHz / 20 to 85 km for equatorial latitudes:

/level2/ALL-Strat-v3.0.0/area?product=O3%20%2F%20545%20GHz%20%2F%2020%20to%2085%20km&min_pressure=0&max_pressure=100000&start_time=2015-01-03&end_time=2015-01-04&min_lat=-5&max_lat=5

Python code example:

import requests

API_ROOT = "http://odin.rss.chalmers.se/rest_api/v5"
AREA_ENDPOINT = "/level2/ALL-Strat-v3.0.0/area"


def get_equatorial_ozone(start_date, end_date):
    """Function for getting ozone data from the Odin REST API"""

    # Set up parameters:
    parameters = {
        "product": "O3 / 545 GHz / 20 to 85 km",
        "min_lat": -5,
        "max_lat": 5,
        "min_altitude": 20000,
        "max_altitude": 85000,
        "start_time": start_date,
        "end_time": end_date,
    }

    # Construct request URI:
    request_url = API_ROOT + AREA_ENDPOINT

    # Get data:
    response = requests.get(request_url, params=parameters)
    data = [response.json()]

    # Note that this endpoint is paginated,
    # and the loop below retrieves data from all pages:
    while "next" in response.links:
        response = requests.get(response.links["next"]["url"])
        data.append(response.json())

    return data


DATA = get_equatorial_ozone("2015-01-03", "2015-01-04")

Look up data by date

The date endpoint lets you access data for a single day. The endpoint also requires the user to specify one of either a pressure or a altitude interval. If one or more products are specified, only data for these will be returned, otherwise data for all available data products will be returned.

The date endpoint is located at /level2/{project}/{date}/ where {date} should be replaced with a date on the format YYYY-MM-DD.

Example query for project ALL-Strat-v3.0.0, product O3 / 545 GHz / 20 to 85 km:

/level2/ALL-Strat-v3.0.0/2015-01-03/?product=O3%20%2F%20545%20GHz%20%2F%2020%20to%2085%20km&min_pressure=10&max_pressure=100000

Python code example:

import requests

API_ROOT = "http://odin.rss.chalmers.se/rest_api/v5"
DATE_ENDPOINT = "/level2/ALL-Strat-v3.0.0/{date}/"


def get_ozone_on_date(date_string):
    """Function for getting ozone data from the Odin REST API"""

    # Set up parameters:
    parameters = {
        "product": "O3 / 545 GHz / 20 to 85 km",
        "min_altitude": 20000,
        "max_altitude": 85000,
    }

    # Construct request URI:
    request_url = API_ROOT + DATE_ENDPOINT.format(date=date_string)

    # Get data:
    response = requests.get(request_url, params=parameters)

    # Return data:
    return response.json()


DATA = get_ozone_on_date("2015-01-03")

Other endpoints

Documentation for all endpoints available through the API is available in the API documentation.

There is also a dedicated API for the Verification Data Set, a data set used to compare Odin/SMR data with data from other instruments. This API is described in detail in the Odin/SMR Verification Dataset: Technical Note. The code example from the appendix is available for download below for convience.

Downloadable examples

For most users the Level 2 data – consisting mainly of atmospheric profiles of different species concentrations at different locations – will be of most interest. An example of a Python program for accessing the Level 2 API can be downloaded here.

The Level 1 data consists of the spectra used in calculating the Level 2 profiles. An example Python program for accessing the Level 1 spectra can be downloaded here.

The Verification Data Set API provides functionality for comparing Odin/SMR data with data from other instruments. An example Python script illustrating its use can be dowloaded here.

Recommended projects and products

The recommended projects and products to use for the different species are listed in the table below. For instance, to access the ozone profiles for the date 2015-01-03 you could make a call to the following URI:

http://odin.rss.chalmers.se/rest_api/v5/level2/ALL-Strat-v3.0.0/2015-01-03/?product=O3%20%2F%20545%20GHz%20%2F%2020%20to%2085%20km&min_pressuree=0&max_pressure=100000

Note that all spaces in the product names need to be replaced by %20 in the request.

For a detailed discussion of the different products, see the Odin/SMR Product Validation and Evolution Report.