1. Introduction

Oikolab has processed hundreds of terabytes of data to give you access this data in seconds rather than hours, whether you require 1 month or 70 years of historical data so that you can focus on your analysis rather than downloading and processing raw data.

1.1 What is reanalysis?

Climate reanalyses combine vast observations from satellites, aircraft, land and sea based weather sensors with atmospheric models to generate consistent time series of multiple climate variables. ERA5 is the latest climate reanalysis produced by ECMWF, providing hourly data on many atmospheric, land-surface and sea-state parameters, on regular latitude-longitude grids at 0.25^o x 0.25^o lat/lon resolution.

1.2 Our Datasets

We're always expanding our datasets - please reach out to us if you have needs for datasets that we don't currently have.

*Coming soon

2. Weather Data (/weather)

2.1 Request

Remember to use your own api_key.

import requests

r = requests.get('https://api.oikolab.com/weather',
                 params={'param': ['temperature','wind_speed'],
                         'start': '2010-01-01',
                         'end': '2018-12-31',
                         'lat': 43.6529,
                         'lon': -79.3849,
                         'api-key': 'your_api_key_here'}
                 )

We've designed the API to be as intuitive as possible.

The data is accessed through REST API by specifying the location, parameters and the time-range of the data needed. In this example, we are using the Python requests library to get temperature and wind_speed (at 10m height) between January 1, 2010 to December 31, 2018.

The following table shows the parameters that can be used to query weather data.

2.2 Response

The above command returns JSON data structured like this:

{'attributes': {
                'processing_time': 1.527,
                'n_parameter_months': 851,
                'gfs_reference_time': '2021-05-17 12 UTC',
                'next_gfs_update': 'in 2.0 hours (approx)',
                 },
  'data': '{"columns": ["temperature (degC)","wind_speed (m/s)"],
                       "index":[1262304000,1262307600,... ],
                       "data":[[16.59,7.61],[16.44,7.79]...]
          }'
}

The returned data in JSON format (default) will have two parts. The first, attributes, contains the meta-data about the response. The data part contains the weather and climate data, organized index, columns, and data, for easy conversion to dataframe. Note that with each respone, we provide the number of units (n_parameter_months) of the API request.

With json and pandas libraries, we can easily conver the JSON format to dataframe.

import json
import pandas as pd

weather_data = json.loads(r.json()['data'])
df = pd.DataFrame(index=pd.to_datetime(weather_data['index'],
                                       unit='s'),
                  data=weather_data['data'],
                  columns=weather_data['columns'])

The data can be easily coverted to Pandas DataFrame, when converted, will look like this:

78888 rows × 2 columns

Please note that the timestamp is UTC and utc_offset is in hours. The 'model elevation (surface) (m)' refers to the model surface elevation (calculated from geopotential value of the dataset) above mean sea level and may differ from actual surface elevation.

2.3 Available Parameters

Available parameters are shown below, grouped into major categories for ease of reference. Please note that some parameters are only available for ERA5 (historical) data.

Group 1: Temperature

*Available for ERA5-Land

Group 2: Wind

*Available for ERA5-Land

Group 3: Radiation

Radiation parameters are accumulated values based on the previous time step, typically one hour or 3 hours in the case of 5 to 16 day forecast. ERA5 reanalysis values are originally provided in J/m² and have been converted to W/m².

*Available for ERA5-Land

Group 4: Pressure, Humidity & Precipitation

Precipitation parameters are accumulated values based on the previous time step, typically one hour or 3 hours in the case of 5 to 16 day forecast. Original values provided in kg/m² of water equivalent have been converted to mm of water equivalent.

*Available for ERA5-Land

Group 5: Advanced Parameters

The following parameters are available for Enterprise plans.

3. Archived Forecast (/archivedforecast)

The GFS forecast data is archived up to 2 years (available from March, 2021).

3.1 Request

Remember to use your own api_key.

import requests

r = requests.get('https://api.oikolab.com/archivedforecast',
                 params={'param': ['temperature',],
                         'utc_cycle': '2022-05-18',
                         'lat': 23.1,
                         'lon': 114.1,
                         'api-key': 'your_api_key_here'}
                 )

GFS forecasts are archived for up to 180 days.

3.2 Response

The response will be the same as the weather API (/weather).

3.3 Available Parameters

Parameters that are available for GFS data are available for archived forecast API.

4. Ensemble Forecast (/ensembleforecast)

We provide summary data from the GFS Ensemble Forecast (GEFS). GEFS runs 30 separate member runs with slight variations in the initial condition.

4.1 Request

Remember to use your own api-key.

import requests

r = requests.get('https://api.oikolab.com/ensembleforecast',
                 params={'param': ['temperature',],
                         'lat': 23.1,
                         'lon': 114.1,
                         'api-key': 'your_api_key_here'}
                 )

4.2 Response

For each parameter, there will be three columns of data, one for ensemble average (_ens_avg suffix), one for control member (_ens_c00 suffix), and for the ensemble spread (_ens_spr suffix), as shown below.

4.3 Available Parameters

5. Seasonal Forecast (/seasonalforecast)

5.1 Request

Remember to use your own api_key.

import requests

r = requests.get('https://api.oikolab.com/seasonalforecast',
                 params={'param': ['temperature',],
                         'lat': 23.1,
                         'lon': 114.1,
                         'api-key': '<your_api_key_here>'}
                 )

5.2 Response

5.3 Available Parameters

6. Air Quality Forecast (/airquality)

This is air quality data from the the System for Integrated modeLling of Atmospheric coMposition (SILAM) dataset from FMI, with 20km, hourly coverage with up to 5 days forecast.

6.1 Request

Remember to use your own api_key.

import requests

r = requests.get('https://api.oikolab.com/airquality',
                 params={'lat': 52.378,
                         'lon': 4.9,
                         'api-key': 'your_api_key_here'}
                 )

6.2 Response

6.3 Available Parameters

5. Frequently Asked Questions

How do I download data?

Many researchers are more familiar with Excel than Python or R programming languages. We've recently added the ability to download data in CSV format which can be processed by Excel or Google Spreadsheet.

Don't see the parameters you need?

Please reach out to us at [email protected] - we'd be more than happy to help.