Edit

Getting Started

Are you using Python? Check out our Python SDK to get started in no time!

Authentication

To access Jua's API, you must create an API key in the developer portal. Include the key in your requests using the X-API-Key header.

X-API-Key: API_KEY_ID:API_KEY_SECRET

Query Data

Details about the request parameters & response formats are available in the Query Engine documentation

1. Query a 3-day forecast for Zurich

curl -X GET "https://query.jua.ai/v1/forecast/\
?models=ept2\
&init_time=latest\
&latitude=47.37\
&longitude=8.54\
&variables=air_temperature_at_height_level_2m\
&variables=wind_speed_at_height_level_10m\
&max_prediction_timedelta=72\
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

2. Query market aggregated data

You can finde more details about market aggregates here

Query the average windspeed over Germany, weighted by wind energy production capacity

curl -X GET "https://query.jua.ai/v1/forecast/market-aggregate\
?models=ept2\
&init_time=2025-10-22T00:00:00Z\
&weighting=wind_capacity\
&market_zones=DE\
&variables=wind_speed_at_height_level_100m\
&max_prediction_timedelta=72\
&include_time=true \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

To query wind speed at 100m your subscription must be Pro or higher

3. Using the general `data` endpoint (POST)

/data allows to make complex analytical queries, select regions, apply custom aggregations and much more.

The features include:

  • Making complex geospatial queries, supporting points, bounding boxes, polygons, market zones and countries

  • Querying multiple times at once, including historical time slices

  • Apply groupings and aggregations such as "hourly minimum and maximum temperature in Switzerland"

  • Apply solar & wind capacity or population density weighting to your queries

Checkout our examples for a hands on overview of Query Engine's capabilities

3.1 Request 3 months of historical data for Zurich for EPT2 and IFS

import requests

url = "https://query.jua.ai/v1/forecast/data"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
params = {
    # use arrow for larger requests, see query engine docs
    "format": "json" 
}
payload = {
    "models": ["ept2", "ecmwf_ifs_single"],
    "geo": {
        "type": "point",
        "value": [47.37, 8.54]  # Zurich [latitude, longitude]
    },
    "variables": [
        "air_temperature_at_height_level_2m",
        "wind_speed_at_height_level_10m"
    ],
    "init_time": {
        "start": "2025-02-01T00:00:00Z",
        "end": "2025-04-30T23:59:59Z"
    },
    "prediction_timedelta": {
        "start": 0,
        "end": 72
    },
    "order_by": ["model", "init_time", "time"],
    "include_time": True,
    "time_zone": "Europe/Zurich",
}

response = requests.post(url, headers=headers, params=params, json=payload)
data = response.json()

3.2 Compute population-weighted temperature average for a custom polygon region

import requests

url = "https://query.jua.ai/v1/forecast/data"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
params = {
    "format": "json"
}
payload = {
    "models": ["ept2"],
    "geo": {
        "type": "polygon",
        "value": [
            # Custom polygon around a region
            [45.82, 5.96],
            [45.82, 10.49], 
            [47.81, 10.49], 
            [47.81, 5.96],  
            [45.82, 5.96]
        ]
    },
    "variables": ["air_temperature_at_height_level_2m"],
    "init_time": "latest",
    "prediction_timedelta": {
        "start": 0,
        "end": 72
    },
    "weighting": {
        "type": "population"
    },
    "group_by": ["model", "init_time", "prediction_timedelta", "time"],
    "aggregation": ["avg"],
    "include_time": True,
    "time_zone": "Europe/Zurich"
}

response = requests.post(url, headers=headers, params=params, json=payload)
data = response.json()

Key Differences Between GET and POST

Feature

GET Endpoints

POST /data Endpoint

Use Case

Simple queries

Complex queries, large datasets

Response Format

JSON only

JSON or Apache Arrow

Streaming

Not supported

Supported with Arrow format

Query Complexity

Limited parameters

Full query flexibility

URL Length

Limited by URL length

No practical limit

Aggregation

Limited (market-aggregate only)

Full aggregation support

Common Parameters

Time Parameters

  • init_time: Forecast initialization time (ISO 8601 format) or "latest" for most recent forecast

  • prediction_timedelta: Lead time in minutes from init_time

    • Single query: {"start": 0, "end": 6} for 0-6 hours

    • Or use min_prediction_timedelta and max_prediction_timedelta in GET requests

Location Parameters

  • Point: {"type": "point", "value": [longitude, latitude], "method": "nearest"}

  • Market Zone: {"type": "market_zone", "value": ["DE", "FR"]}

  • Country: {"type": "country_key", "value": ["DE"]}

  • Bounding Box: {"type": "bbox", "value": [[lat_min, lon_min], [lat_max, lon_max]]}

Aggregation & Weighting

  • weighting: wind_capacity, solar_capacity, or population

  • group_by: Columns to group by (e.g., ["model", "init_time", "time"])

Credit Management

  • request_credit_limit: Maximum credits allowed for the request (prevents unexpectedly large charges)

  • Use /cost endpoint to estimate query cost before execution

Error Handling

Common HTTP status codes:

  • 200: Success

  • 400: Invalid parameters or response size exceeded

  • 401: Missing or invalid API key

  • 402: Insufficient credits

  • 403: Model or variable not in subscription

PreviousTechnical DocumentationNextQuery Engine

Last updated