# Power Forecast

Query power generation forecast data for renewable energy sources (Solar, Wind, etc.).

## Query power forecast data

> Query power forecast prediction data for renewable energy generation (Solar, Wind, etc.).\
> \
> \*\*Dimensions:\*\*\
> \- \`zone\_key\`: Country/region code (e.g. "DE")\
> \- \`psr\_type\`: Generation source type (e.g. "Solar", "Wind Onshore")\
> \
> \*\*Query Modes (mutually exclusive):\*\*\
> \
> 1\. \*\*Horizon mode\*\* (init\_time-centric):\
>    \- \`init\_time\`: Specific init time(s) or relative tokens (\`latest\`, \`latest-N\`)\
>    \- \`max\_prediction\_timedelta\`: Limit forecast horizon (minutes)\
> \
> 2\. \*\*Time range mode\*\* (time-centric):\
>    \- \`start\_time\` / \`end\_time\`: Filter by computed forecast time\
> \
> \*\*Response Formats:\*\*\
> \- \`json\`: Columnar JSON format \`{column: \[values], ...}\`\
> \- \`arrow\`: Apache Arrow IPC stream for efficient processing\
> \
> \*\*Authentication\*\*: Requires API key.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/power-forecast/data":{"post":{"tags":["power-forecast"],"summary":"Query power forecast data","description":"Query power forecast prediction data for renewable energy generation (Solar, Wind, etc.).\n\n**Dimensions:**\n- `zone_key`: Country/region code (e.g. \"DE\")\n- `psr_type`: Generation source type (e.g. \"Solar\", \"Wind Onshore\")\n\n**Query Modes (mutually exclusive):**\n\n1. **Horizon mode** (init_time-centric):\n   - `init_time`: Specific init time(s) or relative tokens (`latest`, `latest-N`)\n   - `max_prediction_timedelta`: Limit forecast horizon (minutes)\n\n2. **Time range mode** (time-centric):\n   - `start_time` / `end_time`: Filter by computed forecast time\n\n**Response Formats:**\n- `json`: Columnar JSON format `{column: [values], ...}`\n- `arrow`: Apache Arrow IPC stream for efficient processing\n\n**Authentication**: Requires API key.","operationId":"post_power_forecast_data_v1_power_forecast_data_post","parameters":[{"name":"format","in":"query","required":false,"schema":{"enum":["json","arrow"],"type":"string","description":"Response format: 'json' or 'arrow'","default":"json","title":"Format"},"description":"Response format: 'json' or 'arrow'"},{"name":"include_units","in":"query","required":false,"schema":{"type":"boolean","description":"When true, JSON responses are wrapped in {data, units}. Units are always sent via X-Variable-Units header regardless.","default":false,"title":"Include Units"},"description":"When true, JSON responses are wrapped in {data, units}. Units are always sent via X-Variable-Units header regardless."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PowerForecastQuery"}}}},"responses":{"200":{"description":"Successfully retrieved power forecast data","content":{"application/json":{"schema":{}},"application/vnd.apache.arrow.stream":{"description":"Apache Arrow IPC stream format"}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"PowerForecastQuery":{"properties":{"zone_keys":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Zone Keys","description":"List of zone codes (e.g. ['DE', 'FR'])"},"psr_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Psr Types","description":"List of PSR types (e.g. ['Solar', 'Wind Onshore'])"},"init_time":{"anyOf":[{"type":"integer","minimum":0,"description":"Offset from latest forecast (0 = latest, 1 = second latest, etc.)"},{"type":"string","format":"date-time"},{"items":{"anyOf":[{"type":"string","format":"date-time"},{"type":"integer","minimum":0,"description":"Offset from latest forecast (0 = latest, 1 = second latest, etc.)"}]},"type":"array"},{"type":"null"}],"title":"Init Time","description":"Init time selection for horizon mode. Accepts datetime(s), 'latest', or 'latest-N'."},"max_prediction_timedelta":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Max Prediction Timedelta","description":"Maximum prediction horizon in minutes (horizon mode)"},"start_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Time","description":"Start of time range (inclusive, time range mode)"},"end_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Time","description":"End of time range (exclusive, time range mode)"},"time_zone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Zone","description":"IANA time zone name for time formatting (e.g. 'Europe/Berlin')"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/OrderByItem_str_"},"type":"array"},{"type":"null"}],"title":"Order By","description":"Columns to order by. Supports direction suffix: 'time__desc' for descending. Default: time ASC."},"pagination":{"anyOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"null"}],"description":"Pagination parameters"}},"type":"object","title":"PowerForecastQuery","description":"Query parameters for power forecast data.\n\nSupports two mutually exclusive query modes:\n\n**Horizon mode** (init_time-centric):\n    - Specify init_time as datetime(s) or relative tokens (latest/latest-N)\n    - Optionally limit by max_prediction_timedelta\n\n**Time range mode** (time-centric):\n    - Specify start_time / end_time\n    - Computed time = init_time + prediction_timedelta * 60s\n\nCommon filters:\n    - zone_keys: List of zone codes (e.g. [\"DE\", \"FR\"])\n    - psr_types: List of generation types (e.g. [\"Solar\", \"Wind Onshore\"])"},"OrderByItem_str_":{"properties":{"field":{"type":"string","title":"Field","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction: 'asc' (default) or 'desc'","default":"asc"},"aggregation":{"anyOf":[{"type":"string","enum":["avg","std","min","max","sum","count","median","quantile","argmin","argmax"]},{"type":"null"}],"title":"Aggregation","description":"Aggregation function when ordering by variable"}},"type":"object","required":["field"],"title":"OrderByItem[str]"},"SortDirection":{"type":"string","enum":["asc","desc"],"title":"SortDirection","description":"Sort direction for ORDER BY clauses."},"Pagination":{"properties":{"limit":{"type":"integer","title":"Limit","default":100},"offset":{"type":"integer","title":"Offset","default":0}},"type":"object","title":"Pagination"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List available power forecast zones

> Get a list of available zone codes that have power forecast data.\
> \
> This is a metadata endpoint and does not require authentication.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"paths":{"/v1/power-forecast/zones":{"get":{"tags":["power-forecast"],"summary":"List available power forecast zones","description":"Get a list of available zone codes that have power forecast data.\n\nThis is a metadata endpoint and does not require authentication.","operationId":"get_power_forecast_zones_v1_power_forecast_zones_get","responses":{"200":{"description":"Successfully retrieved zone list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/jua_query_v2__power_forecast__types__AvailableZonesResult"}}}}}}}},"components":{"schemas":{"jua_query_v2__power_forecast__types__AvailableZonesResult":{"properties":{"zones":{"items":{"type":"string"},"type":"array","title":"Zones"}},"type":"object","required":["zones"],"title":"AvailableZonesResult","description":"Result for available zones query."}}}}
```

## List available PSR types

> Get a list of available PSR (Production Source) types for power forecasts.\
> \
> This is a metadata endpoint and does not require authentication.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"paths":{"/v1/power-forecast/psr-types":{"get":{"tags":["power-forecast"],"summary":"List available PSR types","description":"Get a list of available PSR (Production Source) types for power forecasts.\n\nThis is a metadata endpoint and does not require authentication.","operationId":"get_power_forecast_psr_types_v1_power_forecast_psr_types_get","parameters":[{"name":"zone_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional zone key(s) to filter PSR types by","title":"Zone Key"},"description":"Optional zone key(s) to filter PSR types by"}],"responses":{"200":{"description":"Successfully retrieved PSR type list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/jua_query_v2__power_forecast__types__AvailablePsrTypesResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"jua_query_v2__power_forecast__types__AvailablePsrTypesResult":{"properties":{"psr_types":{"items":{"type":"string"},"type":"array","title":"Psr Types"}},"type":"object","required":["psr_types"],"title":"AvailablePsrTypesResult","description":"Result for available PSR types query."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## Check if latest forecast uses fallback initial conditions

> Check whether the most recent power forecast was generated using fallback\
> initial conditions (i.e. ENTSO-E source data was unavailable).\
> \
> Returns \`{"is\_fallback": true}\` when the latest forecast used synthetic\
> history, and \`{"is\_fallback": false}\` otherwise.\
> \
> This is a metadata endpoint and does not require authentication.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"paths":{"/v1/power-forecast/fallback-status":{"get":{"tags":["power-forecast"],"summary":"Check if latest forecast uses fallback initial conditions","description":"Check whether the most recent power forecast was generated using fallback\ninitial conditions (i.e. ENTSO-E source data was unavailable).\n\nReturns `{\"is_fallback\": true}` when the latest forecast used synthetic\nhistory, and `{\"is_fallback\": false}` otherwise.\n\nThis is a metadata endpoint and does not require authentication.","operationId":"get_fallback_status_v1_power_forecast_fallback_status_get","parameters":[{"name":"zone_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional zone key to check (e.g. 'DE'). If omitted, checks across all zones.","title":"Zone Key"},"description":"Optional zone key to check (e.g. 'DE'). If omitted, checks across all zones."}],"responses":{"200":{"description":"Fallback status","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List init times that used fallback initial conditions

> Return init times whose forecasts were generated with fallback (estimated)\
> initial conditions.  The frontend uses this to flag specific model runs\
> in the chart legend as potentially degraded.\
> \
> This is a metadata endpoint and does not require authentication.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"paths":{"/v1/power-forecast/fallback-init-times":{"get":{"tags":["power-forecast"],"summary":"List init times that used fallback initial conditions","description":"Return init times whose forecasts were generated with fallback (estimated)\ninitial conditions.  The frontend uses this to flag specific model runs\nin the chart legend as potentially degraded.\n\nThis is a metadata endpoint and does not require authentication.","operationId":"get_fallback_init_times_v1_power_forecast_fallback_init_times_get","parameters":[{"name":"zone_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional zone key to filter by (e.g. 'DE'). If omitted, returns fallback init times across all zones.","title":"Zone Key"},"description":"Optional zone key to filter by (e.g. 'DE'). If omitted, returns fallback init times across all zones."}],"responses":{"200":{"description":"List of fallback init times","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List available init times

> Get available forecast init times with their max prediction horizon.\
> \
> Used by the dashboard to populate the init\_time dropdown when creating a\
> power forecast data source.  Results are ordered newest-first.\
> \
> When \`include\_availability=true\` is passed along with zone\_key and psr\_type\
> filters, the response includes an \`availability\_by\_init\_time\` field that\
> maps each init\_time to the list of (zone\_key, psr\_type) combinations that\
> are available for it. This allows determining which specific combinations\
> are missing for excluded init times without additional API calls.\
> \
> This is a metadata endpoint and does not require authentication.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"paths":{"/v1/power-forecast/init-times":{"get":{"tags":["power-forecast"],"summary":"List available init times","description":"Get available forecast init times with their max prediction horizon.\n\nUsed by the dashboard to populate the init_time dropdown when creating a\npower forecast data source.  Results are ordered newest-first.\n\nWhen `include_availability=true` is passed along with zone_key and psr_type\nfilters, the response includes an `availability_by_init_time` field that\nmaps each init_time to the list of (zone_key, psr_type) combinations that\nare available for it. This allows determining which specific combinations\nare missing for excluded init times without additional API calls.\n\nThis is a metadata endpoint and does not require authentication.","operationId":"get_power_forecast_init_times_v1_power_forecast_init_times_get","parameters":[{"name":"zone_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Zone key(s) to filter init times by","title":"Zone Key"},"description":"Zone key(s) to filter init times by"},{"name":"psr_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"PSR type(s) to filter by. When multiple are given, only init_times available for ALL of them are returned.","title":"Psr Type"},"description":"PSR type(s) to filter by. When multiple are given, only init_times available for ALL of them are returned."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of init times to return","default":192,"title":"Limit"},"description":"Maximum number of init times to return"},{"name":"order","in":"query","required":false,"schema":{"enum":["desc","asc"],"type":"string","description":"Sort direction for init_time: 'desc' (newest first, default) or 'asc' (oldest first)","default":"desc","title":"Order"},"description":"Sort direction for init_time: 'desc' (newest first, default) or 'asc' (oldest first)"},{"name":"include_availability","in":"query","required":false,"schema":{"type":"boolean","description":"When true and zone_key/psr_type are provided, include per-init-time availability breakdown showing which zone/PSR combinations are available for each init_time.","default":false,"title":"Include Availability"},"description":"When true and zone_key/psr_type are provided, include per-init-time availability breakdown showing which zone/PSR combinations are available for each init_time."}],"responses":{"200":{"description":"Successfully retrieved init times","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableInitTimesResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AvailableInitTimesResult":{"properties":{"init_times":{"items":{"$ref":"#/components/schemas/InitTimeInfo"},"type":"array","title":"Init Times"},"availability_by_init_time":{"anyOf":[{"additionalProperties":{"items":{"prefixItems":[{"type":"string"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array"},"type":"object"},{"type":"null"}],"title":"Availability By Init Time"}},"type":"object","required":["init_times"],"title":"AvailableInitTimesResult","description":"Result for available init times query."},"InitTimeInfo":{"properties":{"init_time":{"type":"string","format":"date-time","title":"Init Time"},"max_prediction_timedelta":{"type":"integer","title":"Max Prediction Timedelta"}},"type":"object","required":["init_time","max_prediction_timedelta"],"title":"InitTimeInfo","description":"Information about an available init_time."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```