Climatology

Query ERA5 WMO 30-year climatology data (1991-2020) for historical baselines.

Query climatology data over a time range

post

Query ERA5 WMO climatology data (smoothed 30-year daily averages from 1991-2020) over a specified time range.

Climatology provides historical baseline values for each (day_of_year, hour, latitude, longitude) combination, useful for:

• Comparing forecasts against historical norms

• Detecting anomalies in weather patterns

• Energy market baseline calculations

Time Range Query: Specify start_time and end_time to get climatology data for each hour in the range. The climatology values are matched by day of year and hour, then combined with the full datetime from your time range. This allows you to get a "typical" weather pattern for any date range based on historical averages.

Response Format: Use format=json or format=arrow to select the response explicitly. When format is omitted, Accept: application/vnd.apache.arrow.stream selects Arrow and all other requests retain the JSON default.

Query Dimensions:

• geo: Location filter (point, bounding_box, polygon, market_zone, country_key)

• start_time: Start of the time range (inclusive)

• end_time: End of the time range (exclusive)

• variables: Weather variables to retrieve

Time Aggregation: Use group_by to control time aggregation:

• hourly: Hourly resolution (default)

• daily: Daily averages

• weekly: Weekly averages

For daily/weekly aggregations, use timezone to specify the timezone for day/week boundaries (e.g., "Europe/Berlin"). Defaults to UTC if not specified.

Spatial Aggregation: Add market_zone, country_key, or point to group_by to preserve geographic dimensions. Use aggregation to specify the aggregation function (e.g., ["avg"]).

Response Formats:

• json: Columnar JSON format {column: [values], ...}

• arrow: Apache Arrow IPC stream for efficient processing

Authentication: Requires API key.

Billing: Free - no credit charges.

For more information, see docs.jua.ai.

Authorizations

HTTPBearer

Query parameters

formatstring · enumOptional

Response format: 'json' for columnar JSON or 'arrow' for Apache Arrow format

Default: jsonPossible values:

include_unitsbooleanOptional

When true, JSON responses are wrapped in {data, units}. Units are always sent via X-Variable-Units header regardless.

Default: false

Body

application/json

Query for retrieving ERA5 WMO climatology data over a time range.

Instead of specifying day_of_year/hour directly, provide a time range (start_time, end_time) and the query will return climatology data matched to each hour in the range. The response includes a 'time' column with the full datetime values.

Example: python query = TimeRangeClimatologyQuery( geo={"type": "point", "value": [(52.52, 13.405)]}, start_time=datetime(2024, 1, 15, 0, 0, 0), end_time=datetime(2024, 1, 16, 0, 0, 0), variables=["air_temperature_at_height_level_2m"], ) # Returns 24 hourly rows with daily-smoothed climatology values

start_timestring · date-timeRequired

Start time for the climatology query (inclusive). UTC timezone.

end_timestring · date-timeRequired

End time for the climatology query (exclusive). UTC timezone.

group_bystring[] · nullableOptional

List of dimensions to group by for aggregation. Time aggregation options: 'hourly', 'daily', 'weekly'. Other valid fields: 'market_zone', 'country_key', 'point'.

Example: ["hourly"]

timezonestring · nullableOptional

Timezone for time-based aggregations (daily, weekly). If not specified, UTC is used. Example: 'Europe/Berlin'.

Example: UTC

order_bystring[] · nullableOptional

List of dimensions to sort results by. Use 'time' for time-based ordering.

Example: ["time"]

Responses

200

Successfully retrieved climatology data

application/jsonapplication/vnd.apache.arrow.stream

anyOptional

400

Invalid query parameters

401

Authentication required

403

Insufficient permissions

422

Validation Error

application/json

post/v1/climatology/data

HTTPcURLJavaScriptPython

POST /v1/climatology/data HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 222

{
  "geo": {
    "type": "point",
    "value": [
      [
        52.52,
        13.405
      ]
    ],
    "method": "nearest"
  },
  "start_time": "2024-01-15T00:00:00Z",
  "end_time": "2024-01-16T00:00:00Z",
  "variables": [
    "air_temperature_at_height_level_2m",
    "wind_speed_at_height_level_10m"
  ]
}

Query single point for one dayQuery single point for one weekMarket zone queryDaily aggregation queryWeekly aggregation query

{
  "time": [
    "2024-01-15T00:00:00Z",
    "2024-01-15T01:00:00Z",
    "2024-01-15T02:00:00Z"
  ],
  "latitude": [
    52.5,
    52.5,
    52.5
  ],
  "longitude": [
    13.5,
    13.5,
    13.5
  ],
  "air_temperature_at_height_level_2m": [
    271.5,
    271.2,
    270.8
  ]
}

List available climatology variables

get

Get a list of weather variables available in the ERA5 climatology dataset.

These variables represent 30-year averages (1991-2020) computed from ERA5 reanalysis data.

Authentication: Requires API key.

Authorizations

HTTPBearer

Responses

200

Successfully retrieved variable list

application/json

Result containing available climatology variables.

401

Authentication required

422

Validation Error

application/json

get/v1/climatology/variables

HTTPcURLJavaScriptPython

GET /v1/climatology/variables HTTP/1.1
Accept: */*

{
  "variables": [
    {
      "name": "air_temperature_at_height_level_2m",
      "description": "Air temperature at 2m height"
    },
    {
      "name": "wind_speed_at_height_level_10m",
      "description": "Wind speed at 10m height"
    }
  ]
}

Get climatology dataset metadata

get

Get metadata about the ERA5 WMO climatology dataset including:

• Grid resolution and dimensions

• Available days of year and hours

• List of variables

Authentication: Requires API key.

Authorizations

HTTPBearer

Responses

200

Successfully retrieved metadata

application/json

Metadata about the climatology dataset.

descriptionstringRequired

periodstringRequired

grid_resolutionstringRequired

num_latitudesintegerRequired

num_longitudesintegerRequired

days_of_yearinteger[]Required

hoursinteger[]Required

variablesstring[]Required

401

Authentication required

422

Validation Error

application/json

get/v1/climatology/meta

HTTPcURLJavaScriptPython

GET /v1/climatology/meta HTTP/1.1
Accept: */*

{
  "description": "ERA5 WMO 30-year climatology (1991-2020)",
  "period": "1991-2020",
  "grid_resolution": "0.25° x 0.25°",
  "num_latitudes": 720,
  "num_longitudes": 1440,
  "days_of_year": [
    1,
    2,
    3,
    4,
    5
  ],
  "hours": [
    0,
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10,
    11,
    12,
    13,
    14,
    15,
    16,
    17,
    18,
    19,
    20,
    21,
    22,
    23
  ],
  "variables": [
    "air_temperature_at_height_level_2m",
    "..."
  ]
}