Get Started

Follow these steps to start using the Helio API for short-term solar irradiance forecasting.

Step 1: Register and get an API key

Register to get an account. You’ll receive credentials to authenticate with the API.

Step 2: Understand the API endpoints

• Get to know the available endpoints. Detailed information can be found here.
• We provide two types of endpoints: one for specific locations and another for the entire grid of the Netherlands.

Step 3: Make your first API call

1. install packages

pip install requests pandas paho-mqtt

The Helio API uses Firebase ID tokens as Bearer tokens. The helper below exchanges an email/password pair for an Authorization header that is passed to every subsequent request.

import requests
import json


def get_firebase_auth_headers(username: str, password: str) -> dict[str, str]:
    """
    Authenticate a user with Firebase and return the authorization headers
    required for subsequent API requests.

    Parameters
    ----------
    username : str
        The email address of the user.
    password : str
        The password of the user.
    """
    firebase_key = "AIzaSyDBWBRW0WU9kGL5wNFfvtBLRue0UbgfIhk"
    firebase_url = "https://identitytoolkit.googleapis.com/v1"
    firebase_endpoint = f"{firebase_url}/accounts:signInWithPassword?key={firebase_key}"
    data_dict = {"email": username, "password": password, "returnSecureToken": "true"}
    response_post_token = requests.post(firebase_endpoint, data=data_dict)
    if response_post_token.status_code == 200:
        id_token = response_post_token.json()["idToken"]
        headers = {"Content-Type": "application/json", "Authorization": f"Bearer {id_token}"}
    else:
        print(f"Failed to authenticate user with Firebase. {response_post_token.text}")
        headers = {"Content-Type": "application/json", "Authorization": ""}
    return headers

2. Authenticate

# Fill in your credentials
# USERNAME = "your-email@example.com"
# PASSWORD = "your-password"

headers = get_firebase_auth_headers(USERNAME, PASSWORD)
print("Authenticated:", "Authorization" in headers and bool(headers["Authorization"]))

3. Configuration

from datetime import datetime, timedelta, timezone

BASE_URL = "https://api.pythia-energy.nl/helio"

# Use yesterday noon UTC as a safe forecast_datetime (avoids future / too-old validation)
forecast_dt = (
    datetime.now(timezone.utc) - timedelta(days=1)
).replace(hour=12, minute=0, second=0, microsecond=0)
FORECAST_DATETIME = forecast_dt.strftime("%Y-%m-%dT%H:%M:%SZ")

print("Forecast datetime:", FORECAST_DATETIME)

# Example point coordinates (Netherlands)
LATITUDES  = [51.960556]
LONGITUDES = [4.446944]

print("Example coordinates:", list(zip(LATITUDES, LONGITUDES)))

4. Credits

Basic credit summary

response = requests.get(f"{BASE_URL}/credits/", headers=headers)
print(response.status_code)
print(json.dumps(response.json(), indent=2))

5. Quantile forecasts — point

Returns 13 probability levels (quantiles) of GHI [W/m²] at the requested coordinates, at 15-minute intervals up to 6 hours ahead.

payload = {
    "forecast_datetime": FORECAST_DATETIME,
    "latitudes": LATITUDES,
    "longitudes": LONGITUDES,
}

response = requests.post(f"{BASE_URL}/quantiles/point/", headers=headers, json=payload)
print(f"Status code: {response.status_code}")

quantile_point = response.json()["data"]
quantile_point

Download the full notebook

Step 4: Integrate the API into your application

• Consider subscribing to our MQTT service to receive real-time notifications whenever a new forecast becomes available.