MQTT

Use MQTT to get real-time notifications when new forecasts are available.

Step 1: Get a username and password

To use the MQTT service, you’ll first need to register and receive your credentials.

1. Get a username and password by contacting us at info@pythia-energy.nl
2. You’ll receive a username and password – save these securely.

Continue to the next step once you have your credentials.

Example: Connect to the MQTT broker and receive messages

We provide the following topic for our quantile forecast.

• helio/quantiles/

This topic publishes a message whenever a new forecast run becomes available, allowing you to react in real time to the latest updates. See the message format below.

import random
from paho.mqtt import client as mqtt_client

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

broker = "mqtt.pythia-energy.nl"
port = 1883
topic = "helio/quantiles/" 
client_id = f"helio-client-{random.randint(0, 1000)}"
def connect_mqtt():
    def on_connect(
        client, 
        userdata, 
        flags, 
        rc, 
        properties=None
        ):
        if rc == 0:
            print("Connected to MQTT Broker!")
        else:
            try:
                print(
                    f"Failed to connect, return code {rc} ({mqtt_client.connack_string(rc)})"
                    )
            except Exception:
                print(
                    f"Failed to connect, return code {rc}"
                    )

    client = mqtt_client.Client(
        callback_api_version=mqtt_client.CallbackAPIVersion.VERSION2,
        client_id=client_id,
    )
    client.username_pw_set(USERNAME, PASSWORD) 
    client.on_connect = on_connect
    client.connect(broker, port)
    return client


def subscribe(client: mqtt_client):
    def on_message(client, userdata, msg):
        print(f"\nReceived `{msg.payload.decode(errors='replace')}` from `{msg.topic}` topic")
        try:
            payload = json.loads(msg.payload.decode())
            print(json.dumps(payload, indent=2))

            # Add your custom processing logic here

        except Exception:
            pass

    client.subscribe(topic)
    client.on_message = on_message


def run():
    client = connect_mqtt()
    subscribe(client)
    client.loop_forever()

run()

Message format

All messages follow a common structure:

{
  "type": "<message_type>",
  "parameter": "<forecast_type>",
  "forecast_datetime": "<ISO8601 timestamp>"
}

• type: Type of message (e.g. forecast)
• parameter: Describes the forecast content (e.g. quantiles)
• forecast_datetime: Timestamp of the forecast run in UTC (ISO 8601 format)

Here’s an example of a message you might receive:

• Topic helio/quantiles/

{
"type": "forecast",
"parameter": "helio quantiles ghi",
"forecast_datetime": "2026-04-15T12:00:00Z"
}