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

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"

Python

Javascript

Response

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

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"

Python

Javascript

Response

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

Python

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

Javascript

Response

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

Python

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

Javascript

Response

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