pylondonair

Async Python client for the London Air hourly air-quality monitoring index, published by Imperial College London.

pylondonair fetches the hourly monitoring index for the Greater London monitoring network and parses it into clean, typed, immutable data models. It is the data layer behind the Home Assistant London Air integration, but it is a standalone library with no Home Assistant dependency and can be used from any async Python project.

• Async-first — built on aiohttp; the only runtime dependency (plus tzdata on Windows).
• Typed — mypy --strict clean, ships a py.typed marker, full type hints.
• Immutable models — frozen dataclasses; safe to share across tasks.
• No auth, no config — the public feed requires no credentials.

Installation

pip install pylondonair

Requires Python 3.12 or newer.

Quickstart

import asyncio

from pylondonair import LondonAirClient


async def main() -> None:
    async with LondonAirClient() as client:
        data = await client.async_update()

    print(data.group_name)          # "London"
    print(data.time_to_live)        # minutes until the feed is expected to refresh
    for authority in data.authorities.values():
        print(authority.name, authority.status)
        for site in authority.sites:
            print("  ", site.site_name, site.status, site.updated)
            for pollutant in site.pollutants:
                print("    ", pollutant.summary)  # e.g. "PM10 is Low"


asyncio.run(main())

Reusing an existing session

If you already manage an aiohttp.ClientSession (for example, Home Assistant passes its shared session), inject it. The client will not close a session it did not create:

import aiohttp
from pylondonair import LondonAirClient

async with aiohttp.ClientSession() as session:
    client = LondonAirClient(session=session)
    data = await client.async_update()
    # `session` is still open and owned by you.

Connection check

async_test_connection() performs a lightweight GET + status check without parsing the payload. It is intended for config-flow style validation:

await client.async_test_connection()  # raises LondonAirConnectionError on failure

Data model

async_update() returns a LondonAirData:

All models are frozen dataclasses (immutable). Pollutant, Site, and Authority are also hashable; LondonAirData is not, because its authorities mapping is not hashable.

Status aggregation

• Site.status is the most common pollutant quality band at that site. If a site has no usable species it is the sentinel string no_species_data (exported as NO_SPECIES_DATA).
• Authority.status is the most common site status, excluding the sentinel. It is None when the authority has no sites or all sites are no_species_data.

Ties are broken by first appearance in the payload.

@TimeToLive

The feed carries a @TimeToLive attribute (minutes) indicating how long the data is expected to remain current. pylondonair parses it into LondonAirData.time_to_live. If the attribute is missing or non-numeric it defaults to 60 and a warning is logged.

WGS84 fields (footgun)

The API exposes @...WGS84 coordinate fields. Despite the name, these are projected metres (a projected coordinate system), not decimal degrees. pylondonair includes them verbatim under the API-faithful names (latitude_wgs84, longitude_wgs84, centre_latitude_wgs84, centre_longitude_wgs84) as str | None. Do not treat them as lat/long degrees; use the plain latitude/longitude fields (decimal degrees) for geographic purposes.

Error handling

pylondonair raises a small, dedicated hierarchy rooted at LondonAirError:

from pylondonair import (
    LondonAirClient,
    LondonAirConnectionError,
    LondonAirUpdateError,
)

try:
    data = await client.async_update()
except LondonAirConnectionError:
    ...  # transient; retry later
except LondonAirUpdateError:
    ...  # unexpected payload shape; inspect and report

Attribution

Air quality data is provided by London Air and Imperial College London. The API is documented at https://www.imperial.ac.uk/londonair/api/.

License

MIT.