# Forecast

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

## Get forecast models metadata

> 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]\(<https://docs.jua.ai>).

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"forecast","description":"Query and retrieve weather forecast data from Jua's platform."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/forecast/meta":{"get":{"tags":["forecast"],"summary":"Get forecast models metadata","description":"Retrieve metadata for available forecast models including:\n- Available weather variables for each model\n- Spatial grid resolution information\n- Model identifiers\n\nUse this endpoint to discover which models and variables are available before making data queries.\n\n**Authentication**: Requires API key.\n\nFor detailed model specifications and variable descriptions, visit [docs.jua.ai](https://docs.jua.ai).","operationId":"get_meta_v1_forecast_meta_get","parameters":[{"name":"models","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Model"}},{"type":"null"}],"description":"Filter by specific model(s). If not provided, returns all models","title":"Models"},"description":"Filter by specific model(s). If not provided, returns all models"}],"responses":{"200":{"description":"Successfully retrieved model metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaQueryResult"}}}},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Model":{"type":"string","enum":["ept2","ept2_early","ept2_e","ept2_rr","ept2_hrrr","ept1_5","ept1_5_early","aifs","aurora","icon_global","icon_eu","ecmwf_ifs_single","ecmwf_ens","ecmwf_ec46","ept2_reasoning","ecmwf_aifs025_ensemble","meteofrance_arome_france_hd","gfs_global_single","noaa_gfs_single","gfs_global_ensemble","icon_d2","gfs_graphcast025","knmi_harmonie_arome_europe","knmi_harmonie_arome_netherlands","ukmo_global_deterministic_10km","ukmo_uk_deterministic_2km"],"title":"Model"},"MetaQueryResult":{"properties":{"models":{"items":{"$ref":"#/components/schemas/ModelInfo"},"type":"array","title":"Models","description":"List of model metadata"}},"type":"object","required":["models"],"title":"MetaQueryResult","description":"Result containing metadata for one or more forecast models."},"ModelInfo":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the model"},"grid":{"anyOf":[{"$ref":"#/components/schemas/Grid"},{"type":"null"}],"description":"Human readable grid description"},"is_ensemble_model":{"type":"boolean","title":"Is Ensemble Model","description":"Whether the model is an ensemble model","default":false},"variables":{"items":{"$ref":"#/components/schemas/CustomerVariable"},"type":"array","title":"Variables","description":"The variables of the model"},"daily_runs":{"additionalProperties":{"$ref":"#/components/schemas/RunDefinition"},"propertyNames":{"format":"time"},"type":"object","title":"Daily Runs","description":"The daily runs of the model"},"variable_units":{"additionalProperties":{"type":"string"},"type":"object","title":"Variable Units","description":"SI unit for each variable (e.g. K, Pa, m/s)","readOnly":true},"grid_bounds":{"anyOf":[{"$ref":"#/components/schemas/GridBounds"},{"type":"null"}],"description":"The bounds of the grid","readOnly":true},"is_limited_model":{"type":"boolean","title":"Is Limited Model","description":"Limited models provide limited capabilities, such as being restricted to point forecasts and no access to historical data","readOnly":true},"min_step_minutes":{"type":"integer","title":"Min Step Minutes","description":"Minimum temporal step size across all runs in minutes","readOnly":true}},"type":"object","required":["name","variables","variable_units","grid_bounds","is_limited_model","min_step_minutes"],"title":"ModelInfo"},"Grid":{"type":"string","enum":["720x1440","2160x4320","1440x2880","2220x4440","2221x4440","451x900","720x900_europe","721x1201_europe","657x1377","exact"],"title":"Grid"},"CustomerVariable":{"type":"string","enum":["air_temperature_at_height_level_2m","surface_temperature","dew_point_temperature_at_height_level_2m","relative_humidity_at_height_level_2m","air_pressure_at_mean_sea_level","surface_air_pressure","wind_speed_at_height_level_10m","wind_direction_at_height_level_10m","wind_speed_at_height_level_100m","wind_direction_at_height_level_100m","wind_speed_at_height_level_20m","wind_speed_at_height_level_40m","wind_speed_at_height_level_60m","wind_speed_at_height_level_80m","wind_speed_at_height_level_120m","wind_speed_at_height_level_140m","wind_speed_at_height_level_160m","wind_speed_at_height_level_180m","wind_speed_at_height_level_200m","wind_direction_at_height_level_200m","air_density_at_height_level_2m","geopotential_at_pressure_level_50000Pa","eastward_wind_at_height_level_10m","northward_wind_at_height_level_10m","eastward_wind_at_height_level_100m","northward_wind_at_height_level_100m","wind_speed_of_gust_at_height_level_10m_max","surface_direct_downwelling_shortwave_flux_sum_1h","surface_downwelling_longwave_flux_sum_1h","surface_downwelling_shortwave_flux_sum_1h","surface_downwelling_longwave_flux_sum_6h","surface_downwelling_shortwave_flux_sum_6h","surface_net_downward_longwave_flux_sum_1h","surface_net_downward_shortwave_flux_sum_1h","surface_net_downward_longwave_flux_sum_6h","surface_net_downward_shortwave_flux_sum_6h","surface_direct_along_beam_shortwave_flux_sum_6h","cloud_area_fraction_at_entire_atmosphere","cloud_area_fraction_at_entire_atmosphere_high_type","cloud_area_fraction_at_entire_atmosphere_medium_type","cloud_area_fraction_at_entire_atmosphere_low_type","precipitation_amount_sum_1h","precipitation_amount_sum_3h","precipitation_amount_sum_6h","precipitation_amount_sum_12h","precipitation_amount_sum_24h","atmosphere_convective_available_potential_energy","predominant_precipitation_type_at_surface","sea_surface_temperature"],"title":"CustomerVariable","description":"Weather variable name with units:\n  • air_temperature_at_height_level_2m: K\n  • surface_temperature: K\n  • dew_point_temperature_at_height_level_2m: K\n  • relative_humidity_at_height_level_2m: %\n  • air_pressure_at_mean_sea_level: Pa\n  • surface_air_pressure: Pa\n  • wind_speed_at_height_level_10m: m/s\n  • wind_direction_at_height_level_10m: degrees\n  • wind_speed_at_height_level_100m: m/s\n  • wind_direction_at_height_level_100m: degrees\n  • wind_speed_at_height_level_20m: m/s\n  • wind_speed_at_height_level_40m: m/s\n  • wind_speed_at_height_level_60m: m/s\n  • wind_speed_at_height_level_80m: m/s\n  • wind_speed_at_height_level_120m: m/s\n  • wind_speed_at_height_level_140m: m/s\n  • wind_speed_at_height_level_160m: m/s\n  • wind_speed_at_height_level_180m: m/s\n  • wind_speed_at_height_level_200m: m/s\n  • wind_direction_at_height_level_200m: degrees\n  • air_density_at_height_level_2m: kg/m³\n  • geopotential_at_pressure_level_50000Pa: m²/s²\n  • eastward_wind_at_height_level_10m: m/s\n  • northward_wind_at_height_level_10m: m/s\n  • eastward_wind_at_height_level_100m: m/s\n  • northward_wind_at_height_level_100m: m/s\n  • wind_speed_of_gust_at_height_level_10m_max: m/s\n  • surface_direct_downwelling_shortwave_flux_sum_1h: J/m²\n  • surface_downwelling_longwave_flux_sum_1h: J/m²\n  • surface_downwelling_shortwave_flux_sum_1h: J/m²\n  • surface_downwelling_longwave_flux_sum_6h: J/m²\n  • surface_downwelling_shortwave_flux_sum_6h: J/m²\n  • surface_net_downward_longwave_flux_sum_1h: J/m²\n  • surface_net_downward_shortwave_flux_sum_1h: J/m²\n  • surface_net_downward_longwave_flux_sum_6h: J/m²\n  • surface_net_downward_shortwave_flux_sum_6h: J/m²\n  • surface_direct_along_beam_shortwave_flux_sum_6h: J/m²\n  • cloud_area_fraction_at_entire_atmosphere: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_high_type: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_medium_type: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_low_type: fraction (0-1)\n  • precipitation_amount_sum_1h: mm\n  • precipitation_amount_sum_3h: mm\n  • precipitation_amount_sum_6h: mm\n  • precipitation_amount_sum_12h: mm\n  • precipitation_amount_sum_24h: mm\n  • atmosphere_convective_available_potential_energy: J/kg\n  • predominant_precipitation_type_at_surface: categorical\n  • sea_surface_temperature: K"},"RunDefinition":{"properties":{"lead_time_set":{"items":{"type":"integer"},"type":"array","title":"Lead Time Set"},"dissemination_time":{"anyOf":[{"type":"string","format":"time"},{"type":"null"}],"title":"Dissemination Time"},"min_step_minutes":{"type":"integer","title":"Min Step Minutes","description":"Minimum temporal step size between consecutive lead times in minutes.\n\nReturns 60 (hourly) as default if step cannot be determined.","readOnly":true}},"type":"object","required":["lead_time_set","min_step_minutes"],"title":"RunDefinition"},"GridBounds":{"properties":{"min_lat":{"type":"number","title":"Min Lat"},"max_lat":{"type":"number","title":"Max Lat"},"min_lon":{"type":"number","title":"Min Lon"},"max_lon":{"type":"number","title":"Max Lon"}},"type":"object","required":["min_lat","max_lat","min_lon","max_lon"],"title":"GridBounds"},"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 forecasts

> 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]\(<https://docs.jua.ai>).

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"forecast","description":"Query and retrieve weather forecast data from Jua's platform."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/forecast/available-forecasts":{"get":{"tags":["forecast"],"summary":"List available forecasts","description":"List all available forecast initialization times for specified models with optional time filtering.\n\nReturns forecast init times and maximum available lead times, useful for:\n- Discovering historical forecast availability\n- Finding specific forecast runs\n- Monitoring forecast data updates\n\n**Authentication**: Requires API key.\n\nResults are paginated. Use `limit` and `offset` parameters to navigate through large result sets.\n\nFor forecast schedules and update frequencies, see [docs.jua.ai](https://docs.jua.ai).","operationId":"get_available_forecasts_v1_forecast_available_forecasts_get","parameters":[{"name":"models","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Model"}},{"type":"null"}],"description":"Filter by specific model(s). If not provided, returns all accessible models with Clickhouse data source","title":"Models"},"description":"Filter by specific model(s). If not provided, returns all accessible models with Clickhouse data source"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only return forecasts initialized on or after this datetime (optional)","title":"Since"},"description":"Only return forecasts initialized on or after this datetime (optional)"},{"name":"before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only return forecasts initialized before this datetime (optional)","title":"Before"},"description":"Only return forecasts initialized before this datetime (optional)"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Maximum number of results to return","default":20,"title":"Limit"},"description":"Maximum number of results to return"},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Number of results to skip for pagination","default":0,"title":"Offset"},"description":"Number of results to skip for pagination"},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Synthetic invocation time for backtesting (ISO 8601 UTC). Only returns forecasts disseminated at or before this time.","title":"As Of"},"description":"Synthetic invocation time for backtesting (ISO 8601 UTC). Only returns forecasts disseminated at or before this time."}],"responses":{"200":{"description":"Successfully retrieved available forecasts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableForecastsQueryResult"}}}},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"},"422":{"description":"Validation error - invalid model selection"}}}}},"components":{"schemas":{"Model":{"type":"string","enum":["ept2","ept2_early","ept2_e","ept2_rr","ept2_hrrr","ept1_5","ept1_5_early","aifs","aurora","icon_global","icon_eu","ecmwf_ifs_single","ecmwf_ens","ecmwf_ec46","ept2_reasoning","ecmwf_aifs025_ensemble","meteofrance_arome_france_hd","gfs_global_single","noaa_gfs_single","gfs_global_ensemble","icon_d2","gfs_graphcast025","knmi_harmonie_arome_europe","knmi_harmonie_arome_netherlands","ukmo_global_deterministic_10km","ukmo_uk_deterministic_2km"],"title":"Model"},"AvailableForecastsQueryResult":{"properties":{"forecasts_per_model":{"additionalProperties":{"items":{"$ref":"#/components/schemas/ForecastInfo"},"type":"array"},"propertyNames":{"$ref":"#/components/schemas/Model"},"type":"object","title":"Forecasts Per Model","description":"Mapping of model identifiers to lists of available forecasts"},"pagination":{"anyOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"null"}],"description":"Pagination information if results were paginated"}},"type":"object","required":["forecasts_per_model"],"title":"AvailableForecastsQueryResult","description":"Result containing available forecast times per model."},"ForecastInfo":{"properties":{"init_time":{"type":"string","title":"Init Time","description":"Forecast initialization time"},"max_prediction_timedelta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Prediction Timedelta","description":"Maximum available lead time in minutes for this forecast"},"dissemination_time":{"type":"string","title":"Dissemination Time","description":"Forecast step dissemination time"}},"type":"object","required":["init_time","dissemination_time"],"title":"ForecastInfo","description":"Information about a single available forecast."},"Pagination":{"properties":{"limit":{"type":"integer","title":"Limit","default":100},"offset":{"type":"integer","title":"Offset","default":0}},"type":"object","title":"Pagination"}}}}
```

## Count available forecasts

> 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]\(<https://docs.jua.ai>).

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"forecast","description":"Query and retrieve weather forecast data from Jua's platform."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/forecast/count":{"get":{"tags":["forecast"],"summary":"Count available forecasts","description":"Get the total count of available forecasts per model with optional time filtering.\n\nUseful for:\n- Checking data availability before querying\n- Monitoring forecast archive growth\n- Validating expected data coverage\n\n**Authentication**: Requires API key.\n\nFor more information on forecast availability, see [docs.jua.ai](https://docs.jua.ai).","operationId":"get_count_v1_forecast_count_get","parameters":[{"name":"models","in":"query","required":true,"schema":{"type":"array","items":{"$ref":"#/components/schemas/Model"},"minItems":1,"description":"Filter by specific model(s)","title":"Models"},"description":"Filter by specific model(s)"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only count forecasts initialized on or after this datetime (optional)","title":"Since"},"description":"Only count forecasts initialized on or after this datetime (optional)"},{"name":"before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only count forecasts initialized before this datetime (optional)","title":"Before"},"description":"Only count forecasts initialized before this datetime (optional)"},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Synthetic invocation time for backtesting (ISO 8601 UTC). Only counts forecasts disseminated at or before this time.","title":"As Of"},"description":"Synthetic invocation time for backtesting (ISO 8601 UTC). Only counts forecasts disseminated at or before this time."}],"responses":{"200":{"description":"Successfully counted forecasts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotalNumberOfForecastsQueryResult"}}}},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"},"422":{"description":"Validation error - invalid model selection"}}}}},"components":{"schemas":{"Model":{"type":"string","enum":["ept2","ept2_early","ept2_e","ept2_rr","ept2_hrrr","ept1_5","ept1_5_early","aifs","aurora","icon_global","icon_eu","ecmwf_ifs_single","ecmwf_ens","ecmwf_ec46","ept2_reasoning","ecmwf_aifs025_ensemble","meteofrance_arome_france_hd","gfs_global_single","noaa_gfs_single","gfs_global_ensemble","icon_d2","gfs_graphcast025","knmi_harmonie_arome_europe","knmi_harmonie_arome_netherlands","ukmo_global_deterministic_10km","ukmo_uk_deterministic_2km"],"title":"Model"},"TotalNumberOfForecastsQueryResult":{"properties":{"forecasts_per_model":{"additionalProperties":{"type":"integer"},"propertyNames":{"$ref":"#/components/schemas/Model"},"type":"object","title":"Forecasts Per Model","description":"Mapping of model identifiers to the number of available forecasts"}},"type":"object","required":["forecasts_per_model"],"title":"TotalNumberOfForecastsQueryResult","description":"Result containing forecast counts per model."}}}}
```

## Get latest forecast initialization time

> 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]\(<https://docs.jua.ai>).

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"forecast","description":"Query and retrieve weather forecast data from Jua's platform."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/forecast/latest-init-time":{"get":{"tags":["forecast"],"summary":"Get latest forecast initialization time","description":"Retrieve the most recent forecast initialization time available for each model.\n\nReturns:\n- Latest init_time for each model\n- Maximum available lead time for that forecast\n\nUseful for:\n- Getting real-time forecast data with `init_time='latest'`\n- Monitoring forecast update status\n- Validating forecast freshness\n\n**Authentication**: Requires API key.\n\nFor forecast update schedules, see [docs.jua.ai](https://docs.jua.ai).","operationId":"get_latest_init_time_v1_forecast_latest_init_time_get","parameters":[{"name":"models","in":"query","required":true,"schema":{"type":"array","items":{"$ref":"#/components/schemas/Model"},"minItems":1,"description":"Filter by specific model(s)","title":"Models"},"description":"Filter by specific model(s)"},{"name":"min_prediction_timedelta","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Minimum required lead time in minutes","default":0,"title":"Min Prediction Timedelta"},"description":"Minimum required lead time in minutes"},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Synthetic invocation time for backtesting (ISO 8601 UTC). Returns the latest init time that was disseminated at or before this time.","title":"As Of"},"description":"Synthetic invocation time for backtesting (ISO 8601 UTC). Returns the latest init time that was disseminated at or before this time."}],"responses":{"200":{"description":"Successfully retrieved latest forecast info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatestForecastInfoQueryResult"}}}},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"},"422":{"description":"Validation error - models list must contain at least one model"}}}}},"components":{"schemas":{"Model":{"type":"string","enum":["ept2","ept2_early","ept2_e","ept2_rr","ept2_hrrr","ept1_5","ept1_5_early","aifs","aurora","icon_global","icon_eu","ecmwf_ifs_single","ecmwf_ens","ecmwf_ec46","ept2_reasoning","ecmwf_aifs025_ensemble","meteofrance_arome_france_hd","gfs_global_single","noaa_gfs_single","gfs_global_ensemble","icon_d2","gfs_graphcast025","knmi_harmonie_arome_europe","knmi_harmonie_arome_netherlands","ukmo_global_deterministic_10km","ukmo_uk_deterministic_2km"],"title":"Model"},"LatestForecastInfoQueryResult":{"properties":{"forecasts_per_model":{"additionalProperties":{"$ref":"#/components/schemas/LatestForecastInfo"},"propertyNames":{"$ref":"#/components/schemas/Model"},"type":"object","title":"Forecasts Per Model","description":"Mapping of model identifiers to their latest forecast information"}},"type":"object","required":["forecasts_per_model"],"title":"LatestForecastInfoQueryResult","description":"Result containing the latest forecast information per model."},"LatestForecastInfo":{"properties":{"init_time":{"type":"string","title":"Init Time","description":"Latest forecast initialization time (ISO 8601 format)"},"prediction_timedelta":{"type":"integer","title":"Prediction Timedelta","description":"Maximum available lead time in minutes for this forecast"},"dissemination_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dissemination Time","description":"Forecast step dissemination time"}},"type":"object","required":["init_time","prediction_timedelta"],"title":"LatestForecastInfo","description":"Information about the latest available forecast for a model."}}}}
```

## Get forecast dissemination status

> 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]\(<https://docs.jua.ai>).

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"forecast","description":"Query and retrieve weather forecast data from Jua's platform."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/forecast/dissemination-status":{"get":{"tags":["forecast"],"summary":"Get forecast dissemination status","description":"Retrieve dissemination status and delay statistics for forecasts.\n\nReturns for each model:\n- Status for individual forecasts (init_time, delay, whether missing)\n- Aggregated delay statistics (min, max, mean, median, std, percentiles)\n- Missing forecast percentage\n\nUseful for:\n- Monitoring forecast delivery timeliness\n- Identifying delayed or missing forecasts\n- Analyzing dissemination performance over time\n\n**Authentication**: Requires API key.\n\nResults are paginated. Use `limit` and `offset` parameters to navigate through large result sets.\n\nFor forecast schedules and SLA information, see [docs.jua.ai](https://docs.jua.ai).","operationId":"get_forecast_dissemination_status_v1_forecast_dissemination_status_get","parameters":[{"name":"models","in":"query","required":true,"schema":{"type":"array","items":{"$ref":"#/components/schemas/Model"},"minItems":1,"description":"Filter by specific model(s)","title":"Models"},"description":"Filter by specific model(s)"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only analyze forecasts initialized on or after this datetime (optional)","title":"Since"},"description":"Only analyze forecasts initialized on or after this datetime (optional)"},{"name":"before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only analyze forecasts initialized before this datetime (optional)","title":"Before"},"description":"Only analyze forecasts initialized before this datetime (optional)"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Maximum number of forecasts to analyze per model","default":100,"title":"Limit"},"description":"Maximum number of forecasts to analyze per model"},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Number of forecasts to skip for pagination","default":0,"title":"Offset"},"description":"Number of forecasts to skip for pagination"},{"name":"only_stats","in":"query","required":false,"schema":{"type":"boolean","description":"Only return delay statistics per init time (without forecast status)","default":false,"title":"Only Stats"},"description":"Only return delay statistics per init time (without forecast status)"}],"responses":{"200":{"description":"Successfully retrieved dissemination status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisseminationStatus"}}}},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"},"422":{"description":"Validation error - invalid model selection"}}}}},"components":{"schemas":{"Model":{"type":"string","enum":["ept2","ept2_early","ept2_e","ept2_rr","ept2_hrrr","ept1_5","ept1_5_early","aifs","aurora","icon_global","icon_eu","ecmwf_ifs_single","ecmwf_ens","ecmwf_ec46","ept2_reasoning","ecmwf_aifs025_ensemble","meteofrance_arome_france_hd","gfs_global_single","noaa_gfs_single","gfs_global_ensemble","icon_d2","gfs_graphcast025","knmi_harmonie_arome_europe","knmi_harmonie_arome_netherlands","ukmo_global_deterministic_10km","ukmo_uk_deterministic_2km"],"title":"Model"},"DisseminationStatus":{"properties":{"status_per_model":{"additionalProperties":{"$ref":"#/components/schemas/ModelDisseminationStatus"},"propertyNames":{"$ref":"#/components/schemas/Model"},"type":"object","title":"Status Per Model","description":"Status per model"}},"type":"object","required":["status_per_model"],"title":"DisseminationStatus"},"ModelDisseminationStatus":{"properties":{"status":{"items":{"$ref":"#/components/schemas/ForecastDisseminationStatus"},"type":"array","title":"Status","description":"Status for the model"},"delay_stats_per_init_time":{"additionalProperties":{"$ref":"#/components/schemas/DisseminationStats"},"type":"object","title":"Delay Stats Per Init Time","description":"Delay statistics per init time (without date, e.g., '00:00', '06:00')"}},"type":"object","required":["status","delay_stats_per_init_time"],"title":"ModelDisseminationStatus"},"ForecastDisseminationStatus":{"properties":{"init_time":{"type":"string","title":"Init Time","description":"Forecast initialization time"},"delay":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delay","description":"Delay in minutes"},"is_missing":{"type":"boolean","title":"Is Missing","description":"Whether the forecast is missing","default":false},"dissemination_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dissemination Time","description":"Forecast dissemination time"},"expected_dissemination_time":{"anyOf":[{"type":"string","format":"time"},{"type":"null"}],"title":"Expected Dissemination Time","description":"Expected dissemination time"},"max_prediction_timedelta":{"type":"integer","title":"Max Prediction Timedelta","description":"Maximum prediction timedelta for the forecast"},"expected_max_prediction_timedelta":{"type":"integer","title":"Expected Max Prediction Timedelta","description":"Expected maximum prediction timedelta for the forecast"},"is_delayed":{"type":"boolean","title":"Is Delayed","description":"Whether the forecast is delayed","readOnly":true}},"type":"object","required":["init_time","max_prediction_timedelta","expected_max_prediction_timedelta","is_delayed"],"title":"ForecastDisseminationStatus"},"DisseminationStats":{"properties":{"number_of_data_points":{"type":"integer","title":"Number Of Data Points","description":"Number of data points.Tracking started on '2025-10-29"},"min":{"type":"number","title":"Min","description":"Minimum delay in minutes"},"max":{"type":"number","title":"Max","description":"Maximum delay in minutes"},"mean":{"type":"number","title":"Mean","description":"Mean delay in minutes"},"median":{"type":"number","title":"Median","description":"Median delay in minutes"},"std":{"type":"number","title":"Std","description":"Standard deviation of delay in minutes"},"q90":{"type":"number","title":"Q90","description":"90th percentile of delay in minutes"},"q99":{"type":"number","title":"Q99","description":"99th percentile of delay in minutes"},"in_time_percentage":{"type":"number","title":"In Time Percentage","description":"Percentage of forecasts in time"},"missing_percentage":{"type":"number","title":"Missing Percentage","description":"Percentage of missing forecasts"},"expected_dissemination_time":{"type":"string","format":"time","title":"Expected Dissemination Time","description":"Expected dissemination time (time of day) as reference"},"dissemination_time_min":{"type":"string","format":"time","title":"Dissemination Time Min","description":"Minimum dissemination time (time of day)"},"dissemination_time_max":{"type":"string","format":"time","title":"Dissemination Time Max","description":"Maximum dissemination time (time of day)"},"dissemination_time_mean":{"type":"string","format":"time","title":"Dissemination Time Mean","description":"Mean dissemination time (time of day)"},"dissemination_time_median":{"type":"string","format":"time","title":"Dissemination Time Median","description":"Median dissemination time (time of day)"},"dissemination_time_q90":{"type":"string","format":"time","title":"Dissemination Time Q90","description":"90th percentile of dissemination time (time of day)"},"dissemination_time_q99":{"type":"string","format":"time","title":"Dissemination Time Q99","description":"99th percentile of dissemination time (time of day)"}},"type":"object","required":["number_of_data_points","min","max","mean","median","std","q90","q99","in_time_percentage","missing_percentage","expected_dissemination_time","dissemination_time_min","dissemination_time_max","dissemination_time_mean","dissemination_time_median","dissemination_time_q90","dissemination_time_q99"],"title":"DisseminationStats"}}}}
```

## Query forecast data

> 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]\(<https://docs.jua.ai/pricing).\\>
> \
> \*\*Authentication\*\*: Requires API key.\
> \
> For detailed query examples and best practices, visit \[docs.jua.ai]\(<https://docs.jua.ai>).

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"forecast","description":"Query and retrieve weather forecast data from Jua's platform."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/forecast/data":{"post":{"tags":["forecast"],"summary":"Query forecast data","description":"Main endpoint for querying weather forecast data with full flexibility.\n\n## Features\n- Query by location (point, area, market zone) and time\n- Select specific models and weather variables\n- Support for aggregation and grouping\n- Multiple response formats (JSON, Apache Arrow)\n- Optional streaming for large datasets\n\n## Response Formats\n- **JSON** (`format=json`): Returns columnar JSON `{column: [values], ...}` suitable for small to medium datasets\n- **Arrow** (`format=arrow`): Returns Apache Arrow IPC stream for efficient large dataset handling\n\n## Streaming\nSet `stream=true` for streaming responses with Arrow format. Recommended for queries returning >100k rows.\n\n## Cost Management\nQueries are billed based on data volume, models, and variables. Use:\n- `request_credit_limit`: Set maximum credits to prevent unexpectedly large charges\n- `/cost` endpoint: Estimate costs before executing\n\nFor more details on how the costs are computed, visit [docs.jua.ai/pricing](https://docs.jua.ai/pricing).\n\n**Authentication**: Requires API key.\n\nFor detailed query examples and best practices, visit [docs.jua.ai](https://docs.jua.ai).","operationId":"post_data_v1_forecast_data_post","parameters":[{"name":"format","in":"query","required":false,"schema":{"enum":["json","arrow"],"type":"string","description":"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":"json","title":"Format"},"description":"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"},{"name":"stream","in":"query","required":false,"schema":{"type":"boolean","description":"Enable streaming response (only with format=arrow). Recommended for queries returning >100k rows.","default":false,"title":"Stream"},"description":"Enable streaming response (only with format=arrow). Recommended for queries returning >100k rows."},{"name":"request_credit_limit","in":"query","required":false,"schema":{"type":"number","minimum":0,"description":"Maximum credits allowed for this request. Query will fail if estimated cost exceeds this limit","default":50,"title":"Request Credit Limit"},"description":"Maximum credits allowed for this request. Query will fail if estimated cost exceeds this limit"},{"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/ForecastQuery"}}}},"responses":{"200":{"description":"Successfully retrieved forecast data","content":{"application/json":{"schema":{}},"application/vnd.apache.arrow.stream":{"description":"Apache Arrow IPC stream format"}}},"400":{"description":"Invalid query parameters or response size exceeded"},"401":{"description":"Authentication required"},"402":{"description":"Insufficient credits"},"403":{"description":"Insufficient permissions or model not in subscription"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ForecastQuery":{"properties":{"models":{"anyOf":[{"items":{"$ref":"#/components/schemas/Model"},"type":"array"},{"type":"null"}],"title":"Models","description":"List of forecast model identifiers to query (e.g., ['ept2', 'aifs']). Required if model_runs is not specified."},"geo":{"$ref":"#/components/schemas/GeoFilter","description":"Geographic filter specifying the query location(s) or region(s)"},"init_time":{"anyOf":[{"type":"integer","minimum":0,"description":"Offset from latest forecast (0 = latest, 1 = second latest, etc.)"},{"type":"string","format":"date-time"},{"type":"string","pattern":"^latest(-\\d+)?$","description":"Use 'latest' or 'latest-N' for relative init times"},{"items":{"anyOf":[{"type":"integer","minimum":0,"description":"Offset from latest forecast (0 = latest, 1 = second latest, etc.)"},{"type":"string","format":"date-time"},{"type":"string","pattern":"^latest(-\\d+)?$","description":"Use 'latest' or 'latest-N' for relative init times"}]},"type":"array"},{"$ref":"#/components/schemas/TimeSlice"},{"$ref":"#/components/schemas/PreferredHours"},{"type":"null"}],"title":"Init Time","description":"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."},"model_runs":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"integer","minimum":0,"description":"Offset from latest forecast (0 = latest, 1 = second latest, etc.)"},{"type":"string","format":"date-time"},{"type":"string","pattern":"^latest(-\\d+)?$","description":"Use 'latest' or 'latest-N' for relative init times"},{"items":{"anyOf":[{"type":"integer","minimum":0,"description":"Offset from latest forecast (0 = latest, 1 = second latest, etc.)"},{"type":"string","format":"date-time"},{"type":"string","pattern":"^latest(-\\d+)?$","description":"Use 'latest' or 'latest-N' for relative init times"}]},"type":"array"},{"$ref":"#/components/schemas/TimeSlice"},{"$ref":"#/components/schemas/PreferredHours"}]},"propertyNames":{"$ref":"#/components/schemas/Model"},"type":"object"},{"type":"null"}],"title":"Model Runs","description":"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."},"time":{"anyOf":[{"type":"string","format":"date-time"},{"items":{"type":"string","format":"date-time"},"type":"array"},{"$ref":"#/components/schemas/TimeSlice"},{"type":"null"}],"title":"Time","description":"Filter by specific forecast valid times (as opposed to lead times). Accepts datetime, list of datetimes, or time range"},"variables":{"items":{"$ref":"#/components/schemas/CustomerVariable"},"type":"array","title":"Variables","description":"List of weather variables to query (e.g., 'air_temperature_at_height_level_2m', 'wind_speed_at_height_level_100m'). If empty, returns all variables available for the selected models"},"prediction_timedelta":{"anyOf":[{"type":"integer"},{"$ref":"#/components/schemas/PredictionTimedeltaSlice"},{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Prediction Timedelta","description":"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. "},"latest_min_prediction_timedelta":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Latest Min Prediction Timedelta","description":"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_unit":{"type":"string","enum":["h","m","d","hour","hourly","minute","minutes","day","days"],"title":"Timedelta Unit","description":"Time scale to use for the query. Can be 'h' for hours, 'm' for minutes, 'd' for days","default":"h"},"temporal_resolution":{"anyOf":[{"type":"integer","enum":[15,30,60,120,180,240,300,360]},{"type":"null"}],"title":"Temporal Resolution","description":"Requested temporal resolution in minutes"},"group_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/GroupByKey"},"type":"array"},{"type":"null"}],"title":"Group By","description":"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"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/OrderByItem_Union_Coordinates__CustomerVariable__"},"type":"array"},{"type":"null"}],"title":"Order By","description":"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'}"},"aggregation":{"anyOf":[{"items":{"$ref":"#/components/schemas/Aggregation"},"type":"array"},{"type":"null"}],"title":"Aggregation","description":"List of aggregation functions to apply when grouping (e.g., ['avg', 'std']). Requires 'group_by' to be specified"},"weighting":{"anyOf":[{"$ref":"#/components/schemas/Weighting"},{"type":"null"}],"description":"Optional weighting scheme for geographic aggregation (e.g., by wind/solar capacity or population)"},"include_time":{"type":"boolean","title":"Include Time","description":"Include the forecast valid time (init_time + prediction_timedelta) as a column in results","default":false},"time_zone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Zone","description":"IANA time zone name for time formatting (e.g., 'Europe/Berlin', 'America/New_York'). Defaults to UTC"},"pagination":{"anyOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"null"}],"description":"Pagination parameters for limiting result size. Requires 'order_by' to be specified"},"were_variables_explicitly_requested":{"type":"boolean","title":"Were Variables Explicitly Requested","description":"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_filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/ValueFilter"},"type":"array"},{"type":"null"}],"title":"Value Filters","description":"Post-aggregation value filters applied as an outermost SQL wrapper. Used by alert evaluation to push threshold conditions into ClickHouse."},"as_of":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"As Of","description":"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."}},"type":"object","required":["geo"],"title":"ForecastQuery","description":"Main query object for retrieving weather forecast data.\n\nSupports flexible querying by location, time, variables, and models with optional\naggregation, grouping, and weighting capabilities.\n\nTwo modes of specifying models and init_times:\n1. Classic mode: Use `models` + `init_time` (same init_time for all models)\n2. Model runs mode: Use `model_runs` (per-model init_time specification)\n\nThese modes are mutually exclusive."},"Model":{"type":"string","enum":["ept2","ept2_early","ept2_e","ept2_rr","ept2_hrrr","ept1_5","ept1_5_early","aifs","aurora","icon_global","icon_eu","ecmwf_ifs_single","ecmwf_ens","ecmwf_ec46","ept2_reasoning","ecmwf_aifs025_ensemble","meteofrance_arome_france_hd","gfs_global_single","noaa_gfs_single","gfs_global_ensemble","icon_d2","gfs_graphcast025","knmi_harmonie_arome_europe","knmi_harmonie_arome_netherlands","ukmo_global_deterministic_10km","ukmo_uk_deterministic_2km"],"title":"Model"},"GeoFilter":{"properties":{"type":{"type":"string","enum":["point","bounding_box","polygon","market_zone","country_key","poi"],"title":"Type","description":"Geographic filter type. 'point': Single location or list of [latitude, longitude] coordinates. 'bounding_box': Rectangular area defined by [[lat_min, lon_min], [lat_max, lon_max]]. 'polygon': Custom area defined by list of [latitude, longitude] coordinates. 'market_zone': Predefined energy market zone codes (e.g., 'DE', 'FR'). 'country_key': ISO country codes (e.g., 'DE', 'US'). 'poi': Point of Interest reference(s) with coordinates and optional id/label."},"value":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},{"items":{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},"type":"array"},{"prefixItems":[{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2}],"type":"array","maxItems":2,"minItems":2},{"items":{"prefixItems":[{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2}],"type":"array","maxItems":2,"minItems":2},"type":"array"},{"items":{"items":{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},"type":"array"},"type":"array"},{"type":"string","enum":["AD","AE","AF","AG","AL","AM","AO","AR","AT","AU-LH","AU-NSW","AU-NT","AU-QLD","AU-SA","AU-TAS","AU-TAS-CBI","AU-TAS-FI","AU-TAS-KI","AU-VIC","AU-WA","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BM","BN","BO","BR-CS","BR-N","BR-NE","BR-S","BS","BT","BW","BY","BZ","CA-AB","CA-BC","CA-MB","CA-NB","CA-NL","CA-NS","CA-NT","CA-NU","CA-ON","CA-PE","CA-QC","CA-SK","CA-YT","CD","CF","CG","CH","CI","CL-CHP","CL-SEA","CL-SEM","CL-SEN","CM","CN","CO","CR","CU","CV","CW","CY","CZ","DE","DJ","DK-BHM","DK-DK1","DK-DK2","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ES-CN-FV","ES-CN-GC","ES-CN-HI","ES-CN-IG","ES-CN-LP","ES-CN-LZ","ES-CN-TE","ES-IB-FO","ES-IB-IZ","ES-IB-MA","ES-IB-ME","ET","FI","FJ","FK","FM","FO-MI","FO-SI","FR","FR-COR","GA","GB","GB-NIR","GB-ORK","GB-ZET","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GT","GU","GW","GY","HK","HN","HR","HT","HU","ID","IE","IL","IM","IN-AN","IN-EA","IN-NE","IN-NO","IN-SO","IN-WE","IQ","IR","IS","IT-CNO","IT-CSO","IT-NO","IT-SAR","IT-SIC","IT-SO","JE","JM","JO","JP-CB","JP-CG","JP-HKD","JP-HR","JP-KN","JP-KY","JP-ON","JP-SK","JP-TH","JP-TK","KE","KG","KH","KM","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MD","ME","MG","MK","ML","MM","MN","MQ","MR","MT","MU","MV","MW","MX","MY-EM","MY-WM","MZ","NA","NC","NE","NG","NI","NL","NO-NO1","NO-NO2","NO-NO3","NO-NO4","NO-NO5","NP","NZ","NZ-NZC","NZ-NZST","OM","PA","PE","PF","PG","PH-LU","PH-MI","PH-VI","PK","PL","PM","PR","PS","PT","PT-AC","PT-MA","PW","PY","QA","RE","RO","RS","RU-1","RU-2","RU-AS","RU-EU","RU-FE","RU-KGD","RW","SA","SB","SC","SD","SE-SE1","SE-SE2","SE-SE3","SE-SE4","SG","SI","SJ","SK","SL","SN","SO","SR","SS","ST","SV","SY","SZ","TD","TG","TH","TJ","TL","TM","TN","TO","TR","TT","TW","TZ","UA","UA-CR","UG","US-AK","US-AK-SEAPA","US-CAL-BANC","US-CAL-CISO","US-CAL-IID","US-CAL-LDWP","US-CAL-TIDC","US-CAR-CPLE","US-CAR-CPLW","US-CAR-DUK","US-CAR-SC","US-CAR-SCEG","US-CENT-SPA","US-CENT-SWPP","US-FLA-FMPP","US-FLA-FPC","US-FLA-FPL","US-FLA-GVL","US-FLA-HST","US-FLA-JEA","US-FLA-SEC","US-FLA-TAL","US-FLA-TEC","US-HI","US-MIDA-PJM","US-MIDW-AECI","US-MIDW-LGEE","US-MIDW-MISO","US-NE-ISNE","US-NW-AVA","US-NW-BPAT","US-NW-CHPD","US-NW-DOPD","US-NW-GCPD","US-NW-IPCO","US-NW-NEVP","US-NW-NWMT","US-NW-PACE","US-NW-PACW","US-NW-PGE","US-NW-PSCO","US-NW-PSEI","US-NW-SCL","US-NW-TPWR","US-NW-WACM","US-NW-WAUW","US-NY-NYIS","US-SE-SOCO","US-SW-AZPS","US-SW-EPE","US-SW-PNM","US-SW-SRP","US-SW-TEPC","US-SW-WALC","US-TEN-TVA","US-TEX-ERCO","UY","UZ","VC","VE","VI","VN","VU","WS","XK","XX","YE","YT","ZA","ZM","ZW"]},{"items":{"type":"string","enum":["AD","AE","AF","AG","AL","AM","AO","AR","AT","AU-LH","AU-NSW","AU-NT","AU-QLD","AU-SA","AU-TAS","AU-TAS-CBI","AU-TAS-FI","AU-TAS-KI","AU-VIC","AU-WA","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BM","BN","BO","BR-CS","BR-N","BR-NE","BR-S","BS","BT","BW","BY","BZ","CA-AB","CA-BC","CA-MB","CA-NB","CA-NL","CA-NS","CA-NT","CA-NU","CA-ON","CA-PE","CA-QC","CA-SK","CA-YT","CD","CF","CG","CH","CI","CL-CHP","CL-SEA","CL-SEM","CL-SEN","CM","CN","CO","CR","CU","CV","CW","CY","CZ","DE","DJ","DK-BHM","DK-DK1","DK-DK2","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ES-CN-FV","ES-CN-GC","ES-CN-HI","ES-CN-IG","ES-CN-LP","ES-CN-LZ","ES-CN-TE","ES-IB-FO","ES-IB-IZ","ES-IB-MA","ES-IB-ME","ET","FI","FJ","FK","FM","FO-MI","FO-SI","FR","FR-COR","GA","GB","GB-NIR","GB-ORK","GB-ZET","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GT","GU","GW","GY","HK","HN","HR","HT","HU","ID","IE","IL","IM","IN-AN","IN-EA","IN-NE","IN-NO","IN-SO","IN-WE","IQ","IR","IS","IT-CNO","IT-CSO","IT-NO","IT-SAR","IT-SIC","IT-SO","JE","JM","JO","JP-CB","JP-CG","JP-HKD","JP-HR","JP-KN","JP-KY","JP-ON","JP-SK","JP-TH","JP-TK","KE","KG","KH","KM","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MD","ME","MG","MK","ML","MM","MN","MQ","MR","MT","MU","MV","MW","MX","MY-EM","MY-WM","MZ","NA","NC","NE","NG","NI","NL","NO-NO1","NO-NO2","NO-NO3","NO-NO4","NO-NO5","NP","NZ","NZ-NZC","NZ-NZST","OM","PA","PE","PF","PG","PH-LU","PH-MI","PH-VI","PK","PL","PM","PR","PS","PT","PT-AC","PT-MA","PW","PY","QA","RE","RO","RS","RU-1","RU-2","RU-AS","RU-EU","RU-FE","RU-KGD","RW","SA","SB","SC","SD","SE-SE1","SE-SE2","SE-SE3","SE-SE4","SG","SI","SJ","SK","SL","SN","SO","SR","SS","ST","SV","SY","SZ","TD","TG","TH","TJ","TL","TM","TN","TO","TR","TT","TW","TZ","UA","UA-CR","UG","US-AK","US-AK-SEAPA","US-CAL-BANC","US-CAL-CISO","US-CAL-IID","US-CAL-LDWP","US-CAL-TIDC","US-CAR-CPLE","US-CAR-CPLW","US-CAR-DUK","US-CAR-SC","US-CAR-SCEG","US-CENT-SPA","US-CENT-SWPP","US-FLA-FMPP","US-FLA-FPC","US-FLA-FPL","US-FLA-GVL","US-FLA-HST","US-FLA-JEA","US-FLA-SEC","US-FLA-TAL","US-FLA-TEC","US-HI","US-MIDA-PJM","US-MIDW-AECI","US-MIDW-LGEE","US-MIDW-MISO","US-NE-ISNE","US-NW-AVA","US-NW-BPAT","US-NW-CHPD","US-NW-DOPD","US-NW-GCPD","US-NW-IPCO","US-NW-NEVP","US-NW-NWMT","US-NW-PACE","US-NW-PACW","US-NW-PGE","US-NW-PSCO","US-NW-PSEI","US-NW-SCL","US-NW-TPWR","US-NW-WACM","US-NW-WAUW","US-NY-NYIS","US-SE-SOCO","US-SW-AZPS","US-SW-EPE","US-SW-PNM","US-SW-SRP","US-SW-TEPC","US-SW-WALC","US-TEN-TVA","US-TEX-ERCO","UY","UZ","VC","VE","VI","VN","VU","WS","XK","XX","YE","YT","ZA","ZM","ZW"]},"type":"array"},{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","XX","YE","YT","ZA","ZM","ZW"]},{"items":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","XX","YE","YT","ZA","ZM","ZW"]},"type":"array"},{"$ref":"#/components/schemas/POIReference"},{"items":{"$ref":"#/components/schemas/POIReference"},"type":"array"}],"title":"Value","description":"Geographic coordinates or identifiers. For 'point': [latitude, longitude] or list of coordinate pairs. For 'bounding_box': [[lat_min, lon_min], [lat_max, lon_max]]. For 'polygon': [[lat1, lon1], [lat2, lon2], ...]. For 'market_zone' or 'country_key': string code or list of codes. For 'poi': POIReference object or list of POIReference objects."},"method":{"anyOf":[{"type":"string","enum":["nearest","bilinear"]},{"type":"null"}],"title":"Method","description":"Interpolation method for point queries. 'nearest': Uses closest grid point (faster). 'bilinear': Interpolates between 4 surrounding grid points. Only applicable when type='point'. Defaults to 'nearest'"}},"type":"object","required":["type","value"],"title":"GeoFilter","description":"Geographic filter for specifying query locations.\n\nSupports various geographic query types including points, regions, and\npredefined areas like market zones."},"POIReference":{"properties":{"coordinates":{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2,"title":"Coordinates","description":"Geographic coordinates as [latitude, longitude]"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Optional unique identifier (e.g., station ID)"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Optional human-readable name for display"}},"type":"object","required":["coordinates"],"title":"POIReference","description":"Reference to a Point of Interest with optional identity.\n\nThe coordinates are required for geo queries. The id and label are optional\nmetadata - id can be used by data sources that need identifiers (e.g., station IDs),\nand label provides a human-readable name for display purposes."},"TimeSlice":{"properties":{"start":{"type":"string","format":"date-time","title":"Start","description":"Start datetime (inclusive)"},"end":{"type":"string","format":"date-time","title":"End","description":"End datetime (inclusive) in ISO 8601 format"}},"type":"object","required":["start","end"],"title":"TimeSlice","description":"Time range for querying forecasts between two datetime values."},"PreferredHours":{"properties":{"type":{"type":"string","title":"Type","default":"preferred_hours"},"selections":{"items":{"$ref":"#/components/schemas/PreferredHoursSelection"},"type":"array","title":"Selections","description":"List of {hour, offset} pairs to select"}},"type":"object","title":"PreferredHours","description":"Select specific forecast runs by UTC hour and per-hour offset.\n\nEach selection picks the Nth most recent available run at a given UTC hour.\nExample: selections=[{hour:6, offset:0}, {hour:6, offset:2}, {hour:18, offset:0}]\nresolves to today's 6am, day-before-yesterday's 6am, and today's 6pm."},"PreferredHoursSelection":{"properties":{"hour":{"type":"integer","maximum":23,"minimum":0,"title":"Hour","description":"UTC hour (0-23)"},"offset":{"type":"integer","minimum":0,"title":"Offset","description":"0 = most recent run at this hour, 1 = previous, etc.","default":0}},"type":"object","required":["hour"],"title":"PreferredHoursSelection","description":"A single preferred-hour run selection.\n\nPicks the Nth most recent run at a given UTC hour."},"CustomerVariable":{"type":"string","enum":["air_temperature_at_height_level_2m","surface_temperature","dew_point_temperature_at_height_level_2m","relative_humidity_at_height_level_2m","air_pressure_at_mean_sea_level","surface_air_pressure","wind_speed_at_height_level_10m","wind_direction_at_height_level_10m","wind_speed_at_height_level_100m","wind_direction_at_height_level_100m","wind_speed_at_height_level_20m","wind_speed_at_height_level_40m","wind_speed_at_height_level_60m","wind_speed_at_height_level_80m","wind_speed_at_height_level_120m","wind_speed_at_height_level_140m","wind_speed_at_height_level_160m","wind_speed_at_height_level_180m","wind_speed_at_height_level_200m","wind_direction_at_height_level_200m","air_density_at_height_level_2m","geopotential_at_pressure_level_50000Pa","eastward_wind_at_height_level_10m","northward_wind_at_height_level_10m","eastward_wind_at_height_level_100m","northward_wind_at_height_level_100m","wind_speed_of_gust_at_height_level_10m_max","surface_direct_downwelling_shortwave_flux_sum_1h","surface_downwelling_longwave_flux_sum_1h","surface_downwelling_shortwave_flux_sum_1h","surface_downwelling_longwave_flux_sum_6h","surface_downwelling_shortwave_flux_sum_6h","surface_net_downward_longwave_flux_sum_1h","surface_net_downward_shortwave_flux_sum_1h","surface_net_downward_longwave_flux_sum_6h","surface_net_downward_shortwave_flux_sum_6h","surface_direct_along_beam_shortwave_flux_sum_6h","cloud_area_fraction_at_entire_atmosphere","cloud_area_fraction_at_entire_atmosphere_high_type","cloud_area_fraction_at_entire_atmosphere_medium_type","cloud_area_fraction_at_entire_atmosphere_low_type","precipitation_amount_sum_1h","precipitation_amount_sum_3h","precipitation_amount_sum_6h","precipitation_amount_sum_12h","precipitation_amount_sum_24h","atmosphere_convective_available_potential_energy","predominant_precipitation_type_at_surface","sea_surface_temperature"],"title":"CustomerVariable","description":"Weather variable name with units:\n  • air_temperature_at_height_level_2m: K\n  • surface_temperature: K\n  • dew_point_temperature_at_height_level_2m: K\n  • relative_humidity_at_height_level_2m: %\n  • air_pressure_at_mean_sea_level: Pa\n  • surface_air_pressure: Pa\n  • wind_speed_at_height_level_10m: m/s\n  • wind_direction_at_height_level_10m: degrees\n  • wind_speed_at_height_level_100m: m/s\n  • wind_direction_at_height_level_100m: degrees\n  • wind_speed_at_height_level_20m: m/s\n  • wind_speed_at_height_level_40m: m/s\n  • wind_speed_at_height_level_60m: m/s\n  • wind_speed_at_height_level_80m: m/s\n  • wind_speed_at_height_level_120m: m/s\n  • wind_speed_at_height_level_140m: m/s\n  • wind_speed_at_height_level_160m: m/s\n  • wind_speed_at_height_level_180m: m/s\n  • wind_speed_at_height_level_200m: m/s\n  • wind_direction_at_height_level_200m: degrees\n  • air_density_at_height_level_2m: kg/m³\n  • geopotential_at_pressure_level_50000Pa: m²/s²\n  • eastward_wind_at_height_level_10m: m/s\n  • northward_wind_at_height_level_10m: m/s\n  • eastward_wind_at_height_level_100m: m/s\n  • northward_wind_at_height_level_100m: m/s\n  • wind_speed_of_gust_at_height_level_10m_max: m/s\n  • surface_direct_downwelling_shortwave_flux_sum_1h: J/m²\n  • surface_downwelling_longwave_flux_sum_1h: J/m²\n  • surface_downwelling_shortwave_flux_sum_1h: J/m²\n  • surface_downwelling_longwave_flux_sum_6h: J/m²\n  • surface_downwelling_shortwave_flux_sum_6h: J/m²\n  • surface_net_downward_longwave_flux_sum_1h: J/m²\n  • surface_net_downward_shortwave_flux_sum_1h: J/m²\n  • surface_net_downward_longwave_flux_sum_6h: J/m²\n  • surface_net_downward_shortwave_flux_sum_6h: J/m²\n  • surface_direct_along_beam_shortwave_flux_sum_6h: J/m²\n  • cloud_area_fraction_at_entire_atmosphere: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_high_type: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_medium_type: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_low_type: fraction (0-1)\n  • precipitation_amount_sum_1h: mm\n  • precipitation_amount_sum_3h: mm\n  • precipitation_amount_sum_6h: mm\n  • precipitation_amount_sum_12h: mm\n  • precipitation_amount_sum_24h: mm\n  • atmosphere_convective_available_potential_energy: J/kg\n  • predominant_precipitation_type_at_surface: categorical\n  • sea_surface_temperature: K"},"PredictionTimedeltaSlice":{"properties":{"start":{"type":"integer","minimum":0,"title":"Start","description":"Start lead time in minutes from init_time (inclusive)","default":0},"end":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"End","description":"End lead time in minutes from init_time (inclusive). If None, uses model's maximum available lead time"}},"type":"object","title":"PredictionTimedeltaSlice","description":"Forecast lead time range in minutes from the initialization time."},"GroupByKey":{"properties":{"field":{"type":"string","enum":["model","init_time","time","prediction_timedelta","market_zone","country_key","point","latitude","longitude","month","hour"],"title":"Field"},"transformation":{"anyOf":[{"type":"string","const":"to_start_of"},{"type":"null"}],"title":"Transformation"},"parameters_list":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Parameters List"}},"type":"object","required":["field"],"title":"GroupByKey","description":"Structured representation of a group-by key.\n\n- field: one of supported base fields\n- transformation: optional transformation name (currently only 'to_start_of')\n- parameters_list: optional list of parameters for the transformation"},"OrderByItem_Union_Coordinates__CustomerVariable__":{"properties":{"field":{"anyOf":[{"$ref":"#/components/schemas/Coordinates"},{"$ref":"#/components/schemas/CustomerVariable"}],"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[Union[Coordinates, CustomerVariable]]"},"Coordinates":{"type":"string","enum":["model","init_time","time","prediction_timedelta","latitude","longitude","point","market_zone","country_key"],"title":"Coordinates"},"SortDirection":{"type":"string","enum":["asc","desc"],"title":"SortDirection","description":"Sort direction for ORDER BY clauses."},"Aggregation":{"properties":{"aggregation":{"type":"string","enum":["avg","std","min","max","sum","count","median","quantile","argmin","argmax"],"title":"Aggregation","description":"Aggregation function name."},"parameters":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Parameters","description":"Parameters for parameterized aggregations.Example: 'quantile': [0.5] for median, [0.95] for 95th percentile, etc."},"variables":{"anyOf":[{"items":{"$ref":"#/components/schemas/CustomerVariable"},"type":"array"},{"type":"null"}],"title":"Variables","description":"Specific variables to aggregate. If None, applies to all variables in the query"}},"type":"object","required":["aggregation"],"title":"Aggregation","description":"Aggregation function to apply when grouping forecast data.\n\nSupported aggregations:\n- Basic: avg, std, min, max, sum, count, median\n- Parameterized: quantile_(p), argmin_(col), argmax_(col)\n\nFor argmin/argmax, the parameter is the column to return, and the variable\nis the column to find the min/max of. Example:\n    argmin_(time)__temperature -> returns time when temperature is minimum\n\nCan be applied to specific variables or all variables in the query."},"Weighting":{"properties":{"type":{"type":"string","enum":["wind_capacity","wind_capacity_combined","solar_capacity","population"],"title":"Type","description":"Weighting type for geographic aggregation. 'wind_capacity': Weight by installed wind power capacity. 'solar_capacity': Weight by installed solar power capacity. 'population': Weight by population density"},"unit":{"type":"string","enum":["weather","mw"],"title":"Unit","description":"Output unit. 'weather': return capacity-weighted raw weather values E[wu]. 'mw': apply power curves in ClickHouse and return predicted MW.","default":"weather"}},"type":"object","required":["type"],"title":"Weighting","description":"Weighting scheme for aggregating forecast data over geographic areas.\n\nApplies weighted averages based on capacity or population distribution within\nthe queried area."},"Pagination":{"properties":{"limit":{"type":"integer","title":"Limit","default":100},"offset":{"type":"integer","title":"Offset","default":0}},"type":"object","title":"Pagination"},"ValueFilter":{"properties":{"variable":{"type":"string","title":"Variable"},"operator":{"type":"string","title":"Operator"},"value":{"type":"number","title":"Value"}},"type":"object","required":["variable","operator","value"],"title":"ValueFilter"},"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"}}}}
```

## Query forecast data index

> Endpoint to obtain the index for weather forecasts.\
> \
> \*\*Authentication\*\*: Requires API key.\
> \
> For detailed query examples and best practices, visit \[docs.jua.ai]\(<https://docs.jua.ai>).

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"forecast","description":"Query and retrieve weather forecast data from Jua's platform."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/forecast/index":{"post":{"tags":["forecast"],"summary":"Query forecast data index","description":"Endpoint to obtain the index for weather forecasts.\n\n**Authentication**: Requires API key.\n\nFor detailed query examples and best practices, visit [docs.jua.ai](https://docs.jua.ai).","operationId":"post_forecast_index_v1_forecast_index_post","parameters":[{"name":"request_credit_limit","in":"query","required":false,"schema":{"type":"number","minimum":0,"description":"Maximum credits allowed for this request. Query will fail if estimated cost exceeds this limit","default":50,"title":"Request Credit Limit"},"description":"Maximum credits allowed for this request. Query will fail if estimated cost exceeds this limit"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForecastIndexQuery"}}}},"responses":{"200":{"description":"Successfully retrieved forecast data","content":{"application/json":{"schema":{}},"application/vnd.apache.arrow.stream":{"description":"Apache Arrow IPC stream format"}}},"400":{"description":"Invalid query parameters or response size exceeded"},"401":{"description":"Authentication required"},"402":{"description":"Insufficient credits"},"403":{"description":"Insufficient permissions or model not in subscription"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ForecastIndexQuery":{"properties":{"model":{"$ref":"#/components/schemas/Model","description":"Model identifiers to query (e.g. 'ept2')"},"init_time":{"anyOf":[{"type":"integer","minimum":0,"description":"Offset from latest forecast (0 = latest, 1 = second latest, etc.)"},{"type":"string","format":"date-time"},{"type":"string","pattern":"^latest(-\\d+)?$","description":"Use 'latest' or 'latest-N' for relative init times"},{"items":{"anyOf":[{"type":"integer","minimum":0,"description":"Offset from latest forecast (0 = latest, 1 = second latest, etc.)"},{"type":"string","format":"date-time"},{"type":"string","pattern":"^latest(-\\d+)?$","description":"Use 'latest' or 'latest-N' for relative init times"}]},"type":"array"},{"$ref":"#/components/schemas/TimeSlice"},{"$ref":"#/components/schemas/PreferredHours"}],"title":"Init Time","description":"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."},"latitude":{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2,"title":"Latitude","description":"The range of latitudes to return."},"longitude":{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2,"title":"Longitude","description":"Geographic filter specifying the query location(s) or region(s)"},"variables":{"items":{"$ref":"#/components/schemas/CustomerVariable"},"type":"array","title":"Variables","description":"List of weather variables to query (e.g., 'air_temperature_at_height_level_2m', 'wind_speed_at_height_level_100m'). If empty, returns all variables available for the selected models"},"prediction_timedelta":{"anyOf":[{"type":"integer"},{"$ref":"#/components/schemas/PredictionTimedeltaSlice"},{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Prediction Timedelta","description":"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. "},"latest_min_prediction_timedelta":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Latest Min Prediction Timedelta","description":"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_unit":{"type":"string","enum":["h","m","d","hour","hourly","minute","minutes","day","days"],"title":"Timedelta Unit","description":"Time scale to use for the query. Can be 'h' for hours, 'm' for minutes, 'd' for days","default":"h"},"as_of":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"As Of","description":"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."}},"type":"object","required":["model","init_time","latitude","longitude"],"title":"ForecastIndexQuery","description":"Main query object for retrieving the index for forecast data."},"Model":{"type":"string","enum":["ept2","ept2_early","ept2_e","ept2_rr","ept2_hrrr","ept1_5","ept1_5_early","aifs","aurora","icon_global","icon_eu","ecmwf_ifs_single","ecmwf_ens","ecmwf_ec46","ept2_reasoning","ecmwf_aifs025_ensemble","meteofrance_arome_france_hd","gfs_global_single","noaa_gfs_single","gfs_global_ensemble","icon_d2","gfs_graphcast025","knmi_harmonie_arome_europe","knmi_harmonie_arome_netherlands","ukmo_global_deterministic_10km","ukmo_uk_deterministic_2km"],"title":"Model"},"TimeSlice":{"properties":{"start":{"type":"string","format":"date-time","title":"Start","description":"Start datetime (inclusive)"},"end":{"type":"string","format":"date-time","title":"End","description":"End datetime (inclusive) in ISO 8601 format"}},"type":"object","required":["start","end"],"title":"TimeSlice","description":"Time range for querying forecasts between two datetime values."},"PreferredHours":{"properties":{"type":{"type":"string","title":"Type","default":"preferred_hours"},"selections":{"items":{"$ref":"#/components/schemas/PreferredHoursSelection"},"type":"array","title":"Selections","description":"List of {hour, offset} pairs to select"}},"type":"object","title":"PreferredHours","description":"Select specific forecast runs by UTC hour and per-hour offset.\n\nEach selection picks the Nth most recent available run at a given UTC hour.\nExample: selections=[{hour:6, offset:0}, {hour:6, offset:2}, {hour:18, offset:0}]\nresolves to today's 6am, day-before-yesterday's 6am, and today's 6pm."},"PreferredHoursSelection":{"properties":{"hour":{"type":"integer","maximum":23,"minimum":0,"title":"Hour","description":"UTC hour (0-23)"},"offset":{"type":"integer","minimum":0,"title":"Offset","description":"0 = most recent run at this hour, 1 = previous, etc.","default":0}},"type":"object","required":["hour"],"title":"PreferredHoursSelection","description":"A single preferred-hour run selection.\n\nPicks the Nth most recent run at a given UTC hour."},"CustomerVariable":{"type":"string","enum":["air_temperature_at_height_level_2m","surface_temperature","dew_point_temperature_at_height_level_2m","relative_humidity_at_height_level_2m","air_pressure_at_mean_sea_level","surface_air_pressure","wind_speed_at_height_level_10m","wind_direction_at_height_level_10m","wind_speed_at_height_level_100m","wind_direction_at_height_level_100m","wind_speed_at_height_level_20m","wind_speed_at_height_level_40m","wind_speed_at_height_level_60m","wind_speed_at_height_level_80m","wind_speed_at_height_level_120m","wind_speed_at_height_level_140m","wind_speed_at_height_level_160m","wind_speed_at_height_level_180m","wind_speed_at_height_level_200m","wind_direction_at_height_level_200m","air_density_at_height_level_2m","geopotential_at_pressure_level_50000Pa","eastward_wind_at_height_level_10m","northward_wind_at_height_level_10m","eastward_wind_at_height_level_100m","northward_wind_at_height_level_100m","wind_speed_of_gust_at_height_level_10m_max","surface_direct_downwelling_shortwave_flux_sum_1h","surface_downwelling_longwave_flux_sum_1h","surface_downwelling_shortwave_flux_sum_1h","surface_downwelling_longwave_flux_sum_6h","surface_downwelling_shortwave_flux_sum_6h","surface_net_downward_longwave_flux_sum_1h","surface_net_downward_shortwave_flux_sum_1h","surface_net_downward_longwave_flux_sum_6h","surface_net_downward_shortwave_flux_sum_6h","surface_direct_along_beam_shortwave_flux_sum_6h","cloud_area_fraction_at_entire_atmosphere","cloud_area_fraction_at_entire_atmosphere_high_type","cloud_area_fraction_at_entire_atmosphere_medium_type","cloud_area_fraction_at_entire_atmosphere_low_type","precipitation_amount_sum_1h","precipitation_amount_sum_3h","precipitation_amount_sum_6h","precipitation_amount_sum_12h","precipitation_amount_sum_24h","atmosphere_convective_available_potential_energy","predominant_precipitation_type_at_surface","sea_surface_temperature"],"title":"CustomerVariable","description":"Weather variable name with units:\n  • air_temperature_at_height_level_2m: K\n  • surface_temperature: K\n  • dew_point_temperature_at_height_level_2m: K\n  • relative_humidity_at_height_level_2m: %\n  • air_pressure_at_mean_sea_level: Pa\n  • surface_air_pressure: Pa\n  • wind_speed_at_height_level_10m: m/s\n  • wind_direction_at_height_level_10m: degrees\n  • wind_speed_at_height_level_100m: m/s\n  • wind_direction_at_height_level_100m: degrees\n  • wind_speed_at_height_level_20m: m/s\n  • wind_speed_at_height_level_40m: m/s\n  • wind_speed_at_height_level_60m: m/s\n  • wind_speed_at_height_level_80m: m/s\n  • wind_speed_at_height_level_120m: m/s\n  • wind_speed_at_height_level_140m: m/s\n  • wind_speed_at_height_level_160m: m/s\n  • wind_speed_at_height_level_180m: m/s\n  • wind_speed_at_height_level_200m: m/s\n  • wind_direction_at_height_level_200m: degrees\n  • air_density_at_height_level_2m: kg/m³\n  • geopotential_at_pressure_level_50000Pa: m²/s²\n  • eastward_wind_at_height_level_10m: m/s\n  • northward_wind_at_height_level_10m: m/s\n  • eastward_wind_at_height_level_100m: m/s\n  • northward_wind_at_height_level_100m: m/s\n  • wind_speed_of_gust_at_height_level_10m_max: m/s\n  • surface_direct_downwelling_shortwave_flux_sum_1h: J/m²\n  • surface_downwelling_longwave_flux_sum_1h: J/m²\n  • surface_downwelling_shortwave_flux_sum_1h: J/m²\n  • surface_downwelling_longwave_flux_sum_6h: J/m²\n  • surface_downwelling_shortwave_flux_sum_6h: J/m²\n  • surface_net_downward_longwave_flux_sum_1h: J/m²\n  • surface_net_downward_shortwave_flux_sum_1h: J/m²\n  • surface_net_downward_longwave_flux_sum_6h: J/m²\n  • surface_net_downward_shortwave_flux_sum_6h: J/m²\n  • surface_direct_along_beam_shortwave_flux_sum_6h: J/m²\n  • cloud_area_fraction_at_entire_atmosphere: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_high_type: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_medium_type: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_low_type: fraction (0-1)\n  • precipitation_amount_sum_1h: mm\n  • precipitation_amount_sum_3h: mm\n  • precipitation_amount_sum_6h: mm\n  • precipitation_amount_sum_12h: mm\n  • precipitation_amount_sum_24h: mm\n  • atmosphere_convective_available_potential_energy: J/kg\n  • predominant_precipitation_type_at_surface: categorical\n  • sea_surface_temperature: K"},"PredictionTimedeltaSlice":{"properties":{"start":{"type":"integer","minimum":0,"title":"Start","description":"Start lead time in minutes from init_time (inclusive)","default":0},"end":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"End","description":"End lead time in minutes from init_time (inclusive). If None, uses model's maximum available lead time"}},"type":"object","title":"PredictionTimedeltaSlice","description":"Forecast lead time range in minutes from the initialization 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"}}}}
```

## Query forecast data (simple)

> 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]\(<https://docs.jua.ai/>) for examples.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"forecast","description":"Query and retrieve weather forecast data from Jua's platform."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/forecast/":{"get":{"tags":["forecast"],"summary":"Query forecast data (simple)","description":"Simplified GET endpoint for querying forecast data at a single point location.\n\nThis endpoint provides a simpler interface compared to POST `/data` for basic point queries.\nUse this for quick lookups at specific coordinates.\n\n**Limitations**:\n- Point queries only (no areas or market zones)\n- JSON response format only (no Arrow or streaming)\n- No grouping or aggregation support\n\nFor advanced queries with aggregation, multiple locations, or Arrow format, use POST `/data`.\n\n**Authentication**: Requires API key.\n\nSee [docs.jua.ai](https://docs.jua.ai/) for examples.","operationId":"get_data_simple_v1_forecast__get","parameters":[{"name":"models","in":"query","required":true,"schema":{"type":"array","items":{"$ref":"#/components/schemas/Model"},"description":"List of forecast models to query","title":"Models"},"description":"List of forecast models to query"},{"name":"init_time","in":"query","required":true,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"const":"latest","type":"string"}],"description":"Forecast initialization time (ISO 8601 format) or 'latest' for most recent forecast","title":"Init Time"},"description":"Forecast initialization time (ISO 8601 format) or 'latest' for most recent forecast"},{"name":"latitude","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"description":"Latitude of query point in degrees (-90 to 90)","title":"Latitude"},"description":"Latitude of query point in degrees (-90 to 90)"},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","maximum":180,"minimum":-180,"description":"Longitude of query point in degrees (-180 to 180)","title":"Longitude"},"description":"Longitude of query point in degrees (-180 to 180)"},{"name":"method","in":"query","required":false,"schema":{"enum":["nearest","bilinear"],"type":"string","description":"Interpolate or return the nearest value","default":"nearest","title":"Method"},"description":"Interpolate or return the nearest value"},{"name":"variables","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/CustomerVariable"}},{"type":"null"}],"description":"Weather variables to query. If not specified, returns all available variables","title":"Variables"},"description":"Weather variables to query. If not specified, returns all available variables"},{"name":"time_zone","in":"query","required":false,"schema":{"type":"string","description":"IANA time zone name for time formatting","default":"GMT","title":"Time Zone"},"description":"IANA time zone name for time formatting"},{"name":"include_time","in":"query","required":false,"schema":{"type":"boolean","description":"Include forecast valid time column","default":true,"title":"Include Time"},"description":"Include forecast valid time column"},{"name":"min_prediction_timedelta","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Minimum lead time in minutes","default":0,"title":"Min Prediction Timedelta"},"description":"Minimum lead time in minutes"},{"name":"max_prediction_timedelta","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Maximum lead time in minutes","title":"Max Prediction Timedelta"},"description":"Maximum lead time in minutes"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of results to skip for pagination","default":0,"title":"Offset"},"description":"Number of results to skip for pagination"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Maximum number of results to return","default":10000,"title":"Limit"},"description":"Maximum number of results to return"},{"name":"request_credit_limit","in":"query","required":false,"schema":{"type":"number","minimum":0,"description":"Maximum credits allowed for this request","default":5,"title":"Request Credit Limit"},"description":"Maximum credits allowed for this request"},{"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."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Synthetic invocation time for backtesting (ISO 8601 UTC). Only forecast runs disseminated at or before this time are visible.","title":"As Of"},"description":"Synthetic invocation time for backtesting (ISO 8601 UTC). Only forecast runs disseminated at or before this time are visible."}],"responses":{"200":{"description":"Successfully retrieved forecast data","content":{"application/json":{"schema":{}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Authentication required"},"402":{"description":"Insufficient credits"},"403":{"description":"Insufficient permissions"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Model":{"type":"string","enum":["ept2","ept2_early","ept2_e","ept2_rr","ept2_hrrr","ept1_5","ept1_5_early","aifs","aurora","icon_global","icon_eu","ecmwf_ifs_single","ecmwf_ens","ecmwf_ec46","ept2_reasoning","ecmwf_aifs025_ensemble","meteofrance_arome_france_hd","gfs_global_single","noaa_gfs_single","gfs_global_ensemble","icon_d2","gfs_graphcast025","knmi_harmonie_arome_europe","knmi_harmonie_arome_netherlands","ukmo_global_deterministic_10km","ukmo_uk_deterministic_2km"],"title":"Model"},"CustomerVariable":{"type":"string","enum":["air_temperature_at_height_level_2m","surface_temperature","dew_point_temperature_at_height_level_2m","relative_humidity_at_height_level_2m","air_pressure_at_mean_sea_level","surface_air_pressure","wind_speed_at_height_level_10m","wind_direction_at_height_level_10m","wind_speed_at_height_level_100m","wind_direction_at_height_level_100m","wind_speed_at_height_level_20m","wind_speed_at_height_level_40m","wind_speed_at_height_level_60m","wind_speed_at_height_level_80m","wind_speed_at_height_level_120m","wind_speed_at_height_level_140m","wind_speed_at_height_level_160m","wind_speed_at_height_level_180m","wind_speed_at_height_level_200m","wind_direction_at_height_level_200m","air_density_at_height_level_2m","geopotential_at_pressure_level_50000Pa","eastward_wind_at_height_level_10m","northward_wind_at_height_level_10m","eastward_wind_at_height_level_100m","northward_wind_at_height_level_100m","wind_speed_of_gust_at_height_level_10m_max","surface_direct_downwelling_shortwave_flux_sum_1h","surface_downwelling_longwave_flux_sum_1h","surface_downwelling_shortwave_flux_sum_1h","surface_downwelling_longwave_flux_sum_6h","surface_downwelling_shortwave_flux_sum_6h","surface_net_downward_longwave_flux_sum_1h","surface_net_downward_shortwave_flux_sum_1h","surface_net_downward_longwave_flux_sum_6h","surface_net_downward_shortwave_flux_sum_6h","surface_direct_along_beam_shortwave_flux_sum_6h","cloud_area_fraction_at_entire_atmosphere","cloud_area_fraction_at_entire_atmosphere_high_type","cloud_area_fraction_at_entire_atmosphere_medium_type","cloud_area_fraction_at_entire_atmosphere_low_type","precipitation_amount_sum_1h","precipitation_amount_sum_3h","precipitation_amount_sum_6h","precipitation_amount_sum_12h","precipitation_amount_sum_24h","atmosphere_convective_available_potential_energy","predominant_precipitation_type_at_surface","sea_surface_temperature"],"title":"CustomerVariable","description":"Weather variable name with units:\n  • air_temperature_at_height_level_2m: K\n  • surface_temperature: K\n  • dew_point_temperature_at_height_level_2m: K\n  • relative_humidity_at_height_level_2m: %\n  • air_pressure_at_mean_sea_level: Pa\n  • surface_air_pressure: Pa\n  • wind_speed_at_height_level_10m: m/s\n  • wind_direction_at_height_level_10m: degrees\n  • wind_speed_at_height_level_100m: m/s\n  • wind_direction_at_height_level_100m: degrees\n  • wind_speed_at_height_level_20m: m/s\n  • wind_speed_at_height_level_40m: m/s\n  • wind_speed_at_height_level_60m: m/s\n  • wind_speed_at_height_level_80m: m/s\n  • wind_speed_at_height_level_120m: m/s\n  • wind_speed_at_height_level_140m: m/s\n  • wind_speed_at_height_level_160m: m/s\n  • wind_speed_at_height_level_180m: m/s\n  • wind_speed_at_height_level_200m: m/s\n  • wind_direction_at_height_level_200m: degrees\n  • air_density_at_height_level_2m: kg/m³\n  • geopotential_at_pressure_level_50000Pa: m²/s²\n  • eastward_wind_at_height_level_10m: m/s\n  • northward_wind_at_height_level_10m: m/s\n  • eastward_wind_at_height_level_100m: m/s\n  • northward_wind_at_height_level_100m: m/s\n  • wind_speed_of_gust_at_height_level_10m_max: m/s\n  • surface_direct_downwelling_shortwave_flux_sum_1h: J/m²\n  • surface_downwelling_longwave_flux_sum_1h: J/m²\n  • surface_downwelling_shortwave_flux_sum_1h: J/m²\n  • surface_downwelling_longwave_flux_sum_6h: J/m²\n  • surface_downwelling_shortwave_flux_sum_6h: J/m²\n  • surface_net_downward_longwave_flux_sum_1h: J/m²\n  • surface_net_downward_shortwave_flux_sum_1h: J/m²\n  • surface_net_downward_longwave_flux_sum_6h: J/m²\n  • surface_net_downward_shortwave_flux_sum_6h: J/m²\n  • surface_direct_along_beam_shortwave_flux_sum_6h: J/m²\n  • cloud_area_fraction_at_entire_atmosphere: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_high_type: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_medium_type: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_low_type: fraction (0-1)\n  • precipitation_amount_sum_1h: mm\n  • precipitation_amount_sum_3h: mm\n  • precipitation_amount_sum_6h: mm\n  • precipitation_amount_sum_12h: mm\n  • precipitation_amount_sum_24h: mm\n  • atmosphere_convective_available_potential_energy: J/kg\n  • predominant_precipitation_type_at_surface: categorical\n  • sea_surface_temperature: K"},"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"}}}}
```

## Query market-aggregated forecast data

> 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]\(<https://docs.jua.ai/>) for examples.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"forecast","description":"Query and retrieve weather forecast data from Jua's platform."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/forecast/market-aggregate":{"get":{"tags":["forecast"],"summary":"Query market-aggregated forecast data","description":"Simplified GET endpoint for querying weighted-average forecasts over market zones or countries.\n\nAutomatically applies weighted aggregation based on capacity (wind/solar) or population distribution.\nUseful for energy market analysis and regional forecasting.\n\n**Common Use Cases**:\n- Wind power generation forecasts for market zones (weighted by wind capacity)\n- Solar power generation forecasts (weighted by solar capacity)\n- Population-weighted temperature averages for countries\n\n**Weighting Options**:\n- `wind_capacity`: Weight by installed wind power capacity\n- `solar_capacity`: Weight by installed solar power capacity  \n- `population`: Weight by population density\n\n**Limitations**:\n- JSON response format only (no Arrow or streaming)\n- Must specify either `market_zones` OR `country_keys` (not both)\n\nFor advanced aggregation queries, use POST `/data` with `group_by` and `weighting` parameters.\n\n**Authentication**: Requires API key.\n\nSee [docs.jua.ai](https://docs.jua.ai/) for examples.","operationId":"get_market_aggregate_simple_v1_forecast_market_aggregate_get","parameters":[{"name":"models","in":"query","required":true,"schema":{"type":"array","items":{"$ref":"#/components/schemas/Model"},"description":"List of forecast models to query","title":"Models"},"description":"List of forecast models to query"},{"name":"init_time","in":"query","required":true,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"const":"latest","type":"string"}],"description":"Forecast initialization time (ISO 8601 format) or 'latest' for most recent forecast","title":"Init Time"},"description":"Forecast initialization time (ISO 8601 format) or 'latest' for most recent forecast"},{"name":"weighting","in":"query","required":true,"schema":{"enum":["wind_capacity","solar_capacity","population"],"type":"string","description":"Weighting scheme for aggregation","title":"Weighting"},"description":"Weighting scheme for aggregation"},{"name":"market_zones","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Energy market zone codes (e.g., ['DE', 'FR']). Mutually exclusive with country_keys","title":"Market Zones"},"description":"Energy market zone codes (e.g., ['DE', 'FR']). Mutually exclusive with country_keys"},{"name":"country_keys","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"ISO country codes (e.g., ['DE', 'US']). Mutually exclusive with market_zones","title":"Country Keys"},"description":"ISO country codes (e.g., ['DE', 'US']). Mutually exclusive with market_zones"},{"name":"variables","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/CustomerVariable"}},{"type":"null"}],"description":"Weather variables to query. If not specified, returns all available variables","title":"Variables"},"description":"Weather variables to query. If not specified, returns all available variables"},{"name":"time_zone","in":"query","required":false,"schema":{"type":"string","description":"IANA time zone name for time formatting","default":"GMT","title":"Time Zone"},"description":"IANA time zone name for time formatting"},{"name":"include_time","in":"query","required":false,"schema":{"type":"boolean","description":"Include forecast valid time column","default":true,"title":"Include Time"},"description":"Include forecast valid time column"},{"name":"min_prediction_timedelta","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Minimum lead time in minutes","default":0,"title":"Min Prediction Timedelta"},"description":"Minimum lead time in minutes"},{"name":"max_prediction_timedelta","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Maximum lead time in minutes","title":"Max Prediction Timedelta"},"description":"Maximum lead time in minutes"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of results to skip for pagination","default":0,"title":"Offset"},"description":"Number of results to skip for pagination"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100000,"minimum":1,"description":"Maximum number of results to return","default":10000,"title":"Limit"},"description":"Maximum number of results to return"},{"name":"unit","in":"query","required":false,"schema":{"enum":["weather","mw"],"type":"string","description":"Output unit. 'weather': capacity-weighted raw weather. 'mw': apply power curves and return predicted MW.","default":"weather","title":"Unit"},"description":"Output unit. 'weather': capacity-weighted raw weather. 'mw': apply power curves and return predicted MW."},{"name":"request_credit_limit","in":"query","required":false,"schema":{"type":"number","minimum":0,"description":"Maximum credits allowed for this request","default":50,"title":"Request Credit Limit"},"description":"Maximum credits allowed for this request"},{"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."},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Synthetic invocation time for backtesting (ISO 8601 UTC). Only forecast runs disseminated at or before this time are visible.","title":"As Of"},"description":"Synthetic invocation time for backtesting (ISO 8601 UTC). Only forecast runs disseminated at or before this time are visible."}],"responses":{"200":{"description":"Successfully retrieved aggregated forecast data","content":{"application/json":{"schema":{}}}},"400":{"description":"Invalid parameters (must specify market_zones OR country_keys)"},"401":{"description":"Authentication required"},"402":{"description":"Insufficient credits"},"403":{"description":"Insufficient permissions"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Model":{"type":"string","enum":["ept2","ept2_early","ept2_e","ept2_rr","ept2_hrrr","ept1_5","ept1_5_early","aifs","aurora","icon_global","icon_eu","ecmwf_ifs_single","ecmwf_ens","ecmwf_ec46","ept2_reasoning","ecmwf_aifs025_ensemble","meteofrance_arome_france_hd","gfs_global_single","noaa_gfs_single","gfs_global_ensemble","icon_d2","gfs_graphcast025","knmi_harmonie_arome_europe","knmi_harmonie_arome_netherlands","ukmo_global_deterministic_10km","ukmo_uk_deterministic_2km"],"title":"Model"},"CustomerVariable":{"type":"string","enum":["air_temperature_at_height_level_2m","surface_temperature","dew_point_temperature_at_height_level_2m","relative_humidity_at_height_level_2m","air_pressure_at_mean_sea_level","surface_air_pressure","wind_speed_at_height_level_10m","wind_direction_at_height_level_10m","wind_speed_at_height_level_100m","wind_direction_at_height_level_100m","wind_speed_at_height_level_20m","wind_speed_at_height_level_40m","wind_speed_at_height_level_60m","wind_speed_at_height_level_80m","wind_speed_at_height_level_120m","wind_speed_at_height_level_140m","wind_speed_at_height_level_160m","wind_speed_at_height_level_180m","wind_speed_at_height_level_200m","wind_direction_at_height_level_200m","air_density_at_height_level_2m","geopotential_at_pressure_level_50000Pa","eastward_wind_at_height_level_10m","northward_wind_at_height_level_10m","eastward_wind_at_height_level_100m","northward_wind_at_height_level_100m","wind_speed_of_gust_at_height_level_10m_max","surface_direct_downwelling_shortwave_flux_sum_1h","surface_downwelling_longwave_flux_sum_1h","surface_downwelling_shortwave_flux_sum_1h","surface_downwelling_longwave_flux_sum_6h","surface_downwelling_shortwave_flux_sum_6h","surface_net_downward_longwave_flux_sum_1h","surface_net_downward_shortwave_flux_sum_1h","surface_net_downward_longwave_flux_sum_6h","surface_net_downward_shortwave_flux_sum_6h","surface_direct_along_beam_shortwave_flux_sum_6h","cloud_area_fraction_at_entire_atmosphere","cloud_area_fraction_at_entire_atmosphere_high_type","cloud_area_fraction_at_entire_atmosphere_medium_type","cloud_area_fraction_at_entire_atmosphere_low_type","precipitation_amount_sum_1h","precipitation_amount_sum_3h","precipitation_amount_sum_6h","precipitation_amount_sum_12h","precipitation_amount_sum_24h","atmosphere_convective_available_potential_energy","predominant_precipitation_type_at_surface","sea_surface_temperature"],"title":"CustomerVariable","description":"Weather variable name with units:\n  • air_temperature_at_height_level_2m: K\n  • surface_temperature: K\n  • dew_point_temperature_at_height_level_2m: K\n  • relative_humidity_at_height_level_2m: %\n  • air_pressure_at_mean_sea_level: Pa\n  • surface_air_pressure: Pa\n  • wind_speed_at_height_level_10m: m/s\n  • wind_direction_at_height_level_10m: degrees\n  • wind_speed_at_height_level_100m: m/s\n  • wind_direction_at_height_level_100m: degrees\n  • wind_speed_at_height_level_20m: m/s\n  • wind_speed_at_height_level_40m: m/s\n  • wind_speed_at_height_level_60m: m/s\n  • wind_speed_at_height_level_80m: m/s\n  • wind_speed_at_height_level_120m: m/s\n  • wind_speed_at_height_level_140m: m/s\n  • wind_speed_at_height_level_160m: m/s\n  • wind_speed_at_height_level_180m: m/s\n  • wind_speed_at_height_level_200m: m/s\n  • wind_direction_at_height_level_200m: degrees\n  • air_density_at_height_level_2m: kg/m³\n  • geopotential_at_pressure_level_50000Pa: m²/s²\n  • eastward_wind_at_height_level_10m: m/s\n  • northward_wind_at_height_level_10m: m/s\n  • eastward_wind_at_height_level_100m: m/s\n  • northward_wind_at_height_level_100m: m/s\n  • wind_speed_of_gust_at_height_level_10m_max: m/s\n  • surface_direct_downwelling_shortwave_flux_sum_1h: J/m²\n  • surface_downwelling_longwave_flux_sum_1h: J/m²\n  • surface_downwelling_shortwave_flux_sum_1h: J/m²\n  • surface_downwelling_longwave_flux_sum_6h: J/m²\n  • surface_downwelling_shortwave_flux_sum_6h: J/m²\n  • surface_net_downward_longwave_flux_sum_1h: J/m²\n  • surface_net_downward_shortwave_flux_sum_1h: J/m²\n  • surface_net_downward_longwave_flux_sum_6h: J/m²\n  • surface_net_downward_shortwave_flux_sum_6h: J/m²\n  • surface_direct_along_beam_shortwave_flux_sum_6h: J/m²\n  • cloud_area_fraction_at_entire_atmosphere: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_high_type: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_medium_type: fraction (0-1)\n  • cloud_area_fraction_at_entire_atmosphere_low_type: fraction (0-1)\n  • precipitation_amount_sum_1h: mm\n  • precipitation_amount_sum_3h: mm\n  • precipitation_amount_sum_6h: mm\n  • precipitation_amount_sum_12h: mm\n  • precipitation_amount_sum_24h: mm\n  • atmosphere_convective_available_potential_energy: J/kg\n  • predominant_precipitation_type_at_surface: categorical\n  • sea_surface_temperature: K"},"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 market zones capable of MW output

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

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"forecast","description":"Query and retrieve weather forecast data from Jua's platform."}],"paths":{"/v1/forecast/market-aggregate/mw-zones":{"get":{"tags":["forecast"],"summary":"List market zones capable of MW output","description":"Return market zones that have both facility data and fitted power curves.\n\nThis is a metadata endpoint and does not require authentication.\n\nA zone is MW-capable for wind if it has operating wind facilities\n*and* corresponding entries in the wind power-curve tables.\nSame logic applies for solar.\n\nResults are cached in-memory for 5 minutes.","operationId":"get_mw_zones_v1_forecast_market_aggregate_mw_zones_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MWZonesResponse"}}}}}}}},"components":{"schemas":{"MWZonesResponse":{"properties":{"wind":{"items":{"type":"string"},"type":"array","title":"Wind"},"wind_combined":{"items":{"type":"string"},"type":"array","title":"Wind Combined"},"solar":{"items":{"type":"string"},"type":"array","title":"Solar"},"load":{"items":{"type":"string"},"type":"array","title":"Load"}},"type":"object","required":["wind","wind_combined","solar","load"],"title":"MWZonesResponse","description":"Market zones that have power-curve data and can produce MW output."}}}}
```