# 🟣 aiopurpleair: A Python3, asyncio-based library to interact with the PurpleAir API
[![CI][ci-badge]][ci]
[![PyPI][pypi-badge]][pypi]
[![Version][version-badge]][version]
[![License][license-badge]][license]
[![Code Coverage][codecov-badge]][codecov]
[![Maintainability][maintainability-badge]][maintainability]
<a href="https://www.buymeacoffee.com/bachya1208P" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
`aiopurpleair` is a Python3, asyncio-based library to interact with the
[PurpleAir](https://www2.purpleair.com/) API.
- [Installation](#installation)
- [Python Versions](#python-versions)
- [Usage](#usage)
- [Checking an API Key](#checking-an-api-key)
- [Getting Sensors](#getting-sensors)
- [Getting a Single Sensor](#getting-a-single-sensor)
- [Getting Nearby Sensors](#getting-nearby-sensors)
- [Getting a Map URL](#getting-a-map-url)
- [Connection Pooling](#connection-pooling)
- [Contributing](#contributing)
# Installation
```bash
pip install aiopurpleair
```
# Python Versions
`aiopurpleair` is currently supported on:
- Python 3.10
- Python 3.11
- Python 3.12
# Usage
In-depth documentation on the API can be found [here][purpleair-api]. Unless otherwise
noted, `aiopurpleair` endeavors to follow the API as closely as possible.
## Checking an API Key
To check whether an API key is valid and what properties it has:
```python
import asyncio
from aiopurpleair import API
async def main() -> None:
"""Run."""
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"
# >>> response.timestamp_utc == datetime(2022, 10, 27, 18, 25, 41)
asyncio.run(main())
```
## Getting Sensors
```python
import asyncio
from aiopurpleair import API
async def main() -> None:
"""Run."""
api = API("<API_KEY>")
response = await api.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 Parameters
- `fields` (required): The sensor data fields to include
- `location_type` (optional): An LocationType to filter by
- `max_age` (optional): Filter results modified within these seconds
- `modified_since` (optional): Filter results modified since a UTC datetime
- `read_keys` (optional): Read keys for private sensors
- `sensor_indices` (optional): Filter results by sensor index
## Getting a Single Sensor
```python
import asyncio
from aiopurpleair import API
async def main() -> None:
"""Run."""
api = API("<API_KEY>")
response = await api.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 Parameters
- `sensor_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 Sensors
This method returns a list of `NearbySensorResult` objects 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).
`NearbySensorResult` objects have two properties:
- `sensor`: the corresponding `SensorModel` object
- `distance`: the calculated distance (in kilometers) between this sensor and the provided
latitude/longitude
```python
import asyncio
from aiopurpleair import API
async def main() -> None:
"""Run."""
api = API("<API_KEY>")
sensors = await api.sensors.async_get_nearby_sensors(
["name"], 51.5285582, -0.2416796, 10
)
# >>> [NearbySensorResult(...), NearbySensorResult(...)]
asyncio.run(main())
```
### Method Parameters
- `fields` (required): The sensor data fields to include
- `latitude` (required): The latitude of the point to measure distance from
- `longitude` (required): The longitude of the point to measure distance from
- `distance` (required): The distance from the measured point to search (in kilometers)
- `limit` (optional): Limit the results
## Getting a Map URL
If you need to get the URL to a particular sensor index on the PurpleAir map website,
simply pass the appropriate sensor index to the `get_map_url` method:
```python
import asyncio
from aiopurpleair import API
async def main() -> None:
"""Run."""
api = API("<API_KEY>")
map_url = api.get_map_url(12345)
# >>> https://map.purpleair.com/1/mAQI/a10/p604800/cC0?select=12345
asyncio.run(main())
```
## Connection Pooling
By 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), an [`aiohttp`][aiohttp] `ClientSession` can
be used for connection pooling:
```python
import asyncio
from aiohttp import ClientSession
from aiopurpleair import API
async def main() -> None:
"""Run."""
async with ClientSession() as session:
api = await API("<API KEY>")
# Get to work...
asyncio.run(main())
```
# Contributing
Thanks to all of [our contributors][contributors] so far!
1. [Check for open features/bugs][issues] or [initiate a discussion on one][new-issue].
2. [Fork the repository][fork].
3. (_optional, but highly recommended_) Create a virtual environment: `python3 -m venv .venv`
4. (_optional, but highly recommended_) Enter the virtual environment: `source ./.venv/bin/activate`
5. Install the dev environment: `script/setup`
6. Code your new feature or bug fix on a new branch.
7. Write tests that cover your new functionality.
8. Run tests and ensure 100% code coverage: `poetry run pytest --cov aiopurpleair tests`
9. Update `README.md` with any new documentation.
10. Submit a pull request!
[aiohttp]: https://github.com/aio-libs/aiohttp
[ci-badge]: https://github.com/bachya/aiopurpleair/workflows/CI/badge.svg
[ci]: https://github.com/bachya/aiopurpleair/actions
[codecov-badge]: https://codecov.io/gh/bachya/aiopurpleair/branch/dev/graph/badge.svg
[codecov]: https://codecov.io/gh/bachya/aiopurpleair
[contributors]: https://github.com/bachya/aiopurpleair/graphs/contributors
[fork]: https://github.com/bachya/aiopurpleair/fork
[issues]: https://github.com/bachya/aiopurpleair/issues
[license-badge]: https://img.shields.io/pypi/l/aiopurpleair.svg
[license]: https://github.com/bachya/aiopurpleair/blob/main/LICENSE
[maintainability-badge]: https://api.codeclimate.com/v1/badges/40e0f45570a0eb9aab24/maintainability
[maintainability]: https://codeclimate.com/github/bachya/aiopurpleair/maintainability
[new-issue]: https://github.com/bachya/aiopurpleair/issues/new
[new-issue]: https://github.com/bachya/aiopurpleair/issues/new
[notion]: https://getnotion.com
[purpleair-api]: https://api.purpleair.com/#api-welcome
[purpleair]: https://www2.purpleair.com/
[pypi-badge]: https://img.shields.io/pypi/v/aiopurpleair.svg
[pypi]: https://pypi.python.org/pypi/aiopurpleair
[version-badge]: https://img.shields.io/pypi/pyversions/aiopurpleair.svg
[version]: https://pypi.python.org/pypi/aiopurpleair
Raw data
{
"_id": null,
"home_page": "https://github.com/bachya/aiopurpleair",
"name": "aiopurpleair",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Aaron Bach",
"author_email": "bachya1208@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6a/22/854663b08e33a1e713d669f6e541e1ee72fb232ffd4fdfb8f69ee6af1b71/aiopurpleair-2023.12.0.tar.gz",
"platform": null,
"description": "# \ud83d\udfe3 aiopurpleair: A Python3, asyncio-based library to interact with the PurpleAir API\n\n[![CI][ci-badge]][ci]\n[![PyPI][pypi-badge]][pypi]\n[![Version][version-badge]][version]\n[![License][license-badge]][license]\n[![Code Coverage][codecov-badge]][codecov]\n[![Maintainability][maintainability-badge]][maintainability]\n\n<a href=\"https://www.buymeacoffee.com/bachya1208P\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"41\" width=\"174\"></a>\n\n`aiopurpleair` is a Python3, asyncio-based library to interact with the\n[PurpleAir](https://www2.purpleair.com/) API.\n\n- [Installation](#installation)\n- [Python Versions](#python-versions)\n- [Usage](#usage)\n - [Checking an API Key](#checking-an-api-key)\n - [Getting Sensors](#getting-sensors)\n - [Getting a Single Sensor](#getting-a-single-sensor)\n - [Getting Nearby Sensors](#getting-nearby-sensors)\n - [Getting a Map URL](#getting-a-map-url)\n - [Connection Pooling](#connection-pooling)\n- [Contributing](#contributing)\n\n# Installation\n\n```bash\npip install aiopurpleair\n```\n\n# Python Versions\n\n`aiopurpleair` is currently supported on:\n\n- Python 3.10\n- Python 3.11\n- Python 3.12\n\n# Usage\n\nIn-depth documentation on the API can be found [here][purpleair-api]. Unless otherwise\nnoted, `aiopurpleair` endeavors to follow the API as closely as possible.\n\n## Checking an API Key\n\nTo check whether an API key is valid and what properties it has:\n\n```python\nimport asyncio\n\nfrom aiopurpleair import API\n\n\nasync def main() -> None:\n \"\"\"Run.\"\"\"\n api = API(\"<API KEY>\")\n response = await api.async_check_api_key()\n # >>> response.api_key_type == ApiKeyType.READ\n # >>> response.api_version == \"V1.0.11-0.0.41\"\n # >>> response.timestamp_utc == datetime(2022, 10, 27, 18, 25, 41)\n\n\nasyncio.run(main())\n```\n\n## Getting Sensors\n\n```python\nimport asyncio\n\nfrom aiopurpleair import API\n\n\nasync def main() -> None:\n \"\"\"Run.\"\"\"\n api = API(\"<API_KEY>\")\n response = await api.sensors.async_get_sensors([\"name\"])\n # >>> response.api_version == \"V1.0.11-0.0.41\"\n # >>> response.data == {\n # >>> 131075: SensorModel(sensor_index=131075, name=Mariners Bluff),\n # >>> 131079: SensorModel(sensor_index=131079, name=BRSKBV-outside),\n # >>> }\n # >>> response.data_timestamp_utc == datetime(2022, 11, 3, 19, 25, 31)\n # >>> response.fields == [\"sensor_index\", \"name\"]\n # >>> response.firmware_default_version == \"7.02\"\n # >>> response.max_age == 604800\n # >>> response.timestamp_utc == datetime(2022, 11, 3, 19, 26, 29)\n\n\nasyncio.run(main())\n```\n\n### Method Parameters\n\n- `fields` (required): The sensor data fields to include\n- `location_type` (optional): An LocationType to filter by\n- `max_age` (optional): Filter results modified within these seconds\n- `modified_since` (optional): Filter results modified since a UTC datetime\n- `read_keys` (optional): Read keys for private sensors\n- `sensor_indices` (optional): Filter results by sensor index\n\n## Getting a Single Sensor\n\n```python\nimport asyncio\n\nfrom aiopurpleair import API\n\n\nasync def main() -> None:\n \"\"\"Run.\"\"\"\n api = API(\"<API_KEY>\")\n response = await api.sensors.async_get_sensor(131075)\n # >>> response.api_version == \"V1.0.11-0.0.41\"\n # >>> response.data_timestamp_utc == datetime(2022, 11, 5, 16, 36, 21)\n # >>> response.sensor == SensorModel(sensor_index=131075, ...),\n # >>> response.timestamp_utc == datetime(2022, 11, 5, 16, 37, 3)\n\n\nasyncio.run(main())\n```\n\n### Method Parameters\n\n- `sensor_index` (required): The sensor index of the sensor to retrieve.\n- `fields` (optional): The sensor data fields to include.\n- `read_key` (optional): A read key for a private sensor.\n\n## Getting Nearby Sensors\n\nThis method returns a list of `NearbySensorResult` objects that are within a bounding box\naround a given latitude/longitude pair. The list is sorted from nearest to furthest\n(i.e., the first index in the list is the closest to the latitude/longitude).\n\n`NearbySensorResult` objects have two properties:\n\n- `sensor`: the corresponding `SensorModel` object\n- `distance`: the calculated distance (in kilometers) between this sensor and the provided\n latitude/longitude\n\n```python\nimport asyncio\n\nfrom aiopurpleair import API\n\n\nasync def main() -> None:\n \"\"\"Run.\"\"\"\n api = API(\"<API_KEY>\")\n sensors = await api.sensors.async_get_nearby_sensors(\n [\"name\"], 51.5285582, -0.2416796, 10\n )\n # >>> [NearbySensorResult(...), NearbySensorResult(...)]\n\n\nasyncio.run(main())\n```\n\n### Method Parameters\n\n- `fields` (required): The sensor data fields to include\n- `latitude` (required): The latitude of the point to measure distance from\n- `longitude` (required): The longitude of the point to measure distance from\n- `distance` (required): The distance from the measured point to search (in kilometers)\n- `limit` (optional): Limit the results\n\n## Getting a Map URL\n\nIf you need to get the URL to a particular sensor index on the PurpleAir map website,\nsimply pass the appropriate sensor index to the `get_map_url` method:\n\n```python\nimport asyncio\n\nfrom aiopurpleair import API\n\n\nasync def main() -> None:\n \"\"\"Run.\"\"\"\n api = API(\"<API_KEY>\")\n map_url = api.get_map_url(12345)\n # >>> https://map.purpleair.com/1/mAQI/a10/p604800/cC0?select=12345\n\n\nasyncio.run(main())\n```\n\n## Connection Pooling\n\nBy default, the library creates a new connection to the PurpleAir API with each\ncoroutine. If you are calling a large number of coroutines (or merely want to squeeze\nout every second of runtime savings possible), an [`aiohttp`][aiohttp] `ClientSession` can\nbe used for connection pooling:\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom aiopurpleair import API\n\n\nasync def main() -> None:\n \"\"\"Run.\"\"\"\n async with ClientSession() as session:\n api = await API(\"<API KEY>\")\n\n # Get to work...\n\n\nasyncio.run(main())\n```\n\n# Contributing\n\nThanks to all of [our contributors][contributors] so far!\n\n1. [Check for open features/bugs][issues] or [initiate a discussion on one][new-issue].\n2. [Fork the repository][fork].\n3. (_optional, but highly recommended_) Create a virtual environment: `python3 -m venv .venv`\n4. (_optional, but highly recommended_) Enter the virtual environment: `source ./.venv/bin/activate`\n5. Install the dev environment: `script/setup`\n6. Code your new feature or bug fix on a new branch.\n7. Write tests that cover your new functionality.\n8. Run tests and ensure 100% code coverage: `poetry run pytest --cov aiopurpleair tests`\n9. Update `README.md` with any new documentation.\n10. Submit a pull request!\n\n[aiohttp]: https://github.com/aio-libs/aiohttp\n[ci-badge]: https://github.com/bachya/aiopurpleair/workflows/CI/badge.svg\n[ci]: https://github.com/bachya/aiopurpleair/actions\n[codecov-badge]: https://codecov.io/gh/bachya/aiopurpleair/branch/dev/graph/badge.svg\n[codecov]: https://codecov.io/gh/bachya/aiopurpleair\n[contributors]: https://github.com/bachya/aiopurpleair/graphs/contributors\n[fork]: https://github.com/bachya/aiopurpleair/fork\n[issues]: https://github.com/bachya/aiopurpleair/issues\n[license-badge]: https://img.shields.io/pypi/l/aiopurpleair.svg\n[license]: https://github.com/bachya/aiopurpleair/blob/main/LICENSE\n[maintainability-badge]: https://api.codeclimate.com/v1/badges/40e0f45570a0eb9aab24/maintainability\n[maintainability]: https://codeclimate.com/github/bachya/aiopurpleair/maintainability\n[new-issue]: https://github.com/bachya/aiopurpleair/issues/new\n[new-issue]: https://github.com/bachya/aiopurpleair/issues/new\n[notion]: https://getnotion.com\n[purpleair-api]: https://api.purpleair.com/#api-welcome\n[purpleair]: https://www2.purpleair.com/\n[pypi-badge]: https://img.shields.io/pypi/v/aiopurpleair.svg\n[pypi]: https://pypi.python.org/pypi/aiopurpleair\n[version-badge]: https://img.shields.io/pypi/pyversions/aiopurpleair.svg\n[version]: https://pypi.python.org/pypi/aiopurpleair\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python 3, asyncio-based library to interact with the PurpleAir API",
"version": "2023.12.0",
"project_urls": {
"Bug Tracker": "https://github.com/bachya/aiopurpleair/issues",
"Changelog": "https://github.com/bachya/aiopurpleair/releases",
"Homepage": "https://github.com/bachya/aiopurpleair",
"Repository": "https://github.com/bachya/aiopurpleair"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7abf839ab7a1280d0288be1dce968a448d517f1a5be6078099646c7c391d951e",
"md5": "874480ba4979aac068cc53821f9df769",
"sha256": "532ed293444e89d16ca612bbb9186bc1e6d97a85b0503125220a28d04774ea0a"
},
"downloads": -1,
"filename": "aiopurpleair-2023.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "874480ba4979aac068cc53821f9df769",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 19342,
"upload_time": "2023-12-18T02:54:04",
"upload_time_iso_8601": "2023-12-18T02:54:04.333520Z",
"url": "https://files.pythonhosted.org/packages/7a/bf/839ab7a1280d0288be1dce968a448d517f1a5be6078099646c7c391d951e/aiopurpleair-2023.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6a22854663b08e33a1e713d669f6e541e1ee72fb232ffd4fdfb8f69ee6af1b71",
"md5": "4ec22629651ebd5792fbf7d76ab22085",
"sha256": "2598d53b78fc5582b5ca1ca463d5277fe303075f6758329b37b98447fc2b9f89"
},
"downloads": -1,
"filename": "aiopurpleair-2023.12.0.tar.gz",
"has_sig": false,
"md5_digest": "4ec22629651ebd5792fbf7d76ab22085",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 17330,
"upload_time": "2023-12-18T02:54:06",
"upload_time_iso_8601": "2023-12-18T02:54:06.058168Z",
"url": "https://files.pythonhosted.org/packages/6a/22/854663b08e33a1e713d669f6e541e1ee72fb232ffd4fdfb8f69ee6af1b71/aiopurpleair-2023.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-18 02:54:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bachya",
"github_project": "aiopurpleair",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aiopurpleair"
}
JSON
