☀️ 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.
PLEASE READ: Version 2.0.0 and Beyond
Version 2.0.0 of
pyairvisual makes several breaking, but necessary changes:
- Moves the underlying library from Requests to aiohttp
- Changes the entire library to use
- Makes 3.6 the minimum version of Python required
If you wish to continue using the previous, synchronous version of
pyairvisual, make sure to pin version 1.0.0.
pyairvisual is currently supported on:
- Python 3.5
- Python 3.6
- Python 3.7
However, running the test suite currently requires Python 3.6 or higher; tests run on Python 3.5 will fail.
pip install pyairvisual
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:
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
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
The Enterprise Plan gives access to:
- Get a global city ranking of air quality
pyairvisual starts within an
import asyncio from aiohttp import ClientSession from pyairvisual import Client async def main() -> None: """Create the aiohttp session and run the example.""" async with ClientSession() as websession: # YOUR CODE HERE asyncio.get_event_loop().run_until_complete(main())
Create a client and get to work:
import asyncio from aiohttp import ClientSession from pyairvisual import Client async def main() -> None: """Create the aiohttp session and run the example.""" async with ClientSession() as websession: client = Client('<YOUR AIRVISUAL API KEY>', websession) # Get data based on the city nearest to your IP address: data = await client.data.nearest_city() # ...or get data based on the city nearest to a latitude/longitude: data = await client.data.nearest_city( latitude=39.742599, longitude=-104.9942557) # ...or get it explicitly: data = await client.data.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 client.data.nearest_station() data = await client.data.nearest_station( latitude=39.742599, longitude=-104.9942557) data = await client.data.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 client.data.ranking() # Lastly, pyairvisual gives you several methods to look locations up: countries = await client.supported.countries() states = await client.supported.states('USA') cities = await client.supported.cities('USA', 'Colorado') stations = await client.supported.stations('USA', 'Colorado', 'Denver') asyncio.get_event_loop().run_until_complete(main())
example.py, the tests, and the source files themselves for method
signatures and more examples.
- Check for open features/bugs or initiate a discussion on one.
- Fork the repository.
- Install the dev environment:
- Enter the virtual environment:
- Code your new feature or bug fix.
- Write a test that covers your new functionality.
- Run tests and ensure 100% code coverage:
- Add yourself to
- Submit a pull request!