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

modelsany ofOptional

Filter by specific model(s). If not provided, returns all models

nullOptional

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

modelsany ofOptional

Filter by specific model(s). If not provided, returns all accessible models with Clickhouse data source

nullOptional

sinceany ofOptional

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

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

string · date-timeOptional

nullOptional

beforeany ofOptional

Only return forecasts initialized before this datetime (optional)

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

string · date-timeOptional

nullOptional

limitany ofOptional

Maximum number of results to return

Default: 20

integer · min: 1Optional

nullOptional

offsetany ofOptional

Number of results to skip for pagination

Default: 0

integerOptional

nullOptional

as_ofany ofOptional

Synthetic invocation time for backtesting (ISO 8601 UTC). Only returns forecasts disseminated at or before this time.

string · date-timeOptional

nullOptional

Responses

200

Successfully retrieved available forecasts

application/json

Result containing available forecast times per model.

paginationany ofOptional

Pagination information if results were paginated

nullOptional

401

Authentication required

403

Insufficient permissions

422

Validation error - invalid model selection

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

sinceany ofOptional

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

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

string · date-timeOptional

nullOptional

beforeany ofOptional

Only count forecasts initialized before this datetime (optional)

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

string · date-timeOptional

nullOptional

as_ofany ofOptional

Synthetic invocation time for backtesting (ISO 8601 UTC). Only counts forecasts disseminated at or before this time.

string · date-timeOptional

nullOptional

Responses

200

Successfully counted forecasts

application/json

Result containing forecast counts per model.

401

Authentication required

403

Insufficient permissions

422

Validation error - invalid model selection

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

as_ofany ofOptional

Synthetic invocation time for backtesting (ISO 8601 UTC). Returns the latest init time that was disseminated at or before this time.

string · date-timeOptional

nullOptional

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 - models list must contain at least one model

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

sinceany ofOptional

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

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

string · date-timeOptional

nullOptional

beforeany ofOptional

Only analyze forecasts initialized before this datetime (optional)

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

string · date-timeOptional

nullOptional

limitany ofOptional

Maximum number of forecasts to analyze per model

Default: 100

integer · min: 1Optional

nullOptional

offsetany ofOptional

Number of forecasts to skip for pagination

Default: 0

integerOptional

nullOptional

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 - invalid model selection

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

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.

modelsany ofOptional

List of forecast model identifiers to query (e.g., ['ept2', 'aifs']). Required if model_runs is not specified.

Example: ["ept2"]

nullOptional

init_timeany ofOptional

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+)?$

nullOptional

model_runsany ofOptional

Per-model init_time specification. Alternative to models+init_time. Keys are model identifiers, values are init_time specifications (same formats as init_time: 'latest', 'latest-N', integer offset, datetime, list, or TimeSlice). Cannot be used together with models/init_time.

Example: {"aifs":"2025-01-15T00:00:00","ept2":"latest"}

nullOptional

timeany ofOptional

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

nullOptional

prediction_timedeltaany ofOptional

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

nullOptional

latest_min_prediction_timedeltaany ofOptional

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).

integerOptional

nullOptional

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

Requested temporal resolution in minutes

Example: 15

integer · enumOptionalPossible values:

nullOptional

group_byany ofOptional

List of dimensions to group by for aggregation (e.g., ['model', 'init_time', 'time']). Requires 'aggregation' to be specified. See docs.jua.ai for grouping examples

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","init_time","prediction_timedelta"]

nullOptional

aggregationany ofOptional

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

nullOptional

weightingany ofOptional

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

Example: {"type":"wind_capacity"}

nullOptional

include_timebooleanOptional

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

Default: false

time_zoneany ofOptional

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

Example: UTC

stringOptional

nullOptional

paginationany ofOptional

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

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

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

value_filtersany ofOptional

Post-aggregation value filters applied as an outermost SQL wrapper. Used by alert evaluation to push threshold conditions into ClickHouse.

nullOptional

as_ofany ofOptional

Synthetic invocation time for backtesting (ISO 8601 UTC datetime). When set, only forecast runs that were disseminated at or before this time are visible, and 'latest' resolves relative to this timestamp. Omit or set to null for real-time behaviour.

Example: 2025-06-15T12:00:00

string · date-timeOptional

nullOptional

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": [
      13.405,
      52.52
    ],
    "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 ofOptional

Example: 1

integerOptional

integer[]Optional

nullOptional

latest_min_prediction_timedeltaany ofOptional

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).

integerOptional

nullOptional

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:

as_ofany ofOptional

Synthetic invocation time for backtesting (ISO 8601 UTC datetime). When set, only forecast runs that were disseminated at or before this time are visible. Omit or set to null for real-time behaviour.

Example: 2025-06-15T12:00:00

string · date-timeOptional

nullOptional

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:

variablesany ofOptional

Weather variables to query. If not specified, returns all available variables

nullOptional

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 in minutes

Default: 0

max_prediction_timedeltaany ofOptional

Maximum lead time in minutes

integerOptional

nullOptional

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

as_ofany ofOptional

Synthetic invocation time for backtesting (ISO 8601 UTC). Only forecast runs disseminated at or before this time are visible.

string · date-timeOptional

nullOptional

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-03-17T22%3A18%3A43.559Z&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_zonesany ofOptional

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

string[]Optional

nullOptional

country_keysany ofOptional

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

string[]Optional

nullOptional

variablesany ofOptional

Weather variables to query. If not specified, returns all available variables

nullOptional

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 in minutes

Default: 0

max_prediction_timedeltaany ofOptional

Maximum lead time in minutes

integerOptional

nullOptional

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

as_ofany ofOptional

Synthetic invocation time for backtesting (ISO 8601 UTC). Only forecast runs disseminated at or before this time are visible.

string · date-timeOptional

nullOptional

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-03-17T22%3A18%3A43.559Z&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

solarstring[]Required

get

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

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

200

Successful Response

{
  "wind": [
    "text"
  ],
  "solar": [
    "text"
  ]
}

PreviousRate Limiting NextBenchmarks

Last updated 41 minutes ago

hashtagGet forecast models metadata

hashtagList available forecasts

hashtagCount available forecasts

hashtagGet latest forecast initialization time

hashtagGet forecast dissemination status

hashtagQuery forecast data

hashtagFeatures

hashtagResponse Formats

hashtagStreaming

hashtagCost Management

hashtagQuery forecast data index

hashtagQuery forecast data (simple)

hashtagQuery market-aggregated forecast data

hashtagList market zones capable of MW output

Get forecast models metadata

List available forecasts

Count available forecasts

Get latest forecast initialization time

Get forecast dissemination status

Query forecast data

Features

Response Formats

Streaming

Cost Management

Query forecast data index

Query forecast data (simple)

Query market-aggregated forecast data

List market zones capable of MW output