Metadata-Version: 2.4
Name: purpleair_api
Version: 1.5.0a1
Home-page: https://github.com/carlkidcrypto/purpleair_api
Author: Carlos Santos
Author-email: dose.lucky.sake@cloak.id
License: MIT
Keywords: purpleair_api,purple air api,purple_air,purple air,purpleair_sensor,purpleair sensor,purpleair-sensor,air quality,aqi,air quality index,air pollution,air quality monitoring,environmental monitoring,sensor data,air quality sensor,iot,api wrapper,environmental data,pollution monitoring,pm2.5,particulate matter
Platform: Windows 32/64
Platform: Linux 32/64
Platform: MacOS 32/64
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

purple_air_api (PAA)
====================

This is a python3 wrapper for the new 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.

.. image:: https://github.com/carlkidcrypto/purpleair_api/actions/workflows/build_and_publish_to_pypi.yml/badge.svg
   :target: https://github.com/carlkidcrypto/purpleair_api/actions/workflows/build_and_publish_to_pypi.yml
   :alt: PyPI Distributions

.. image:: https://github.com/carlkidcrypto/purpleair_api/actions/workflows/build_and_publish_to_test_pypi.yml/badge.svg
   :target: https://github.com/carlkidcrypto/purpleair_api/actions/workflows/build_and_publish_to_test_pypi.yml
   :alt: TestPyPI Distributions

.. image:: https://github.com/carlkidcrypto/purpleair_api/actions/workflows/black.yml/badge.svg
   :target: https://github.com/carlkidcrypto/purpleair_api/actions/workflows/black.yml
   :alt: Black

.. image:: https://github.com/carlkidcrypto/purpleair_api/actions/workflows/tests.yml/badge.svg?branch=main
   :target: https://github.com/carlkidcrypto/purpleair_api/actions/workflows/tests.yml
   :alt: Tests

.. image:: https://img.shields.io/github/downloads/carlkidcrypto/purpleair_api/total.svg?style=flat-square&label=all%20downloads
   :target: https://github.com/carlkidcrypto/purpleair_api/releases
   :alt: Total download count

.. image:: https://img.shields.io/github/downloads/carlkidcrypto/purpleair_api/v1.5.0a1/total.svg?style=flat-square
   :target: https://github.com/carlkidcrypto/purpleair_api/releases/tag/v1.5.0a1
   :alt: Latest release download count

How to Support This Project
----------------------------

.. image:: https://cdn.buymeacoffee.com/buttons/default-orange.png
   :target: https://www.buymeacoffee.com/carlkidcrypto
   :alt: Buy Me A Coffee
   :height: 41
   :width: 174

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:

.. code-block:: bash

   python3 -m pip install purple_air_api

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

.. code-block:: bash

   git clone https://github.com/carlkidcrypto/purpleair_api.git
   cd purpleair_api
   python3 setup.py install

PurpleAirAPI Usage Example
---------------------------

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

.. code-block:: python

   from purpleair_api.PurpleAirAPI import PurpleAirAPI

Next we need to make an instance of PAA:

.. code-block:: python

   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:

.. code-block:: python

   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:

.. code-block:: python

   from purpleair_api.PurpleAirReadAPI import PurpleAirReadAPI

Now we need to make an instance of it:

.. code-block:: python

   my_paa = PurpleAirReadAPI(api_read_key)

Now we can use that instance to do things like:

.. code-block:: python

   retval = my_paa.request_multiple_sensors_data("name")

PurpleAirWriteAPI Usage Example
--------------------------------

First we need to import the PurpleAirWriteAPI:

.. code-block:: python

   from purpleair_api.PurpleAirWriteAPI import PurpleAirWriteAPI

Now we need to make an instance of it:

.. code-block:: python

   my_paa = PurpleAirWriteAPI(api_write_key)

Now we can use that instance to do things like:

.. code-block:: python

   retval = my_paa.post_create_member(1234)

PurpleAirLocalAPI Usage Example
--------------------------------

First we need to import the PurpleAirLocalAPI:

.. code-block:: python

   from purpleair_api.PurpleAirLocalAPI import PurpleAirLocalAPI

Now we need to make an instance of it:

.. code-block:: python

   my_paa = PurpleAirLocalAPI(["ipv4_address"])

Now we can use that instance to do things like:

.. code-block:: python

   retval = my_paa.request_local_sensor_data()

Tests
-----

Refer to the test `README <tests/README.rst>`_

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.

.. code-block:: python

   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 full documentation at ``sphinx_docs_build/source/matter.rst`` or
``docs/matter.html`` after building.

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
