Forecast

Query and retrieve weather forecast data from Jua's platform.

Get forecast models metadata

get

Retrieve metadata for available forecast models including:

Available weather variables for each model
Spatial grid resolution information
Model identifiers

Use this endpoint to discover which models and variables are available before making data queries.

Authentication: Requires API key.

For detailed model specifications and variable descriptions, visit docs.jua.ai.

Authorizations

Query parameters

Responses

200

Successfully retrieved model metadata

application/json

Result containing metadata for one or more forecast models.

401

Authentication required

403

Insufficient permissions

422

Validation Error

application/json

get/v1/forecast/meta

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

{
  "models": [
    {
      "model": "ept2",
      "variables": [
        "air_temperature_at_height_level_2m",
        "wind_speed_at_height_level_100m"
      ],
      "grid": {
        "num_latitudes": 2160,
        "num_longitudes": 4320
      }
    }
  ]
}

List available forecasts

get

List all available forecast initialization times for specified models with optional time filtering.

Returns forecast init times and maximum available lead times, useful for:

Discovering historical forecast availability
Finding specific forecast runs
Monitoring forecast data updates

Authentication: Requires API key.

Results are paginated. Use limit and offset parameters to navigate through large result sets.

For forecast schedules and update frequencies, see docs.jua.ai.

Authorizations

Query parameters

sincestring · date-time · nullableOptional

Only return forecasts initialized on or after this datetime (optional)

Example: 2025-01-01T00:00:00Z

beforestring · date-time · nullableOptional

Only return forecasts initialized before this datetime (optional)

Example: 2025-10-01T00:00:00Z

limitinteger · min: 1 · nullableOptional

Maximum number of results to return

Default: 20

offsetinteger · nullableOptional

Number of results to skip for pagination

Default: 0

orderstring · enumOptional

Sort by init_time: 'desc' (newest first, default) or 'asc' (oldest first). Use 'asc' with limit=1 to find the earliest run.

Default: descPossible values:

Responses

200

Successfully retrieved available forecasts

application/json

Result containing available forecast times per model.

401

Authentication required

403

Insufficient permissions

422

Validation Error

application/json

get/v1/forecast/available-forecasts

GET /v1/forecast/available-forecasts HTTP/1.1
Accept: */*

{
  "forecasts_per_model": {
    "ept2": [
      {
        "init_time": "2025-01-15T00:00:00Z",
        "max_prediction_timedelta": 10080
      }
    ]
  },
  "pagination": {
    "limit": 20,
    "offset": 0
  }
}

Count available forecasts

get

Get the total count of available forecasts per model with optional time filtering.

Useful for:

Checking data availability before querying
Monitoring forecast archive growth
Validating expected data coverage

Authentication: Requires API key.

For more information on forecast availability, see docs.jua.ai.

Authorizations

Query parameters

sincestring · date-time · nullableOptional

Only count forecasts initialized on or after this datetime (optional)

Example: 2025-01-01T00:00:00Z

beforestring · date-time · nullableOptional

Only count forecasts initialized before this datetime (optional)

Example: 2025-10-01T00:00:00Z

Responses

200

Successfully counted forecasts

application/json

Result containing forecast counts per model.

401

Authentication required

403

Insufficient permissions

422

Validation Error

application/json

get/v1/forecast/count

GET /v1/forecast/count?models=ept2 HTTP/1.1
Accept: */*

{
  "forecasts_per_model": {
    "ept2": 1250,
    "aifs": 980
  }
}

Get latest forecast initialization time

get

Retrieve the most recent forecast initialization time available for each model.

Returns:

Latest init_time for each model
Maximum available lead time for that forecast

Useful for:

Getting real-time forecast data with init_time='latest'
Monitoring forecast update status
Validating forecast freshness

Authentication: Requires API key.

For forecast update schedules, see docs.jua.ai.

Authorizations

Query parameters

min_prediction_timedeltaintegerOptional

Minimum required lead time in minutes

Default: 0

Responses

200

Successfully retrieved latest forecast info

application/json

Result containing the latest forecast information per model.

401

Authentication required

403

Insufficient permissions

422

Validation Error

application/json

get/v1/forecast/latest-init-time

GET /v1/forecast/latest-init-time?models=ept2 HTTP/1.1
Accept: */*

{
  "forecasts_per_model": {
    "ept2": {
      "init_time": "2025-01-15T12:00:00Z",
      "prediction_timedelta": 10080
    }
  }
}

Get forecast dissemination status

get

Retrieve dissemination status and delay statistics for forecasts.

Returns for each model:

Status for individual forecasts (init_time, delay, whether missing)
Aggregated delay statistics (min, max, mean, median, std, percentiles)
Missing forecast percentage

Useful for:

Monitoring forecast delivery timeliness
Identifying delayed or missing forecasts
Analyzing dissemination performance over time

Authentication: Requires API key.

Results are paginated. Use limit and offset parameters to navigate through large result sets.

For forecast schedules and SLA information, see docs.jua.ai.

Authorizations

Query parameters

sincestring · date-time · nullableOptional

Only analyze forecasts initialized on or after this datetime (optional)

Example: 2025-01-01T00:00:00Z

beforestring · date-time · nullableOptional

Only analyze forecasts initialized before this datetime (optional)

Example: 2025-10-01T00:00:00Z

limitinteger · min: 1 · nullableOptional

Maximum number of forecasts to analyze per model

Default: 100

offsetinteger · nullableOptional

Number of forecasts to skip for pagination

Default: 0

only_statsbooleanOptional

Only return delay statistics per init time (without forecast status)

Default: false

Responses

200

Successfully retrieved dissemination status

application/json

401

Authentication required

403

Insufficient permissions

422

Validation Error

application/json

get/v1/forecast/dissemination-status

GET /v1/forecast/dissemination-status?models=ept2 HTTP/1.1
Accept: */*

{
  "status_per_model": {
    "ept2": {
      "status": [
        {
          "init_time": "2025-01-15T00:00:00Z",
          "delay": -2.2,
          "is_missing": false,
          "is_delayed": true
        }
      ],
      "delay_stats": {
        "min": -2.5,
        "max": 0.3,
        "mean": -0.1,
        "median": -2.3,
        "std": 1.1,
        "q90": -0.1,
        "q99": 0.01,
        "missing_percentage": 0
      }
    }
  }
}

Query forecast data

post

Main endpoint for querying weather forecast data with full flexibility.

Features

Query by location (point, area, market zone) and time
Select specific models and weather variables
Support for aggregation and grouping
Multiple response formats (JSON, Apache Arrow)
Optional streaming for large datasets

Response Formats

JSON (format=json): Returns columnar JSON {column: [values], ...} suitable for small to medium datasets
Arrow (format=arrow): Returns Apache Arrow IPC stream for efficient large dataset handling

Streaming

Set stream=true for streaming responses with Arrow format. Recommended for queries returning >100k rows.

Cost Management

Queries are billed based on data volume, models, and variables. Use:

request_credit_limit: Set maximum credits to prevent unexpectedly large charges
/cost endpoint: Estimate costs before executing

For more details on how the costs are computed, visit docs.jua.ai/pricing.

Authentication: Requires API key.

For detailed query examples and best practices, visit docs.jua.ai.

Authorizations

Query parameters

formatstring · enumOptional

Response format: 'json' for columnar JSON or 'arrow' for Apache Arrow formatjson only supports up to 50k rows, arrow supports up to 5M rows without streaming

Default: jsonPossible values:

streambooleanOptional

Enable streaming response (only with format=arrow). Recommended for queries returning >100k rows.

Default: false

request_credit_limitnumberOptional

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

Default: 50

include_unitsbooleanOptional

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

Default: false

Header parameters

X-Request-Sourcestring · nullableOptional

Body

Main query object for retrieving weather forecast data.

Supports flexible querying by location, time, variables, and models with optional aggregation, grouping, and weighting capabilities.

Two modes of specifying models and init_times:

Classic mode: Use models + init_time (same init_time for all models)
Model runs mode: Use model_runs (per-model init_time specification)

These modes are mutually exclusive.

init_timeany of · nullableOptional

Forecast initialization time(s). Accepts: 'latest' or 'latest-N' for relative init times, an integer offset (0 = latest, 1 = second latest), an ISO 8601 datetime string, a list of any of the above, or a TimeSlice object with start/end for a date range. Required if model_runs is not specified.

Example: latest

integerOptional

Offset from latest forecast (0 = latest, 1 = second latest, etc.)

string · date-timeOptional

stringOptional

Use 'latest' or 'latest-N' for relative init times

Pattern: ^latest(-\d+)?$

timeany of · nullableOptional

Filter by specific forecast valid times (as opposed to lead times). Accepts datetime, list of datetimes, or time range

Example: 2025-01-15T09:00:00

string · date-timeOptional

string · date-time[]Optional

prediction_timedeltaany of · nullableOptional

Forecast lead time(s) from init_time. The units are determined by the timedelta_unit parameter (default: h). Can be a single integer, list of integers, or a PredictionTimedeltaSlice range. If None, returns all available lead times.

Example: 1

integerOptional

integer[]Optional

latest_min_prediction_timedeltainteger · nullableOptional

When using init_time='latest', only use forecasts with at least latest_min_prediction_timedelta of lead time available. The units are determined by the timedelta_unit parameter (default: h).

timedelta_unitstring · enumOptional

Time scale to use for the query. Can be 'h' for hours, 'm' for minutes, 'd' for days

Default: hExample: hPossible values:

temporal_resolutioninteger · enum · nullableOptional

Requested temporal resolution in minutes

Example: 15Possible values:

include_timebooleanOptional

Include the forecast valid time (init_time + prediction_timedelta) as a column in results

Default: false

time_zonestring · nullableOptional

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

Example: UTC

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

include_ensemble_membersbooleanOptional

When True, return per-ensemble-member rows for ensemble models instead of the implicit ensemble-mean. Disables the auto-grouping that hides individual members. If group_by is also explicit, 'ensemble_member' is automatically added so aggregation runs per member.

Default: false

debiasbooleanOptional

If True, subtract a per-(model, valid-time month, valid-time hour) bias from the requested values before returning. The bias is the average of the previous calendar month's forecast-vs-station errors across European stations, computed on the fly from synoptic_station_bias_europe. Only air_temperature_at_height_level_2m and wind_speed_at_height_level_10m may be requested; any other variable, or any power/MW forecast, is rejected.

Default: false

Responses

200

Successfully retrieved forecast data

anyOptional

400

Invalid query parameters or response size exceeded

401

Authentication required

402

Insufficient credits

403

Insufficient permissions or model not in subscription

422

Validation Error

application/json

post/v1/forecast/data

POST /v1/forecast/data HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 235

{
  "models": [
    "ept2"
  ],
  "geo": {
    "type": "point",
    "value": [
      52.52,
      13.405
    ],
    "method": "nearest"
  },
  "variables": [
    "air_temperature_at_height_level_2m",
    "wind_speed_at_height_level_100m"
  ],
  "init_time": "latest",
  "prediction_timedelta": {
    "start": 0,
    "end": 360
  }
}

{
  "model": [
    "ept2",
    "ept2"
  ],
  "init_time": [
    "2025-10-15T00:00:00Z",
    "2025-10-15T00:00:00Z"
  ],
  "latitude": [
    52.52,
    52.52
  ],
  "longitude": [
    13.4,
    13.4
  ],
  "prediction_timedelta": [
    60,
    120
  ],
  "air_temperature_at_height_level_2m": [
    285.5,
    286.2
  ]
}

Query forecast data index

post

Endpoint to obtain the index for weather forecasts.

Authentication: Requires API key.

For detailed query examples and best practices, visit docs.jua.ai.

Authorizations

Query parameters

request_credit_limitnumberOptional

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

Default: 50

Body

Main query object for retrieving the index for forecast data.

modelstring · enumRequired

Model identifiers to query (e.g. 'ept2')

Example: ept1_5Possible values:

init_timeany ofRequired

Example: latest

integerOptional

Offset from latest forecast (0 = latest, 1 = second latest, etc.)

string · date-timeOptional

stringOptional

Use 'latest' or 'latest-N' for relative init times

Pattern: ^latest(-\d+)?$

latitudearray · min: 2 · max: 2Required

The range of latitudes to return.

Example: [32,71]

longitudearray · min: 2 · max: 2Required

Geographic filter specifying the query location(s) or region(s)

Example: [-15,50]

prediction_timedeltaany of · nullableOptional

Example: 1

integerOptional

integer[]Optional

latest_min_prediction_timedeltainteger · nullableOptional

When using init_time='latest', only use forecasts with at least latest_min_prediction_timedelta of lead time available. The units are determined by the timedelta_unit parameter (default: h).

timedelta_unitstring · enumOptional

Time scale to use for the query. Can be 'h' for hours, 'm' for minutes, 'd' for days

Default: hExample: hPossible values:

Responses

200

Successfully retrieved forecast data

anyOptional

400

Invalid query parameters or response size exceeded

401

Authentication required

402

Insufficient credits

403

Insufficient permissions or model not in subscription

422

Validation Error

application/json

post/v1/forecast/index

POST /v1/forecast/index HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 281

{
  "model": "ept2",
  "latitude": [
    32,
    71
  ],
  "longitude": [
    -15,
    50
  ],
  "variables": [
    "air_temperature_at_height_level_2m",
    "wind_speed_at_height_level_100m"
  ],
  "init_time": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "prediction_timedelta": {
    "start": 0,
    "end": 120
  },
  "timedelta_unit": "h"
}

{
  "init_time": [
    "2025-10-15T00:00:00Z",
    "2025-10-15T06:00:00Z"
  ],
  "latitude": [
    52,
    52.25,
    52.5
  ],
  "longitude": [
    13,
    13.25
  ],
  "prediction_timedelta": [
    0,
    60,
    120,
    180
  ],
  "variables": [
    "air_temperature_at_height_level_2m"
  ]
}

Query forecast data (simple)

get

Simplified GET endpoint for querying forecast data at a single point location.

This endpoint provides a simpler interface compared to POST /data for basic point queries. Use this for quick lookups at specific coordinates.

Limitations:

Point queries only (no areas or market zones)
JSON response format only (no Arrow or streaming)
No grouping or aggregation support

For advanced queries with aggregation, multiple locations, or Arrow format, use POST /data.

Authentication: Requires API key.

See docs.jua.ai for examples.

Authorizations

Query parameters

init_timeany ofRequired

Forecast initialization time (ISO 8601 format) or 'latest' for most recent forecast

string · date-timeOptional

const: latestOptional

latitudenumber · min: -90 · max: 90Required

Latitude of query point in degrees (-90 to 90)

longitudenumber · min: -180 · max: 180Required

Longitude of query point in degrees (-180 to 180)

methodstring · enumOptional

Interpolate or return the nearest value

Default: nearestPossible values:

time_zonestringOptional

IANA time zone name for time formatting

Default: GMT

include_timebooleanOptional

Include forecast valid time column

Default: true

min_prediction_timedeltaintegerOptional

Minimum lead time, expressed in timedelta_unit (default hours)

Default: 0

max_prediction_timedeltainteger · nullableOptional

Maximum lead time, expressed in timedelta_unit (default hours)

timedelta_unitstring · enumOptional

Unit for min/max_prediction_timedelta. 'h' hours (default), 'm' minutes, 'd' days. Defaults to hours for backward compatibility.

Default: hPossible values:

offsetintegerOptional

Number of results to skip for pagination

Default: 0

limitinteger · min: 1Optional

Maximum number of results to return

Default: 10000

request_credit_limitnumberOptional

Maximum credits allowed for this request

Default: 5

include_unitsbooleanOptional

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

Default: false

include_ensemble_membersbooleanOptional

When true, return per-ensemble-member rows instead of ensemble-mean rows. Not supported for ept2_e.

Default: false

Responses

200

Successfully retrieved forecast data

application/json

anyOptional

400

Invalid query parameters

401

Authentication required

402

Insufficient credits

403

Insufficient permissions

422

Validation Error

application/json

get/v1/forecast/

GET /v1/forecast/?models=ept2&init_time=2026-07-21T17%3A43%3A17.693Z&latitude=1&longitude=1 HTTP/1.1
Accept: */*

{
  "model": [
    "ept2",
    "ept2"
  ],
  "init_time": [
    "2025-01-15T00:00:00Z",
    "2025-01-15T00:00:00Z"
  ],
  "latitude": [
    52.52,
    52.52
  ],
  "longitude": [
    13.4,
    13.4
  ],
  "prediction_timedelta": [
    60,
    120
  ],
  "air_temperature_at_height_level_2m": [
    285.5,
    286.2
  ]
}

Query market-aggregated forecast data

get

Simplified GET endpoint for querying weighted-average forecasts over market zones or countries.

Automatically applies weighted aggregation based on capacity (wind/solar) or population distribution. Useful for energy market analysis and regional forecasting.

Common Use Cases:

Wind power generation forecasts for market zones (weighted by wind capacity)
Solar power generation forecasts (weighted by solar capacity)
Population-weighted temperature averages for countries

Weighting Options:

wind_capacity: Weight by installed wind power capacity
solar_capacity: Weight by installed solar power capacity
population: Weight by population density

Limitations:

JSON response format only (no Arrow or streaming)
Must specify either market_zones OR country_keys (not both)

For advanced aggregation queries, use POST /data with group_by and weighting parameters.

Authentication: Requires API key.

See docs.jua.ai for examples.

Authorizations

Query parameters

init_timeany ofRequired

Forecast initialization time (ISO 8601 format) or 'latest' for most recent forecast

string · date-timeOptional

const: latestOptional

weightingstring · enumRequired

Weighting scheme for aggregation

Possible values:

market_zonesstring[] · nullableOptional

Energy market zone codes (e.g., ['DE', 'FR']). Mutually exclusive with country_keys

country_keysstring[] · nullableOptional

ISO country codes (e.g., ['DE', 'US']). Mutually exclusive with market_zones

time_zonestringOptional

IANA time zone name for time formatting

Default: GMT

include_timebooleanOptional

Include forecast valid time column

Default: true

min_prediction_timedeltaintegerOptional

Minimum lead time, expressed in timedelta_unit (default hours)

Default: 0

max_prediction_timedeltainteger · nullableOptional

Maximum lead time, expressed in timedelta_unit (default hours)

timedelta_unitstring · enumOptional

Unit for min/max_prediction_timedelta. 'h' hours (default), 'm' minutes, 'd' days. Defaults to hours for backward compatibility.

Default: hPossible values:

temporal_resolutioninteger · enum · nullableOptional

Requested temporal resolution in minutes. Values finer than the model's native step trigger interpolation; coarser values downsample. Allowed: 15, 30, 60, 120, 180, 240, 300, 360.

Possible values:

offsetintegerOptional

Number of results to skip for pagination

Default: 0

limitinteger · min: 1 · max: 100000Optional

Maximum number of results to return

Default: 10000

unitstring · enumOptional

Output unit. 'weather': capacity-weighted raw weather. 'mw': apply power curves and return predicted MW.

Default: weatherPossible values:

request_credit_limitnumberOptional

Maximum credits allowed for this request

Default: 50

include_unitsbooleanOptional

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

Default: false

Responses

200

Successfully retrieved aggregated forecast data

application/json

anyOptional

400

Invalid parameters (must specify market_zones OR country_keys)

401

Authentication required

402

Insufficient credits

403

Insufficient permissions

422

Validation Error

application/json

get/v1/forecast/market-aggregate

GET /v1/forecast/market-aggregate?models=ept2&init_time=2026-07-21T17%3A43%3A17.693Z&weighting=wind_capacity HTTP/1.1
Accept: */*

{
  "model": [
    "ept2"
  ],
  "init_time": [
    "2025-01-15T00:00:00Z"
  ],
  "time": [
    "2025-01-15T06:00:00Z"
  ],
  "prediction_timedelta": [
    360
  ],
  "wind_speed_at_height_level_100m": [
    8.5
  ]
}

List market zones capable of MW output

get

Return market zones that have both facility data and fitted power curves.

This is a metadata endpoint and does not require authentication.

A zone is MW-capable for wind if it has operating wind facilities and corresponding entries in the wind power-curve tables. Same logic applies for solar.

Results are cached in-memory for 5 minutes.

Responses

200

Successful Response

application/json

Market zones that have power-curve data and can produce MW output.

windstring[]Required

wind_combinedstring[]Required

wind_transmission_embeddedstring[]OptionalDefault: []

wind_onshore_onlystring[]Required

solarstring[]Required

loadstring[]Required

422

Validation Error

application/json

get/v1/forecast/market-aggregate/mw-zones

GET /v1/forecast/market-aggregate/mw-zones HTTP/1.1
Accept: */*

{
  "wind": [
    "text"
  ],
  "wind_combined": [
    "text"
  ],
  "wind_transmission_embedded": [
    "text"
  ],
  "wind_onshore_only": [
    "text"
  ],
  "solar": [
    "text"
  ],
  "load": [
    "text"
  ]
}

PreviousRate Limiting NextBenchmarks

Last updated 2 hours ago