# Reanalysis

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

## Query reanalysis data

> Query reanalysis data from models like ARCO ERA5.\
> \
> Reanalysis data provides historical weather analysis at a specific time (unlike forecasts\
> which have init\_time + prediction\_timedelta dimensions). This is useful for:\
> \- Historical weather analysis\
> \- Training and validating machine learning models\
> \- Comparing forecasts against actuals\
> \
> \*\*Query Dimensions:\*\*\
> \- \`models\`: Reanalysis model(s) to query (e.g., \["arco\_era5"])\
> \- \`geo\`: Location filter (point, bounding\_box, polygon, market\_zone, country\_key)\
> \- \`time\`: Time(s) to query - "latest", single datetime, list of datetimes, or time range\
> \- \`variables\`: Weather variables to retrieve\
> \
> \*\*Response Formats:\*\*\
> \- \`json\`: Columnar JSON format \`{column: \[values], ...}\`\
> \- \`arrow\`: Apache Arrow IPC stream for efficient processing\
> \
> \*\*Authentication\*\*: Requires API key.\
> \
> For more information, see \[docs.jua.ai]\(<https://docs.jua.ai>).

````json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"reanalysis","description":"Query reanalysis data from models like ARCO ERA5 for historical weather analysis."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/reanalysis/data":{"post":{"tags":["reanalysis"],"summary":"Query reanalysis data","description":"Query reanalysis data from models like ARCO ERA5.\n\nReanalysis data provides historical weather analysis at a specific time (unlike forecasts\nwhich have init_time + prediction_timedelta dimensions). This is useful for:\n- Historical weather analysis\n- Training and validating machine learning models\n- Comparing forecasts against actuals\n\n**Query Dimensions:**\n- `models`: Reanalysis model(s) to query (e.g., [\"arco_era5\"])\n- `geo`: Location filter (point, bounding_box, polygon, market_zone, country_key)\n- `time`: Time(s) to query - \"latest\", single datetime, list of datetimes, or time range\n- `variables`: Weather variables to retrieve\n\n**Response Formats:**\n- `json`: Columnar JSON format `{column: [values], ...}`\n- `arrow`: Apache Arrow IPC stream for efficient processing\n\n**Authentication**: Requires API key.\n\nFor more information, see [docs.jua.ai](https://docs.jua.ai).","operationId":"post_reanalysis_data_v1_reanalysis_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","default":"json","title":"Format"},"description":"Response format: 'json' for columnar JSON or 'arrow' for Apache Arrow"},{"name":"stream","in":"query","required":false,"schema":{"type":"boolean","description":"If true, stream the response as an Apache Arrow IPC stream. Overrides 'format' to 'arrow'.","default":false,"title":"Stream"},"description":"If true, stream the response as an Apache Arrow IPC stream. Overrides 'format' to 'arrow'."},{"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/ReanalysisQuery"}}}},"responses":{"200":{"description":"Successfully retrieved reanalysis data","content":{"application/json":{"schema":{}},"application/vnd.apache.arrow.stream":{"description":"Apache Arrow IPC stream format"}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Authentication required"},"402":{"description":"Insufficient credits"},"403":{"description":"Insufficient permissions"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ReanalysisQuery":{"properties":{"models":{"items":{"$ref":"#/components/schemas/ReanalysisModel"},"type":"array","title":"Models","description":"List of reanalysis model identifiers to query"},"geo":{"$ref":"#/components/schemas/GeoFilter","description":"Geographic filter specifying the query location(s) or region(s)"},"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":"Time","description":"Time(s) to query. Can be 'latest' (or integer offset 0), a single datetime, a list of datetimes, or a TimeSlice range."},"variables":{"items":{"$ref":"#/components/schemas/CustomerVariable"},"type":"array","title":"Variables","description":"List of weather variables to query. If empty, returns all variables available for the selected models"},"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', 'time']). Requires 'aggregation' to be specified."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/OrderByItem_Union_ReanalysisCoordinates__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 time column in results (default: True)","default":true},"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}},"type":"object","required":["models","geo","time"],"title":"ReanalysisQuery","description":"Query object for retrieving reanalysis data.\n\nReanalysis data uses a simple time dimension (unlike forecasts which\nhave init_time + prediction_timedelta). This provides historical\nanalysis data at specified timestamps.\n\nExample:\n    ```python\n    query = ReanalysisQuery(\n        models=[\"arco_era5\"],\n        geo={\"type\": \"point\", \"value\": [(52.52, 13.405)]},\n        time={\"start\": \"2024-01-01T00:00:00Z\", \"end\": \"2024-01-07T00:00:00Z\"},\n        variables=[\"air_temperature_at_height_level_2m\"],\n    )\n    ```"},"ReanalysisModel":{"type":"string","enum":["arco_era5"],"title":"ReanalysisModel","description":"Enumeration of available reanalysis models.\n\nUnlike forecast models which have init_time + prediction_timedelta dimensions,\nreanalysis models have a single time dimension representing the actual timestamp\nof the analysis."},"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"},"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_ReanalysisCoordinates__CustomerVariable__":{"properties":{"field":{"anyOf":[{"$ref":"#/components/schemas/ReanalysisCoordinates"},{"$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[ReanalysisCoordinates, CustomerVariable]]"},"ReanalysisCoordinates":{"type":"string","enum":["model","time","latitude","longitude","point","market_zone","country_key"],"title":"ReanalysisCoordinates","description":"Coordinate dimensions available for reanalysis queries."},"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"},"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"}}}}
````

## Get reanalysis dataset metadata

> Get metadata about available reanalysis models including:\
> \- Model names and display names\
> \- Grid resolution and temporal resolution\
> \- Available variables\
> \
> \*\*Authentication\*\*: Requires API key.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"reanalysis","description":"Query reanalysis data from models like ARCO ERA5 for historical weather analysis."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/reanalysis/meta":{"get":{"tags":["reanalysis"],"summary":"Get reanalysis dataset metadata","description":"Get metadata about available reanalysis models including:\n- Model names and display names\n- Grid resolution and temporal resolution\n- Available variables\n\n**Authentication**: Requires API key.","operationId":"get_reanalysis_meta_v1_reanalysis_meta_get","responses":{"200":{"description":"Successfully retrieved metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReanalysisMetaResult"}}}},"401":{"description":"Authentication required"}}}}},"components":{"schemas":{"ReanalysisMetaResult":{"properties":{"models":{"items":{"$ref":"#/components/schemas/ReanalysisModelInfo"},"type":"array","title":"Models"}},"type":"object","required":["models"],"title":"ReanalysisMetaResult","description":"Metadata about available reanalysis models."},"ReanalysisModelInfo":{"properties":{"name":{"type":"string","title":"Name"},"display_name":{"type":"string","title":"Display Name"},"grid_resolution":{"type":"string","title":"Grid Resolution"},"temporal_resolution_minutes":{"type":"integer","title":"Temporal Resolution Minutes"},"variables":{"items":{"type":"string"},"type":"array","title":"Variables"},"variable_units":{"additionalProperties":{"type":"string"},"type":"object","title":"Variable Units","default":{}}},"type":"object","required":["name","display_name","grid_resolution","temporal_resolution_minutes","variables"],"title":"ReanalysisModelInfo","description":"Information about a reanalysis model."}}}}
```

## Get latest available timestamp

> Get the latest available timestamp for each specified reanalysis model.\
> \
> This is useful for knowing what data is currently available without making a full query.\
> \
> \*\*Authentication\*\*: Requires API key.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"reanalysis","description":"Query reanalysis data from models like ARCO ERA5 for historical weather analysis."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/reanalysis/latest-timestamp":{"get":{"tags":["reanalysis"],"summary":"Get latest available timestamp","description":"Get the latest available timestamp for each specified reanalysis model.\n\nThis is useful for knowing what data is currently available without making a full query.\n\n**Authentication**: Requires API key.","operationId":"get_latest_timestamp_v1_reanalysis_latest_timestamp_get","parameters":[{"name":"models","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"List of reanalysis models to check","default":["arco_era5"],"title":"Models"},"description":"List of reanalysis models to check"}],"responses":{"200":{"description":"Successfully retrieved latest timestamps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatestTimestampResult"}}}},"401":{"description":"Authentication required"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"LatestTimestampResult":{"properties":{"timestamps":{"additionalProperties":{"type":"string","format":"date-time"},"type":"object","title":"Timestamps"}},"type":"object","required":["timestamps"],"title":"LatestTimestampResult","description":"Result containing latest timestamps per model."},"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"}}}}
```

## Get available timestamps

> Get a list of available timestamps for each specified reanalysis model within an optional\
> time range.\
> \
> \*\*Authentication\*\*: Requires API key.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"reanalysis","description":"Query reanalysis data from models like ARCO ERA5 for historical weather analysis."}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/reanalysis/available-timestamps":{"get":{"tags":["reanalysis"],"summary":"Get available timestamps","description":"Get a list of available timestamps for each specified reanalysis model within an optional\ntime range.\n\n**Authentication**: Requires API key.","operationId":"get_available_timestamps_v1_reanalysis_available_timestamps_get","parameters":[{"name":"models","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"List of reanalysis models to check","default":["arco_era5"],"title":"Models"},"description":"List of reanalysis models to check"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only return timestamps >= this time (inclusive)","title":"Since"},"description":"Only return timestamps >= this time (inclusive)"},{"name":"before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only return timestamps < this time (exclusive)","title":"Before"},"description":"Only return timestamps < this time (exclusive)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of timestamps to return","default":100,"title":"Limit"},"description":"Maximum number of timestamps to return"}],"responses":{"200":{"description":"Successfully retrieved available timestamps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableTimestampsResult"}}}},"401":{"description":"Authentication required"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AvailableTimestampsResult":{"properties":{"timestamps":{"additionalProperties":{"items":{"type":"string","format":"date-time"},"type":"array"},"type":"object","title":"Timestamps"}},"type":"object","required":["timestamps"],"title":"AvailableTimestampsResult","description":"Result containing available timestamps per model."},"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"}}}}
```