pyzonneplan

Asynchronous Python client for the Zonneplan API.

About

pyzonneplan is an async client for the Zonneplan API, focused on:

• Dynamic electricity and gas prices
• Electricity and gas consumption, also without a P1 meter
• Solar (PV) installation data
• Home battery monitoring and control modes
• EV charge point sessions and schedules

The library is under active development and endpoint coverage will keep expanding.

Installation

pip install pyzonneplan

Usage

Zonneplan authenticates with a one-time password (OTP) mailed to the account address instead of a password. Log in once, then store the token and pass it back in later:

import asyncio
import json
from datetime import date
from pathlib import Path

from pyzonneplan import Token, Zonneplan

TOKEN_FILE = Path("token.json")


async def main() -> None:
    """Log in (or restore the saved token) and read some data."""
    token = Token.from_dict(json.loads(TOKEN_FILE.read_text())) if TOKEN_FILE.exists() else None

    async with Zonneplan(email="you@example.com", token=token) as client:
        if token is None:
            challenge = await client.async_request_otp(source_name="pyzonneplan")
            await client.async_submit_otp(challenge, input("One-time password: "))

        account = await client.async_get_account()
        for connection in account.connections:
            print(connection.market_segment, connection.uuid)

        electricity = next(c for c in account.connections if c.market_segment == "electricity")
        summary = await client.async_get_summary(electricity.uuid)
        print("Tariff group now:", summary.usage.type)

        chart = await client.async_get_electricity_chart(electricity.uuid, date.today())
        if chart.group is not None and chart.group.has_data:
            print("Used today:", chart.group.delivered_kwh, "kWh")

        # The client refreshes the token when it nears expiry, which rotates it: save the latest one.
        if client.token is not None:
            TOKEN_FILE.write_text(json.dumps(client.token.as_dict()))


if __name__ == "__main__":
    asyncio.run(main())

Available data

The contract UUIDs come from the account, e.g. connection.contracts_of_type(ContractType.HOME_BATTERY) (constants such as ContractType, ChartInterval and BatteryMode live in pyzonneplan.const). For a contract the account doesn't have, the battery and charge point methods raise ZonneplanNotFoundError. Fields keep the API's raw units (1e-7 EUR, Wh, dm³, permille); properties such as delivered_kwh, electricity_price_euro and state_of_charge_percent convert them.

Usage without a P1 meter arrives a day or more late from the grid operator: check has_data before trusting zeros, and expect the last hours of a day to be revised when the next day arrives.

The PV, battery and charge point models follow the responses other projects have seen, but haven't been tested against live hardware yet. Reports and captured (anonymised) responses are welcome.

Actions

A battery with both modes off trades on the dynamic prices (BatteryMode.DYNAMIC_CHARGING). The API doesn't switch the other mode off for you; async_set_battery_control_mode() does, like the Zonneplan app. The battery and charge point confirm a change asynchronously; until then their state reports processing. Actions are sent once and never retried.

Errors

Every error derives from ZonneplanError:

• ZonneplanAuthenticationError: the token is invalid or expired (log in again); ZonneplanInvalidOtpError when the OTP is rejected.
• ZonneplanRateLimitError: HTTP 429; retry_after holds the seconds to wait. It isn't retried.
• ZonneplanRequestError: the API rejected the request (HTTP 4xx), e.g. an unknown chart interval; ZonneplanNotFoundError for a 404, e.g. a device the account doesn't have. Not retried.
• ZonneplanResponseError: the response isn't JSON or doesn't have the expected shape.
• ZonneplanConnectionError / ZonneplanTimeoutError: a network error, a timeout or an HTTP 5xx. GET requests are retried with backoff first (max_retries, default 3); actions are never retried.

More examples can be found in the examples directory.

Documentation

Project documentation and API reference: https://erwindouna.github.io/pyzonneplan/

Contributing

Contributions are welcome. Please open an issue or pull request.

For local development:

uv sync --all-groups && uv run pre-commit install

Run checks:

uv run pre-commit run --all-files

Run tests:

uv run pytest

License

MIT License

Copyright (c) 2026 Erwin Douna