aionatgrid 0.3.0

Async Python client for National Grid built on aiohttp

aionatgrid

Async Python client for National Grid's GraphQL and REST APIs.

Installation

pip install aionatgrid

Quick Start

import asyncio
from aionatgrid import NationalGridClient, NationalGridConfig

async def main() -> None:
    config = NationalGridConfig(
        username="[e-mail]",
        password="your-password",
    )

    async with NationalGridClient(config=config) as client:
        response = await client.linked_billing_accounts()
        print(response.data)

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

Query Methods

Method	Description
linked_billing_accounts()	Get linked billing account IDs
billing_account_info()	Get account details (region, meters, address)
energy_usage_costs()	Get energy costs for a billing period
energy_usages()	Get historical usage data
ami_energy_usages()	Get AMI hourly energy usage
realtime_meter_info()	Get real-time meter readings (REST)

For custom queries, use execute() with a GraphQLRequest directly.

Examples

uv run python examples/list-accounts.py --username [e-mail] --password secret
uv run python examples/account-info.py --username [e-mail] --password secret
uv run python examples/energy-usage.py --username [e-mail] --password secret
uv run python examples/interval-reads.py --username [e-mail] --password secret
uv run python examples/ami-usage.py --username [e-mail] --password secret

Development

Requires Python 3.10+ and uv.

uv sync                # install dependencies
uv run pytest          # run tests
uv run ruff check .    # lint
uv run ruff format .   # format
uv run mypy src        # type-check