{"id":15722907,"url":"https://github.com/bachya/aiopurpleair","last_synced_at":"2025-05-05T21:29:54.889Z","repository":{"id":62180177,"uuid":"558530092","full_name":"bachya/aiopurpleair","owner":"bachya","description":"🟣 A Python 3, asyncio-based library to interact with the PurpleAir API","archived":false,"fork":false,"pushed_at":"2025-03-27T08:21:29.000Z","size":1274,"stargazers_count":1,"open_issues_count":11,"forks_count":1,"subscribers_count":2,"default_branch":"dev","last_synced_at":"2025-03-30T23:51:09.401Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bachya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-27T18:26:52.000Z","updated_at":"2025-03-11T23:21:09.000Z","dependencies_parsed_at":"2023-02-18T07:46:05.805Z","dependency_job_id":"68ee3a63-2119-43a7-ae53-0fdbec634a90","html_url":"https://github.com/bachya/aiopurpleair","commit_stats":{"total_commits":110,"total_committers":2,"mean_commits":55.0,"dds":0.4727272727272728,"last_synced_commit":"86830ade9ea35315ef51f1592da68cf55862d5f9"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":"bachya/pypi-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Faiopurpleair","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Faiopurpleair/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Faiopurpleair/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Faiopurpleair/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bachya","download_url":"https://codeload.github.com/bachya/aiopurpleair/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252579895,"owners_count":21771238,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T22:09:40.300Z","updated_at":"2025-05-05T21:29:54.868Z","avatar_url":"https://github.com/bachya.png","language":"Python","funding_links":["https://www.buymeacoffee.com/bachya1208P"],"categories":[],"sub_categories":[],"readme":"# 🟣 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\u003ca href=\"https://www.buymeacoffee.com/bachya1208P\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"41\" width=\"174\"\u003e\u003c/a\u003e\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() -\u003e None:\n    \"\"\"Run.\"\"\"\n    api = API(\"\u003cAPI KEY\u003e\")\n    response = await api.async_check_api_key()\n    # \u003e\u003e\u003e response.api_key_type == ApiKeyType.READ\n    # \u003e\u003e\u003e response.api_version == \"V1.0.11-0.0.41\"\n    # \u003e\u003e\u003e 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() -\u003e None:\n    \"\"\"Run.\"\"\"\n    api = API(\"\u003cAPI_KEY\u003e\")\n    response = await api.sensors.async_get_sensors([\"name\"])\n    # \u003e\u003e\u003e response.api_version == \"V1.0.11-0.0.41\"\n    # \u003e\u003e\u003e response.data == {\n    # \u003e\u003e\u003e     131075: SensorModel(sensor_index=131075, name=Mariners Bluff),\n    # \u003e\u003e\u003e     131079: SensorModel(sensor_index=131079, name=BRSKBV-outside),\n    # \u003e\u003e\u003e }\n    # \u003e\u003e\u003e response.data_timestamp_utc == datetime(2022, 11, 3, 19, 25, 31)\n    # \u003e\u003e\u003e response.fields == [\"sensor_index\", \"name\"]\n    # \u003e\u003e\u003e response.firmware_default_version == \"7.02\"\n    # \u003e\u003e\u003e response.max_age == 604800\n    # \u003e\u003e\u003e 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() -\u003e None:\n    \"\"\"Run.\"\"\"\n    api = API(\"\u003cAPI_KEY\u003e\")\n    response = await api.sensors.async_get_sensor(131075)\n    # \u003e\u003e\u003e response.api_version == \"V1.0.11-0.0.41\"\n    # \u003e\u003e\u003e response.data_timestamp_utc == datetime(2022, 11, 5, 16, 36, 21)\n    # \u003e\u003e\u003e response.sensor == SensorModel(sensor_index=131075, ...),\n    # \u003e\u003e\u003e 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() -\u003e None:\n    \"\"\"Run.\"\"\"\n    api = API(\"\u003cAPI_KEY\u003e\")\n    sensors = await api.sensors.async_get_nearby_sensors(\n        [\"name\"], 51.5285582, -0.2416796, 10\n    )\n    # \u003e\u003e\u003e [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() -\u003e None:\n    \"\"\"Run.\"\"\"\n    api = API(\"\u003cAPI_KEY\u003e\")\n    map_url = api.get_map_url(12345)\n    # \u003e\u003e\u003e 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() -\u003e None:\n    \"\"\"Run.\"\"\"\n    async with ClientSession() as session:\n        api = await API(\"\u003cAPI KEY\u003e\")\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://img.shields.io/github/actions/workflow/status/bachya/aiopurpleair/test.yml\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbachya%2Faiopurpleair","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbachya%2Faiopurpleair","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbachya%2Faiopurpleair/lists"}