Package: aiopurpleair
🟣 aiopurpleair: A Python3, asyncio-based library to interact with the PurpleAir APIaiopurpleairis a Python3, asyncio-based library to interact with thePurpleAirAPI.InstallationPython VersionsUsageChecking an API KeyGetting SensorsGetting a Single SensorGetting Nearby SensorsGetting a Map URLConnection PoolingContributingInstallationpipinstallaiopurpleairPython Versionsaiopurpleairis currently supported on:Python 3.10Python 3.11Python 3.12UsageIn-depth documentation on the API can be foundhere. Unless otherwise
noted,aiopurpleairendeavors to follow the API as closely as possible.Checking an API KeyTo check whether an API key is valid and what properties it has:importasynciofromaiopurpleairimportAPIasyncdefmain()->None:"""Run."""api=API("<API KEY>")response=awaitapi.async_check_api_key()# >>> response.api_key_type == ApiKeyType.READ# >>> response.api_version == "V1.0.11-0.0.41"# >>> response.timestamp_utc == datetime(2022, 10, 27, 18, 25, 41)asyncio.run(main())Getting SensorsimportasynciofromaiopurpleairimportAPIasyncdefmain()->None:"""Run."""api=API("<API_KEY>")response=awaitapi.sensors.async_get_sensors(["name"])# >>> response.api_version == "V1.0.11-0.0.41"# >>> response.data == {# >>>     131075: SensorModel(sensor_index=131075, name=Mariners Bluff),# >>>     131079: SensorModel(sensor_index=131079, name=BRSKBV-outside),# >>> }# >>> response.data_timestamp_utc == datetime(2022, 11, 3, 19, 25, 31)# >>> response.fields == ["sensor_index", "name"]# >>> response.firmware_default_version == "7.02"# >>> response.max_age == 604800# >>> response.timestamp_utc == datetime(2022, 11, 3, 19, 26, 29)asyncio.run(main())Method Parametersfields(required): The sensor data fields to includelocation_type(optional): An LocationType to filter bymax_age(optional): Filter results modified within these secondsmodified_since(optional): Filter results modified since a UTC datetimeread_keys(optional): Read keys for private sensorssensor_indices(optional): Filter results by sensor indexGetting a Single SensorimportasynciofromaiopurpleairimportAPIasyncdefmain()->None:"""Run."""api=API("<API_KEY>")response=awaitapi.sensors.async_get_sensor(131075)# >>> response.api_version == "V1.0.11-0.0.41"# >>> response.data_timestamp_utc == datetime(2022, 11, 5, 16, 36, 21)# >>> response.sensor == SensorModel(sensor_index=131075, ...),# >>> response.timestamp_utc == datetime(2022, 11, 5, 16, 37, 3)asyncio.run(main())Method Parameterssensor_index(required): The sensor index of the sensor to retrieve.fields(optional): The sensor data fields to include.read_key(optional): A read key for a private sensor.Getting Nearby SensorsThis method returns a list ofNearbySensorResultobjects that are within a bounding box
around a given latitude/longitude pair. The list is sorted from nearest to furthest
(i.e., the first index in the list is the closest to the latitude/longitude).NearbySensorResultobjects have two properties:sensor: the correspondingSensorModelobjectdistance: the calculated distance (in kilometers) between this sensor and the provided
latitude/longitudeimportasynciofromaiopurpleairimportAPIasyncdefmain()->None:"""Run."""api=API("<API_KEY>")sensors=awaitapi.sensors.async_get_nearby_sensors(["name"],51.5285582,-0.2416796,10)# >>> [NearbySensorResult(...), NearbySensorResult(...)]asyncio.run(main())Method Parametersfields(required): The sensor data fields to includelatitude(required): The latitude of the point to measure distance fromlongitude(required): The longitude of the point to measure distance fromdistance(required): The distance from the measured point to search (in kilometers)limit(optional): Limit the resultsGetting a Map URLIf you need to get the URL to a particular sensor index on the PurpleAir map website,
simply pass the appropriate sensor index to theget_map_urlmethod:importasynciofromaiopurpleairimportAPIasyncdefmain()->None:"""Run."""api=API("<API_KEY>")map_url=api.get_map_url(12345)# >>> https://map.purpleair.com/1/mAQI/a10/p604800/cC0?select=12345asyncio.run(main())Connection PoolingBy default, the library creates a new connection to the PurpleAir API with each
coroutine. If you are calling a large number of coroutines (or merely want to squeeze
out every second of runtime savings possible), anaiohttpClientSessioncan
be used for connection pooling:importasynciofromaiohttpimportClientSessionfromaiopurpleairimportAPIasyncdefmain()->None:"""Run."""asyncwithClientSession()assession:api=awaitAPI("<API KEY>")# Get to work...asyncio.run(main())ContributingThanks to all ofour contributorsso far!Check for open features/bugsorinitiate a discussion on one.Fork the repository.(optional, but highly recommended) Create a virtual environment:python3 -m venv .venv(optional, but highly recommended) Enter the virtual environment:source ./.venv/bin/activateInstall the dev environment:script/setupCode your new feature or bug fix on a new branch.Write tests that cover your new functionality.Run tests and ensure 100% code coverage:poetry run pytest --cov aiopurpleair testsUpdateREADME.mdwith any new documentation.Submit a pull request!