purple_air_api (PAA)

This is a python3 wrapper for the PurpleAirAPI (PAA). Details of the API can be found using this link: https://api.purpleair.com/#api-welcome

To use the PurpleAirAPI (PAA), API keys are required. You can get API keys by sending an email to contact@purpleair.com with a first and last name to assign them to.

How to Support This Project

Purpose

This package is designed to be used for making tools around the PurpleAir API.

For example, PAA data loggers - https://github.com/carlkidcrypto/purpleair_data_logger

Requirements

• Python 3.10 or higher (supports Python 3.10, 3.11, 3.12, 3.13, and 3.14)
• requests library

Installation

You can install the PurpleAir API via pip:

python3 -m pip install purpleair_api

You can also install PurpleAir API by cloning down this repo:

git clone https://github.com/carlkidcrypto/purpleair_api.git
cd purpleair_api
pip install .

PurpleAirAPI Usage Example

First we need to import the PurpleAir API (PAA):

from purpleair_api.PurpleAirAPI import PurpleAirAPI

Next we need to make an instance of PAA:

my_paa = PurpleAirAPI(your_api_read_key, your_api_write_key, [your_ipv4_address])

Now you can use that PAA instance to do things like:

retval = my_paa.request_sensor_data(1234)

Note

PurpleAirAPI is the main entry point. It will load read, write, and local submodules based on the parameters that are passed in upon construction. If you wish to only use a small piece of PurpleAirAPI then see the examples below.

PurpleAirReadAPI Usage Example

First we need to import the PurpleAirReadAPI:

from purpleair_api.PurpleAirReadAPI import PurpleAirReadAPI

Now we need to make an instance of it:

my_paa = PurpleAirReadAPI(api_read_key)

Now we can use that instance to do things like:

retval = my_paa.request_multiple_sensors_data("name")

PurpleAirWriteAPI Usage Example

First we need to import the PurpleAirWriteAPI:

from purpleair_api.PurpleAirWriteAPI import PurpleAirWriteAPI

Now we need to make an instance of it:

my_paa = PurpleAirWriteAPI(api_write_key)

Now we can use that instance to do things like:

retval = my_paa.post_create_member(group_id=1234, sensor_index=5678)

PurpleAirLocalAPI Usage Example

First we need to import the PurpleAirLocalAPI:

from purpleair_api.PurpleAirLocalAPI import PurpleAirLocalAPI

Now we need to make an instance of it:

my_paa = PurpleAirLocalAPI(["ipv4_address"])

Now we can use that instance to do things like:

retval = my_paa.request_local_sensor_data()

Tests

Refer to the test README

Documentation

Full API documentation is available at https://carlkidcrypto.github.io/purpleair_api/

---

This content was generated by AI and reviewed by humans. Mistakes may still occur. PRs for corrections are welcome.

Matter Device Converter (Matter 1.5.1)

Map PurpleAir sensor data to Matter device type structures for use with Matter-compatible ecosystems (Apple Home, Google Home, Alexa, SmartThings, Home Assistant Matter integration).

Supports Matter 1.5.1 Air Quality Sensor (Device Type 0x002D), Temperature Sensor, and Environmental Sensor device types with full EPA AQI calculation.

from purpleair_api.PurpleAirReadAPI import PurpleAirReadAPI
from purpleair_api.PurpleAirMatterConverter import PurpleAirMatterConverter

pa = PurpleAirReadAPI("YOUR_READ_API_KEY")
raw = pa.request_sensor_data(282168)

matter_device = PurpleAirMatterConverter.to_air_quality_sensor(raw)
print(matter_device["air_quality_summary"])
# {'epa_aqi': 68, 'epa_category': 'Moderate',
#  'matter_air_quality_rating': 'GOOD', ...}

See the Matter implementation guide at sphinx_docs_build/source/matter_implementation.rst or docs/html/matter_implementation.html after building, or read the rendered guide online at https://carlkidcrypto.github.io/purpleair_api/matter_implementation.html. The API reference remains available at sphinx_docs_build/source/PurpleAirMatterConverter.rst.

References:

• Matter 1.5.1 Core Specification (CSA, 2024) — https://csa-iot.org/developer-resource/specifications/
• Air Quality Measurement Cluster (0x005D) — https://github.com/project-chip/matter
• EPA AQI Calculation — https://www.airnow.gov/sites/default/files/2022-05/AQI-Basics-Calculation.pdf