Reanalysis

Query reanalysis data from models like ARCO ERA5 for historical weather analysis.

Query reanalysis data

post

Query reanalysis data from models like ARCO ERA5.

Reanalysis data provides historical weather analysis at a specific time (unlike forecasts which have init_time + prediction_timedelta dimensions). This is useful for:

• Historical weather analysis

• Training and validating machine learning models

• Comparing forecasts against actuals

Query Dimensions:

• models: Reanalysis model(s) to query (e.g., ["arco_era5"])

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

• time: Time(s) to query - "latest", single datetime, list of datetimes, or time range

• variables: Weather variables to retrieve

Response Formats:

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

• arrow: Apache Arrow IPC stream for efficient processing

Authentication: Requires API key.

For more information, see docs.jua.ai.

Authorizations

HTTPBearer

Query parameters

formatstring · enumOptional

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

Default: jsonPossible values:

streambooleanOptional

If true, stream the response as an Apache Arrow IPC stream. Overrides 'format' to 'arrow'.

Default: false

request_credit_limitnumberOptional

Maximum credits allowed for this request. Query will fail if estimated cost exceeds this limit

Default: 50

Body

application/json

Query object for retrieving reanalysis data.

Reanalysis data uses a simple time dimension (unlike forecasts which have init_time + prediction_timedelta). This provides historical analysis data at specified timestamps.

Example: python query = ReanalysisQuery( models=["arco_era5"], geo={"type": "point", "value": [(52.52, 13.405)]}, time={"start": "2024-01-01T00:00:00Z", "end": "2024-01-07T00:00:00Z"}, variables=["air_temperature_at_height_level_2m"], )

timeany ofRequired

Time(s) to query. Can be 'latest', a single datetime, a list of datetimes, or a TimeSlice range.

Example: latest

string · date-timeOptional

or

string · date-time[]Optional

or

or

const: latestOptional

group_byany ofOptional

List of dimensions to group by for aggregation (e.g., ['model', 'time']). Requires 'aggregation' to be specified.

or

nullOptional

order_byany ofOptional

List of dimensions to sort results by. Supports direction suffix: 'time__desc' for descending, 'time__asc' for ascending (default). Can also use object format: {'field': 'time', 'direction': 'desc'}

Example: ["model","time"]

or

nullOptional

aggregationany ofOptional

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

or

nullOptional

weightingany ofOptional

Optional weighting scheme for geographic aggregation (e.g., by wind/solar capacity or population)

Example: {"type":"wind_capacity"}

or

nullOptional

include_timebooleanOptional

Include the time column in results (default: True)

Default: true

time_zoneany ofOptional

IANA time zone name for time formatting (e.g., 'Europe/Berlin', 'America/New_York'). Defaults to UTC

Example: UTC

stringOptional

or

nullOptional

paginationany ofOptional

Pagination parameters for limiting result size. Requires 'order_by' to be specified

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

or

nullOptional

were_variables_explicitly_requestedbooleanOptional

Whether the user passed the variables explicitly. If True, the variables will be used to filter the results. If False, all variables will be returned.

Default: true

Responses

200

Successfully retrieved reanalysis data

application/jsonapplication/vnd.apache.arrow.stream

Responseany

400

Invalid query parameters

401

Authentication required

402

Insufficient credits

403

Insufficient permissions

422

Validation Error

application/json

post

/v1/reanalysis/data

HTTPcURLJavaScriptPython

POST /v1/reanalysis/data HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 244

{
  "models": [
    "arco_era5"
  ],
  "geo": {
    "type": "point",
    "value": [
      [
        52.52,
        13.405
      ]
    ],
    "method": "nearest"
  },
  "time": {
    "start": "2024-01-15T00:00:00Z",
    "end": "2024-01-16T00:00:00Z"
  },
  "variables": [
    "air_temperature_at_height_level_2m",
    "wind_speed_at_height_level_10m"
  ]
}

Query single point for one dayQuery latest available dataMarket zone queryAggregation 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
  ]
}

Estimate query cost

post

Calculate the estimated credit cost for a reanalysis query before executing it.

Returns detailed information about:

• Total credits required

• Number of data rows to be returned

• Number of data rows to be accessed

Authentication: Requires API key.

Authorizations

HTTPBearer

Body

application/json

Query object for retrieving reanalysis data.

Reanalysis data uses a simple time dimension (unlike forecasts which have init_time + prediction_timedelta). This provides historical analysis data at specified timestamps.

Example: python query = ReanalysisQuery( models=["arco_era5"], geo={"type": "point", "value": [(52.52, 13.405)]}, time={"start": "2024-01-01T00:00:00Z", "end": "2024-01-07T00:00:00Z"}, variables=["air_temperature_at_height_level_2m"], )

timeany ofRequired

Time(s) to query. Can be 'latest', a single datetime, a list of datetimes, or a TimeSlice range.

Example: latest

string · date-timeOptional

or

string · date-time[]Optional

or

or

const: latestOptional

group_byany ofOptional

List of dimensions to group by for aggregation (e.g., ['model', 'time']). Requires 'aggregation' to be specified.

or

nullOptional

order_byany ofOptional

List of dimensions to sort results by. Supports direction suffix: 'time__desc' for descending, 'time__asc' for ascending (default). Can also use object format: {'field': 'time', 'direction': 'desc'}

Example: ["model","time"]

or

nullOptional

aggregationany ofOptional

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

or

nullOptional

weightingany ofOptional

Optional weighting scheme for geographic aggregation (e.g., by wind/solar capacity or population)

Example: {"type":"wind_capacity"}

or

nullOptional

include_timebooleanOptional

Include the time column in results (default: True)

Default: true

time_zoneany ofOptional

IANA time zone name for time formatting (e.g., 'Europe/Berlin', 'America/New_York'). Defaults to UTC

Example: UTC

stringOptional

or

nullOptional

paginationany ofOptional

Pagination parameters for limiting result size. Requires 'order_by' to be specified

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

or

nullOptional

were_variables_explicitly_requestedbooleanOptional

Whether the user passed the variables explicitly. If True, the variables will be used to filter the results. If False, all variables will be returned.

Default: true

Responses

200

Successfully calculated query cost

application/json

400

Invalid query parameters

401

Authentication required

403

Insufficient permissions

422

Validation Error

application/json

post

/v1/reanalysis/cost

HTTPcURLJavaScriptPython

POST /v1/reanalysis/cost HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 209

{
  "models": [
    "arco_era5"
  ],
  "geo": {
    "type": "point",
    "value": [
      13.405,
      52.52
    ],
    "method": "nearest"
  },
  "variables": [
    "air_temperature_at_height_level_2m"
  ],
  "time": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-02T00:00:00Z"
  }
}

{
  "total_credits_needed": 0.187,
  "total_rows_returned": 281,
  "total_rows_accessed": 281
}

Get reanalysis dataset metadata

get

Get metadata about available reanalysis models including:

• Model names and display names

• Grid resolution and temporal resolution

• Available variables

Authentication: Requires API key.

Authorizations

HTTPBearer

Responses

200

Successfully retrieved metadata

application/json

401

Authentication required

get

/v1/reanalysis/meta

HTTPcURLJavaScriptPython

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

{
  "models": [
    {
      "name": "arco_era5",
      "display_name": "ARCO ERA5",
      "grid_resolution": "0.25° x 0.25°",
      "temporal_resolution_minutes": 60,
      "variables": [
        "air_temperature_at_height_level_2m",
        "..."
      ]
    }
  ]
}

Get latest available timestamp

get

Get the latest available timestamp for each specified reanalysis model.

This is useful for knowing what data is currently available without making a full query.

Authentication: Requires API key.

Authorizations

HTTPBearer

Query parameters

modelsstring[]Optional

List of reanalysis models to check

Default: ["arco_era5"]Example: arco_era5

Responses

200

Successfully retrieved latest timestamps

application/json

401

Authentication required

422

Validation Error

application/json

get

/v1/reanalysis/latest-timestamp

HTTPcURLJavaScriptPython

GET /v1/reanalysis/latest-timestamp HTTP/1.1
Accept: */*

{
  "timestamps": {
    "arco_era5": "2024-01-15T12:00:00Z"
  }
}

Get available timestamps

get

Get a list of available timestamps for each specified reanalysis model within an optional time range.

Authentication: Requires API key.

Authorizations

HTTPBearer

Query parameters

modelsstring[]Optional

List of reanalysis models to check

Default: ["arco_era5"]Example: arco_era5

sinceany ofOptional

Only return timestamps >= this time (inclusive)

string · date-timeOptional

or

nullOptional

beforeany ofOptional

Only return timestamps < this time (exclusive)

string · date-timeOptional

or

nullOptional

limitinteger · min: 1 · max: 1000Optional

Maximum number of timestamps to return

Default: 100

Responses

200

Successfully retrieved available timestamps

application/json

401

Authentication required

422

Validation Error

application/json

get

/v1/reanalysis/available-timestamps

HTTPcURLJavaScriptPython

GET /v1/reanalysis/available-timestamps HTTP/1.1
Accept: */*

{
  "timestamps": {
    "arco_era5": [
      "2024-01-15T00:00:00Z",
      "2024-01-15T01:00:00Z",
      "2024-01-15T02:00:00Z"
    ]
  }
}