aioecosmart

Async Python client for the Ecosmart price API — live New Zealand wholesale electricity spot prices, forecasts and settled prices for the connection points an API key carries.

Ecosmart is a New Zealand electricity retailer that passes wholesale spot prices through to customers. Account holders mint their own API key in the Ecosmart app under More → Settings → Advanced → API keys.

This library backs the Home Assistant ecosmart integration. Nothing in it depends on Home Assistant, so it is equally usable from a script, a battery controller, or a dashboard.

Install

pip install aioecosmart

Requires Python 3.13 or newer.

Usage

import asyncio
from aioecosmart import EcosmartClient


async def main() -> None:
    async with EcosmartClient("ecos_live_your_key_here") as client:
        me = await client.me()
        poc = me.allowed_icps[0].poc  # the grid exit point for your ICP
        now = await client.spot(poc)
        if not now.is_stale and now.price_cents_per_kwh_incl_gst is not None:
            print(f"{now.price_cents_per_kwh_incl_gst:.2f} c/kWh incl GST")
        ahead = await client.forecast(poc, hours=48)
        print(f"{ahead.count} half-hours, covering {ahead.covered_hours} h")


asyncio.run(main())

Pass your own aiohttp.ClientSession as the second argument and the client will use it without ever closing it; omit it and the client makes and closes its own.

What it covers

All seven published endpoints:

Things worth knowing before you build on it

• Prices are wholesale energy at the grid exit point, not a retail rate. Lines charges, metering, levies and retailer margin are not included.
• GST. Everything the market publishes is GST-exclusive. Use price_cents_per_kwh_incl_gst to compare with a power bill.
• Negative prices are real, especially overnight in the South Island. They pass through untouched.
• Stale is not an error. A Spot with is_stale true, or with null prices, is a valid 200. Treat it as unavailable rather than as a failure — a price more than about 15 minutes old must never drive a battery.
• Empty is not an error either. A Forecast with no points, or Windows with empty cheap/dear, is a valid 200 with unavailable_reason set.
• Read covered_hours, not horizon_hours. The latter is only your request echoed back after clamping; the former is how far the published schedules reach.
• Use trading_date and trading_period verbatim. Two days a year have 46 or 50 trading periods instead of 48; never recompute half-hours locally.
• Timestamps are UTC (Z) and arrive as timezone-aware datetime objects.
• The library never retries and never throttles. The API allows a documented minimum of 12 requests per minute per key, with X-RateLimit-* on every response and Retry-After on a 429; scheduling and backoff belong to the caller. The most recent budget is on the rate_limit property.
• Minting a new key revokes the previous one. A rotated key shows up as EcosmartAuthError, indistinguishable from an unknown or revoked one.

Errors

Everything inherits EcosmartError.

Documentation

• Human documentation: https://www.ecosmart.co.nz/electricity/api/
• Machine contract: https://www.ecosmart.co.nz/electricity/openapi.yaml

Licence

MIT. See LICENSE.