ptr727-aiopurpleair 1.0.0.dev0

Async Python client for the PurpleAir API, with the organization endpoint and typed error codes.

aiopurpleair

Async Python client library for the PurpleAir air-quality API, with the organization endpoint and typed error codes.

Build and Distribution

• Source Code: GitHub - Source code, issues, discussions, and CI/CD pipelines.
• Versioned Releases: GitHub Releases - Version tagged source code and build artifacts.
• PyPI Packages: PyPI - Python wheel + sdist published to PyPI.org as ptr727-aiopurpleair.

Build Status

Releases

Release Notes

See HISTORY.md for the release notes ledger.

Getting Started

Get started with aiopurpleair in two easy steps:

1. Add aiopurpleair to your project:

   # Add the package to your project (import name stays `aiopurpleair`)
   pip install ptr727-aiopurpleair
   

2. Write some code:

   import asyncio
   
   from aiopurpleair import API
   
   
   async def main() -> None:
       """Check an API key and fetch sensors."""
       api = API("<API_KEY>")
       keys = await api.async_check_api_key()
       sensors = await api.sensors.async_get_sensors(["name", "pm2.5"])
       organization = await api.organizations.async_get_organization()
   
   
   asyncio.run(main())
   

See Usage for detailed usage instructions.

Table of Contents

• aiopurpleair
  • Build and Distribution
    • Build Status
    • Releases
    • Release Notes
  • Getting Started
  • Table of Contents
  • Features
  • Usage
    • Checking an API Key
    • Getting Sensors
    • Getting the Organization
    • Error Handling
    • Connection Pooling
  • Installation
  • Questions or Issues
  • Build Artifacts
  • API Reference
  • Contributing
  • Origin
  • License

Features

• Async client for the PurpleAir API, covering the sensors and keys endpoints.
• GET /v1/organization endpoint exposing remaining API points and consumption rate.
• Typed exception hierarchy mapped from the API's documented error codes.
• Timezone-aware UTC datetimes and typed Pydantic response models with a py.typed marker.
• Modern packaging: hatchling, uv, automatic versioning, OIDC-published releases, and 100% test coverage.

Usage

In-depth documentation on the API is available from PurpleAir. Unless otherwise noted, aiopurpleair follows the API as closely as possible.

Checking an API Key

import asyncio

from aiopurpleair import API


async def main() -> None:
    """Check whether an API key is valid and what properties it has."""
    api = API("<API_KEY>")
    response = await api.async_check_api_key()
    # >>> response.api_key_type == ApiKeyType.READ
    # >>> response.api_version == "V1.0.11-0.0.41"


asyncio.run(main())

Getting Sensors

import asyncio

from aiopurpleair import API


async def main() -> None:
    """Fetch sensor data for the requested fields."""
    api = API("<API_KEY>")
    response = await api.sensors.async_get_sensors(["name", "pm2.5"])
    # >>> response.data == {131075: SensorModel(...), 131079: SensorModel(...)}


asyncio.run(main())

Private sensors require their per-sensor read key: pass read_key= to async_get_sensor, or read_keys=[...] to async_get_sensors. Use async_get_nearby_sensors(fields, latitude, longitude, distance) for a distance-sorted search, and get_map_url(sensor_index) for a map link.

Getting the Organization

The organization endpoint reports the account's remaining API points and consumption rate, useful for surfacing a low-points warning before queries start failing:

import asyncio

from aiopurpleair import API


async def main() -> None:
    """Fetch the organization associated with the API key."""
    api = API("<API_KEY>")
    response = await api.organizations.async_get_organization()
    # >>> response.remaining_points == 500000
    # >>> response.consumption_rate == 1234.5
    # >>> response.organization_id == "..."
    # >>> response.organization_name == "..."


asyncio.run(main())

Error Handling

Each documented PurpleAir API error code maps to a specific exception subclass, so callers can catch a precise condition instead of pattern-matching on str(err). Every subclass derives from PurpleAirError:

import asyncio

from aiopurpleair import API
from aiopurpleair.errors import InvalidApiKeyError, RateLimitExceededError


async def main() -> None:
    """Handle specific PurpleAir error conditions."""
    api = API("<API_KEY>")
    try:
        await api.sensors.async_get_sensors(["name"])
    except InvalidApiKeyError:
        ...  # the API key is missing or invalid
    except RateLimitExceededError:
        ...  # back off and retry later


asyncio.run(main())

All error codes and semantics are verified against the official PurpleAir API documentation.

Connection Pooling

By default a new connection is created per coroutine. Pass an existing aiohttp ClientSession for connection pooling:

import asyncio

from aiohttp import ClientSession

from aiopurpleair import API


async def main() -> None:
    """Reuse a session across calls."""
    async with ClientSession() as session:
        api = API("<API_KEY>", session=session)
        ...


asyncio.run(main())

Installation

Project integration:

# Add the package to your project
pip install ptr727-aiopurpleair

# Import the library (the import name stays `aiopurpleair`)
import aiopurpleair

The distribution name is ptr727-aiopurpleair (distinct from the canonical aiopurpleair on PyPI); the import path is unchanged. aiopurpleair supports Python 3.13 and 3.14, and depends on aiohttp, pydantic, yarl, and certifi.

Questions or Issues

General questions:

• Use the Discussions forum for general questions.

Bug reports:

• Ask in the Discussions forum if you are not sure if it is a bug.
• Check the existing Issues tracker for known problems.
• If the issue is unique and a bug, file it in Issues, and include all pertinent steps to reproduce the issue.

Build Artifacts

Build process and artifacts:

• Package: a Python wheel + sdist (ptr727-aiopurpleair), built with the hatchling backend on a src-layout (src/aiopurpleair/) and managed with uv.
• Versioning: automatic via Nerdbank.GitVersioning from version.json (1.0 base) plus git height; main builds a clean stable X.Y.Z, develop a X.Y.Z.dev0 prerelease. There is no manual tagging.
• Publishing: releases publish to PyPI over OIDC Trusted Publishing (no stored API token). A shipped-path push to main (stable) or develop (prerelease), or a manual dispatch, cuts a GitHub Release and uploads the wheel + sdist to PyPI. See WORKFLOW.md for the complete CI/CD contract.

API Reference

PurpleAir does not publish an OpenAPI/Swagger spec. This repo reconstructs one at docs/purpleair-openapi.yaml from PurpleAir's apiDoc-generated docs (which serve machine-readable api_data.js), using scripts/generate_openapi.py. The library's endpoint, field, and error-code coverage is validated against this spec.

Regenerate it after an upstream API change:

# Live-fetch https://api.purpleair.com/api_data.js, rebuild and validate the spec
uv run --with pyyaml --with openapi-spec-validator python scripts/generate_openapi.py

The generator takes the API version from the docs' changelog (the apiDoc build-metadata version lags behind), validates the result, and writes docs/purpleair-openapi.yaml. A non-empty diff means the upstream API changed. See AGENTS.md for how the code is validated against the spec.

Contributing

• Branching workflow:
  • The repo uses a two-branch model with ruleset-enforced merge methods.
  • Feature branch -> develop via squash merge (develop is kept linear).
  • develop -> main via merge commit (preserves develop's commit list on main as the second parent of each release commit).
  • Dependabot targets main and develop in parallel via separate PRs and auto-merges every tier once the required check passes.
  • See WORKFLOW.md and AGENTS.md for complete details.
• Code style:
  • See CODESTYLE.md and .editorconfig for Python code style rules. Everything runs through uv run (ruff, mypy, pyright, pytest with 100% coverage and syrupy snapshots).
• Repository setup:
  • See repo-config/README.md for repo configuration details.

Origin

aiopurpleair is an independent, MIT-licensed continuation of the bachya/aiopurpleair PurpleAir API client. Its distinguishing capabilities originated in two upstream contributions that were abandoned after the upstream maintainers became unresponsive:

• A pull request against bachya/aiopurpleair adding the organization endpoint and typed error codes, which was not merged.
• A PurpleAir integration proposed for Home Assistant core as home-assistant/core#140901, now maintained separately as the homeassistant-purpleair HACS custom integration, this library's primary consumer.

The import package name is aiopurpleair; the distribution name ptr727-aiopurpleair keeps it distinct from the canonical aiopurpleair on PyPI. The original MIT copyright is retained alongside the current maintainer's in LICENSE and NOTICE.

License

Licensed under the MIT License

• Original aiopurpleair author: Aaron Bach (@bachya).
• Current maintainer: Pieter Viljoen (@ptr727).