API Endpoints

Access power generation forecast data through the Jua Query Engine.

Available Endpoints

1. Get Available Zones

GET /v1/power-forecast/zones

Returns list of available zone keys (countries/regions).

Example:

curl -X GET "https://query.jua.ai/v1/power-forecast/zones" \
  -H "X-API-Key: your_api_key_id:your_api_secret"

Response:

{"zones": ["DE"]}

---

2. Get Available PSR Types

GET /v1/power-forecast/psr-types

Returns list of available power system resource types.

Example:

curl -X GET "https://query.jua.ai/v1/power-forecast/psr-types" \
  -H "X-API-Key: your_api_key_id:your_api_secret"

Response:

{"psr_types": ["Solar", "Wind Onshore"]}

---

3. Get Available Init Times

GET /v1/power-forecast/init-times

Returns recent forecast initialization times for a zone.

Query Parameters:

• zone_key (required): Zone identifier (e.g., "DE")

• limit (optional): Number of recent init times to return

Example:

curl -X GET "https://query.jua.ai/v1/power-forecast/init-times?zone_key=DE&limit=3" \
  -H "X-API-Key: your_api_key_id:your_api_secret"

Response:

{
  "init_times": [
    {
      "init_time": "2026-02-24T14:00:00",
      "max_prediction_timedelta": 2025
    },
    {
      "init_time": "2026-02-24T13:45:00",
      "max_prediction_timedelta": 2040
    },
    {
      "init_time": "2026-02-24T13:30:00",
      "max_prediction_timedelta": 2055
    }
  ]
}

Fields:

• init_time: Forecast initialization timestamp (ISO 8601)

• max_prediction_timedelta: Maximum forecast horizon in minutes

---

4. Get Forecast Data

POST /v1/power-forecast/data

Retrieve power forecast data for specified zones and PSR types.

Request Body:

{
  "zone_keys": ["DE"],
  "psr_types": ["Solar", "Wind Onshore"],
  "latest_init_time": true,
  "order_by": ["time"]
}

Request Parameters:

Parameter	Type	Required	Description
zone_keys	array[string]	Yes	List of zone identifiers
psr_types	array[string]	Yes	List of PSR types ("Solar", "Wind Onshore")
latest_init_time	boolean	No	Get latest forecast (default: false)
init_times	array[string]	No	Specific init times to query
order_by	array[string]	No	Sort order (e.g., ["time"], ["init_time", "time"])

Note: Use either latest_init_time: true OR provide specific init_times, not both.

Example - Latest Forecast:

curl -X POST "https://query.jua.ai/v1/power-forecast/data" \
  -H "X-API-Key: your_api_key_id:your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "zone_keys": ["DE"],
    "psr_types": ["Solar"],
    "latest_init_time": true,
    "order_by": ["time"]
  }'

Example - Specific Init Times:

curl -X POST "https://query.jua.ai/v1/power-forecast/data" \
  -H "X-API-Key: your_api_key_id:your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "zone_keys": ["DE"],
    "psr_types": ["Wind Onshore"],
    "init_times": ["2026-02-24T13:00:00Z", "2026-02-24T14:00:00Z"],
    "order_by": ["init_time", "time"]
  }'

Response Format:

{
  "zone_key": ["DE", "DE", "DE", ...],
  "psr_type": ["Solar", "Solar", "Solar", ...],
  "init_time": ["2026-02-24T14:00:00+00:00", "2026-02-24T14:00:00+00:00", ...],
  "time": ["2026-02-24T14:00:00+00:00", "2026-02-24T14:15:00+00:00", ...],
  "value": [10902.29, 9434.68, 8016.34, ...]
}

Response Fields:

• zone_key: Array of zone identifiers (repeated for each data point)

• psr_type: Array of PSR types (repeated for each data point)

• init_time: Array of forecast initialization times

• time: Array of forecast valid times (15-minute intervals)

• value: Array of power values in MW

Notes:

• All timestamps are in UTC with timezone offset (+00:00)

• Power values are in MW (Megawatts)

• Time resolution is 15 minutes

• Each forecast run typically covers until the end of the next day

---

Python Example

import requests

API_KEY_ID = "your_api_key_id"
API_SECRET = "your_api_secret"
BASE_URL = "https://query.jua.ai"

headers = {
    "X-API-Key": f"{API_KEY_ID}:{API_SECRET}",
    "Content-Type": "application/json"
}

# Get available zones
zones = requests.get(f"{BASE_URL}/v1/power-forecast/zones", headers=headers)
print(zones.json())

# Get available PSR types
psr_types = requests.get(f"{BASE_URL}/v1/power-forecast/psr-types", headers=headers)
print(psr_types.json())

# Get latest forecast
payload = {
    "zone_keys": ["DE"],
    "psr_types": ["Solar"],
    "latest_init_time": True,
    "order_by": ["time"]
}

response = requests.post(
    f"{BASE_URL}/v1/power-forecast/data",
    headers=headers,
    json=payload
)

data = response.json()
print(f"Retrieved {len(data['time'])} data points")
print(f"First value: {data['value'][0]} MW at {data['time'][0]}")

---

Error Responses

401 Unauthorized

{"detail": "Unauthorized"}

400 Bad Request

{"detail": "Invalid parameters"}

---

See Also

• Power Forecast API Overview