# ☀️ pyairvisual: a thin Python wrapper for the AirVisual© 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>
`pyairvisual` is a simple, clean, well-tested library for interacting with
[AirVisual][airvisual] to retrieve air quality information.
- [Python Versions](#python-versions)
- [Installation](#installation)
- [API Key](#api-key)
- [Community](#community)
- [Startup](#startup)
- [Enterprise](#enterprise)
- [Usage](#usage)
- [Using the Cloud API](#using-the-cloud-api)
- [Working with Node/Pro Units](#working-with-node-pro-units)
- [Contributing](#contributing)
# Python Versions
`pyairvisual` is currently supported on:
- Python 3.10
- Python 3.11
- Python 3.12
# Installation
```bash
pip install pyairvisual
```
# API Key
You can get an AirVisual API key from [the AirVisual API site][airvisual-api].
Depending on the plan you choose, more functionality will be available from the API:
## Community
The Community Plan gives access to:
- List supported countries
- List supported states
- List supported cities
- Get data from the nearest city based on IP address
- Get data from the nearest city based on latitude/longitude
- Get data from a specific city
## Startup
The Startup Plan gives access to:
- List supported stations in a city
- Get data from the nearest station based on IP address
- Get data from the nearest station based on latitude/longitude
- Get data from a specific station
## Enterprise
The Enterprise Plan gives access to:
- Get a global city ranking of air quality
# Usage
## Using the Cloud API
```python
import asyncio
from pyairvisual.cloud_api import CloudAPI
async def main() -> None:
"""Run!"""
cloud_api = CloudAPI("<YOUR_AIRVISUAL_API_KEY>")
# Get data based on the city nearest to your IP address:
data = await cloud_api.air_quality.nearest_city()
# ...or get data based on the city nearest to a latitude/longitude:
data = await cloud_api.air_quality.nearest_city(
latitude=39.742599, longitude=-104.9942557
)
# ...or get it explicitly:
data = await cloud_api.air_quality.city(
city="Los Angeles", state="California", country="USA"
)
# If you have the appropriate API key, you can also get data based on
# station (nearest or explicit):
data = await cloud_api.air_quality.nearest_station()
data = await cloud_api.air_quality.nearest_station(
latitude=39.742599, longitude=-104.9942557
)
data = await cloud_api.air_quality.station(
station="US Embassy in Beijing",
city="Beijing",
state="Beijing",
country="China",
)
# With the appropriate API key, you can get an air quality ranking:
data = await cloud_api.air_quality.ranking()
# pyairvisual gives you several methods to look locations up:
countries = await cloud_api.supported.countries()
states = await cloud_api.supported.states("USA")
cities = await cloud_api.supported.cities("USA", "Colorado")
stations = await cloud_api.supported.stations("USA", "Colorado", "Denver")
asyncio.run(main())
```
By default, the library creates a new connection to AirVisual 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 pyairvisual.cloud_api import CloudAPI
async def main() -> None:
"""Run!"""
async with ClientSession() as session:
cloud_api = CloudAPI("<YOUR_AIRVISUAL_API_KEY>", session=session)
# ...
asyncio.run(main())
```
## Working with Node/Pro Units
`pyairvisual` also allows users to interact with [Node/Pro units][airvisual-pro], both via
the cloud API:
```python
import asyncio
from aiohttp import ClientSession
from pyairvisual.cloud_api import CloudAPI
async def main() -> None:
"""Run!"""
cloud_api = CloudAPI("<YOUR_AIRVISUAL_API_KEY>")
# The Node/Pro unit ID can be retrieved from the "API" section of the cloud
# dashboard:
data = await cloud_api.node.get_by_node_id("<NODE_ID>")
asyncio.run(main())
```
...or over the local network via Samba (the unit password can be found
[on the device itself][airvisual-samba-instructions]):
```python
import asyncio
from aiohttp import ClientSession
from pyairvisual.node import NodeSamba
async def main() -> None:
"""Run!"""
async with NodeSamba("<IP_ADDRESS_OR_HOST>", "<PASSWORD>") as node:
measurements = await node.async_get_latest_measurements()
# Can take some optional parameters:
# 1. include_trends: include trends (defaults to True)
# 2. measurements_to_use: the number of measurements to use when calculating
# trends (defaults to -1, which means "use all measurements")
history = await node.async_get_history()
asyncio.run(main())
```
Check out the examples, the tests, and the source files themselves for method
signatures and more examples.
# 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 pyairvisual tests`
9. Update `README.md` with any new documentation.
10. Submit a pull request!
[aiohttp]: https://github.com/aio-libs/aiohttp
[airvisual]: https://www.airvisual.com/
[airvisual-api]: https://www.airvisual.com/user/api
[airvisual-pro]: https://www.airvisual.com/air-quality-monitor
[airvisual-samba-instructions]: https://support.airvisual.com/en/articles/3029331-download-the-airvisual-node-pro-s-data-using-samba
[ci-badge]: https://github.com/bachya/pyairvisual/workflows/CI/badge.svg
[ci]: https://github.com/bachya/pyairvisual/actions
[codecov-badge]: https://codecov.io/gh/bachya/pyairvisual/branch/dev/graph/badge.svg
[codecov]: https://codecov.io/gh/bachya/pyairvisual
[contributors]: https://github.com/bachya/pyairvisual/graphs/contributors
[fork]: https://github.com/bachya/pyairvisual/fork
[issues]: https://github.com/bachya/pyairvisual/issues
[license-badge]: https://img.shields.io/pypi/l/pyairvisual.svg
[license]: https://github.com/bachya/pyairvisual/blob/main/LICENSE
[maintainability-badge]: https://api.codeclimate.com/v1/badges/948e4e3c84e5c49826f1/maintainability
[maintainability]: https://codeclimate.com/github/bachya/pyairvisual/maintainability
[new-issue]: https://github.com/bachya/pyairvisual/issues/new
[new-issue]: https://github.com/bachya/pyairvisual/issues/new
[pypi-badge]: https://img.shields.io/pypi/v/pyairvisual.svg
[pypi]: https://pypi.python.org/pypi/pyairvisual
[version-badge]: https://img.shields.io/pypi/pyversions/pyairvisual.svg
[version]: https://pypi.python.org/pypi/pyairvisual
Raw data
{
"_id": null,
"home_page": "https://github.com/bachya/pyairvisual",
"name": "pyairvisual",
"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/b2/cb/b600aa67910fa43bf530d4b503c731ca595ba2a0d31423dddaf3bf64dc95/pyairvisual-2023.12.0.tar.gz",
"platform": null,
"description": "# \u2600\ufe0f pyairvisual: a thin Python wrapper for the AirVisual\u00a9 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`pyairvisual` is a simple, clean, well-tested library for interacting with\n[AirVisual][airvisual] to retrieve air quality information.\n\n- [Python Versions](#python-versions)\n- [Installation](#installation)\n- [API Key](#api-key)\n - [Community](#community)\n - [Startup](#startup)\n - [Enterprise](#enterprise)\n- [Usage](#usage)\n - [Using the Cloud API](#using-the-cloud-api)\n - [Working with Node/Pro Units](#working-with-node-pro-units)\n- [Contributing](#contributing)\n\n# Python Versions\n\n`pyairvisual` is currently supported on:\n\n- Python 3.10\n- Python 3.11\n- Python 3.12\n\n# Installation\n\n```bash\npip install pyairvisual\n```\n\n# API Key\n\nYou can get an AirVisual API key from [the AirVisual API site][airvisual-api].\nDepending on the plan you choose, more functionality will be available from the API:\n\n## Community\n\nThe Community Plan gives access to:\n\n- List supported countries\n- List supported states\n- List supported cities\n- Get data from the nearest city based on IP address\n- Get data from the nearest city based on latitude/longitude\n- Get data from a specific city\n\n## Startup\n\nThe Startup Plan gives access to:\n\n- List supported stations in a city\n- Get data from the nearest station based on IP address\n- Get data from the nearest station based on latitude/longitude\n- Get data from a specific station\n\n## Enterprise\n\nThe Enterprise Plan gives access to:\n\n- Get a global city ranking of air quality\n\n# Usage\n\n## Using the Cloud API\n\n```python\nimport asyncio\n\nfrom pyairvisual.cloud_api import CloudAPI\n\n\nasync def main() -> None:\n \"\"\"Run!\"\"\"\n cloud_api = CloudAPI(\"<YOUR_AIRVISUAL_API_KEY>\")\n\n # Get data based on the city nearest to your IP address:\n data = await cloud_api.air_quality.nearest_city()\n\n # ...or get data based on the city nearest to a latitude/longitude:\n data = await cloud_api.air_quality.nearest_city(\n latitude=39.742599, longitude=-104.9942557\n )\n\n # ...or get it explicitly:\n data = await cloud_api.air_quality.city(\n city=\"Los Angeles\", state=\"California\", country=\"USA\"\n )\n\n # If you have the appropriate API key, you can also get data based on\n # station (nearest or explicit):\n data = await cloud_api.air_quality.nearest_station()\n data = await cloud_api.air_quality.nearest_station(\n latitude=39.742599, longitude=-104.9942557\n )\n data = await cloud_api.air_quality.station(\n station=\"US Embassy in Beijing\",\n city=\"Beijing\",\n state=\"Beijing\",\n country=\"China\",\n )\n\n # With the appropriate API key, you can get an air quality ranking:\n data = await cloud_api.air_quality.ranking()\n\n # pyairvisual gives you several methods to look locations up:\n countries = await cloud_api.supported.countries()\n states = await cloud_api.supported.states(\"USA\")\n cities = await cloud_api.supported.cities(\"USA\", \"Colorado\")\n stations = await cloud_api.supported.stations(\"USA\", \"Colorado\", \"Denver\")\n\n\nasyncio.run(main())\n```\n\nBy default, the library creates a new connection to AirVisual with each coroutine. If\nyou are calling a large number of coroutines (or merely want to squeeze out every second\nof runtime savings possible), an [`aiohttp`][aiohttp] `ClientSession` can be used for\nconnection pooling:\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom pyairvisual.cloud_api import CloudAPI\n\n\nasync def main() -> None:\n \"\"\"Run!\"\"\"\n async with ClientSession() as session:\n cloud_api = CloudAPI(\"<YOUR_AIRVISUAL_API_KEY>\", session=session)\n\n # ...\n\n\nasyncio.run(main())\n```\n\n## Working with Node/Pro Units\n\n`pyairvisual` also allows users to interact with [Node/Pro units][airvisual-pro], both via\nthe cloud API:\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom pyairvisual.cloud_api import CloudAPI\n\n\nasync def main() -> None:\n \"\"\"Run!\"\"\"\n cloud_api = CloudAPI(\"<YOUR_AIRVISUAL_API_KEY>\")\n\n # The Node/Pro unit ID can be retrieved from the \"API\" section of the cloud\n # dashboard:\n data = await cloud_api.node.get_by_node_id(\"<NODE_ID>\")\n\n\nasyncio.run(main())\n```\n\n...or over the local network via Samba (the unit password can be found\n[on the device itself][airvisual-samba-instructions]):\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom pyairvisual.node import NodeSamba\n\n\nasync def main() -> None:\n \"\"\"Run!\"\"\"\n async with NodeSamba(\"<IP_ADDRESS_OR_HOST>\", \"<PASSWORD>\") as node:\n measurements = await node.async_get_latest_measurements()\n\n # Can take some optional parameters:\n # 1. include_trends: include trends (defaults to True)\n # 2. measurements_to_use: the number of measurements to use when calculating\n # trends (defaults to -1, which means \"use all measurements\")\n history = await node.async_get_history()\n\n\nasyncio.run(main())\n```\n\nCheck out the examples, the tests, and the source files themselves for method\nsignatures and more examples.\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 pyairvisual tests`\n9. Update `README.md` with any new documentation.\n10. Submit a pull request!\n\n[aiohttp]: https://github.com/aio-libs/aiohttp\n[airvisual]: https://www.airvisual.com/\n[airvisual-api]: https://www.airvisual.com/user/api\n[airvisual-pro]: https://www.airvisual.com/air-quality-monitor\n[airvisual-samba-instructions]: https://support.airvisual.com/en/articles/3029331-download-the-airvisual-node-pro-s-data-using-samba\n[ci-badge]: https://github.com/bachya/pyairvisual/workflows/CI/badge.svg\n[ci]: https://github.com/bachya/pyairvisual/actions\n[codecov-badge]: https://codecov.io/gh/bachya/pyairvisual/branch/dev/graph/badge.svg\n[codecov]: https://codecov.io/gh/bachya/pyairvisual\n[contributors]: https://github.com/bachya/pyairvisual/graphs/contributors\n[fork]: https://github.com/bachya/pyairvisual/fork\n[issues]: https://github.com/bachya/pyairvisual/issues\n[license-badge]: https://img.shields.io/pypi/l/pyairvisual.svg\n[license]: https://github.com/bachya/pyairvisual/blob/main/LICENSE\n[maintainability-badge]: https://api.codeclimate.com/v1/badges/948e4e3c84e5c49826f1/maintainability\n[maintainability]: https://codeclimate.com/github/bachya/pyairvisual/maintainability\n[new-issue]: https://github.com/bachya/pyairvisual/issues/new\n[new-issue]: https://github.com/bachya/pyairvisual/issues/new\n[pypi-badge]: https://img.shields.io/pypi/v/pyairvisual.svg\n[pypi]: https://pypi.python.org/pypi/pyairvisual\n[version-badge]: https://img.shields.io/pypi/pyversions/pyairvisual.svg\n[version]: https://pypi.python.org/pypi/pyairvisual\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple API for AirVisual air quality data",
"version": "2023.12.0",
"project_urls": {
"Bug Tracker": "https://github.com/bachya/pyairvisual/issues",
"Changelog": "https://github.com/bachya/pyairvisual/releases",
"Homepage": "https://github.com/bachya/pyairvisual",
"Repository": "https://github.com/bachya/pyairvisual"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "edd9b0ce00d7f266f25c3df0729f764aef2d9cd67bba8c7231e5b139a758e7c5",
"md5": "ef97e67560ec3b9b25e96725534a9905",
"sha256": "ebdfe5ddeb65a853914a2f2e7febabc84d04fdf9346710cb2a6fcac8421f2b9b"
},
"downloads": -1,
"filename": "pyairvisual-2023.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ef97e67560ec3b9b25e96725534a9905",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 13407,
"upload_time": "2023-12-18T01:26:27",
"upload_time_iso_8601": "2023-12-18T01:26:27.517229Z",
"url": "https://files.pythonhosted.org/packages/ed/d9/b0ce00d7f266f25c3df0729f764aef2d9cd67bba8c7231e5b139a758e7c5/pyairvisual-2023.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b2cbb600aa67910fa43bf530d4b503c731ca595ba2a0d31423dddaf3bf64dc95",
"md5": "0b0d66dd1b555b4e76c35c0093cfa330",
"sha256": "bc668bf037f414821f216d888c81ea9e8f92f7574e340ef2509102357f3153fd"
},
"downloads": -1,
"filename": "pyairvisual-2023.12.0.tar.gz",
"has_sig": false,
"md5_digest": "0b0d66dd1b555b4e76c35c0093cfa330",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 14102,
"upload_time": "2023-12-18T01:26:29",
"upload_time_iso_8601": "2023-12-18T01:26:29.264482Z",
"url": "https://files.pythonhosted.org/packages/b2/cb/b600aa67910fa43bf530d4b503c731ca595ba2a0d31423dddaf3bf64dc95/pyairvisual-2023.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-18 01:26:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bachya",
"github_project": "pyairvisual",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyairvisual"
}
JSON
