A simple API for AirVisual air quality data
Project description
☀️ pyairvisual: a thin Python wrapper for the AirVisual© API
pyairvisual
is a simple, clean, well-tested library for interacting with
AirVisual to retrieve air quality information.
Python Versions
pyairvisual
is currently supported on:
- Python 3.10
- Python 3.11
- Python 3.12
Installation
pip install pyairvisual
API Key
You can get an AirVisual API key from the AirVisual API site. 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
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
ClientSession
can be used for
connection pooling:
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, both via
the cloud API:
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):
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 so far!
- Check for open features/bugs or initiate 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/activate
- Install the dev environment:
script/setup
- Code 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 pyairvisual tests
- Update
README.md
with any new documentation. - Submit a pull request!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file pyairvisual-2023.12.0.tar.gz
.
File metadata
- Download URL: pyairvisual-2023.12.0.tar.gz
- Upload date:
- Size: 14.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.7.1 CPython/3.12.1 Linux/6.2.0-1018-azure
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | bc668bf037f414821f216d888c81ea9e8f92f7574e340ef2509102357f3153fd |
|
MD5 | 0b0d66dd1b555b4e76c35c0093cfa330 |
|
BLAKE2b-256 | b2cbb600aa67910fa43bf530d4b503c731ca595ba2a0d31423dddaf3bf64dc95 |
File details
Details for the file pyairvisual-2023.12.0-py3-none-any.whl
.
File metadata
- Download URL: pyairvisual-2023.12.0-py3-none-any.whl
- Upload date:
- Size: 13.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.7.1 CPython/3.12.1 Linux/6.2.0-1018-azure
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | ebdfe5ddeb65a853914a2f2e7febabc84d04fdf9346710cb2a6fcac8421f2b9b |
|
MD5 | ef97e67560ec3b9b25e96725534a9905 |
|
BLAKE2b-256 | edd9b0ce00d7f266f25c3df0729f764aef2d9cd67bba8c7231e5b139a758e7c5 |