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 (30-year averages from 1991-2020) over a specified time range.

Climatology provides historical baseline values for each (month, 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 month 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.

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:

Body

application/json

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

Instead of specifying month/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 climatology values for January

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_byany ofOptional

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

Example: ["hourly"]

string[]Optional

or

nullOptional

timezoneany ofOptional

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

Example: UTC

stringOptional

or

nullOptional

aggregationany ofOptional

List of aggregation functions to apply when grouping (e.g., ['avg', 'std']). Requires 'group_by' to be specified.

or

nullOptional

order_byany ofOptional

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

Example: ["time"]

string[]Optional

or

nullOptional

paginationany ofOptional

Pagination parameters for limiting result size.

Example: {"limit":100,"offset":0}

or

nullOptional

weightingany ofOptional

Optional weighting scheme for geographic aggregation. Applies weighted averages based on capacity or population. Only valid with spatial aggregation (market_zone or country_key).

Example: {"type":"population"}

or

nullOptional

Responses

200

Successfully retrieved climatology data

application/jsonapplication/vnd.apache.arrow.stream

Responseany

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

401

Authentication required

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 months and hours

• List of variables

Authentication: Requires API key.

Authorizations

HTTPBearer

Responses

200

Successfully retrieved metadata

application/json

401

Authentication required

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": 721,
  "num_longitudes": 1440,
  "months": [
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10,
    11,
    12
  ],
  "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",
    "..."
  ]
}