pyairnow is a simple, tested, thin client library for interacting with the
AirNow United States EPA Air Quality Index API.
pyairnow is currently supported and tested on:
- Python 3.8
- Python 3.9
- Python 3.10
- Python 3.11
pip install pyairnowYou can get an AirNow API key from the AirNow API site. Ensure you read and understand the expectations and limitations of API usage, which can be found at the AirNow FAQ.
import asyncio
import datetime
from pyairnow import WebServiceAPI
async def main() -> None:
client = WebServiceAPI('your-api-key')
# Get current observational data based on a zip code
data = await client.observations.zipCode(
'95001',
# if there are no observation stations in this zip code, optionally
# provide a radius to search (in miles)
distance=50,
)
# Get current observational data based on a latitude and longitude
data = await client.observations.latLong(
34.053718, -118.244842,
# if there are no observation stations at this location, optionally
# provide a radius to search (in miles)
distance=50,
)
# Get forecast data based on a zip code
data = await client.forecast.zipCode(
'95001',
# to get a forecast for a certain day, provide a date in yyyy-mm-dd,
# if not specified the current day will be used
date='2020-09-01',
# if there are no observation stations in this zip code, optionally
# provide a radius to search (in miles)
distance=50,
)
# Get forecast data based on a latitude and longitude
data = await client.forecast.latLong(
# Lat/Long may be strings or floats
'34.053718', '-118.244842',
# forecast dates may also be datetime.date or datetime.datetime objects
date=datetime.date(2020, 9, 1),
# if there are no observation stations in this zip code, optionally
# provide a radius to search (in miles)
distance=50,
)
asyncio.run(main())By default, the library creates a new connection to AirNow 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
import datetime
from aiohttp import ClientSession
from pyairnow import WebServiceAPI
async def main() -> None:
async with ClientSession() as session:
client = WebServiceAPI('your-api-key', session=session)
# ...
asyncio.run(main())The library provides two convenience functions to convert between AQI and pollutant concentrations. See this EPA document for more details.
from pyairnow.conv import aqi_to_concentration, concentration_to_aqi
# Supported Pollutants
# --------------------
# Ozone ('O3'): ppm
# pm2.5 ('PM2.5'): ug/m^3
# pm10 ('PM10'): ug/m^3
# Carbon Monoxide ('CO'): ppm
# Sulfur Dioxide ('SO2'): ppm
# Nitrogen Dioxide ('NO2'): ppm
# Returns AQI = 144 for pm2.5 of 53.0 ug/m^3
aqi_to_concentration(144, 'PM2.5')
# Returns Cp = 53.0 ug/m^3
concentration_to_aqi(53.0, 'PM2.5')- Check for open features/bugs or start a discussion on one.
- Fork the repository.
- Install Poetry and set up the development workspace:
poetry install - Code your new feature or bug fix.
- Write tests that cover your new functionality.
- Run tests and ensure 100% code coverage:
make test - Run the linter to ensure 100% code style correctness:
make lint - Update
README.mdwith any new documentation. - Add yourself to
AUTHORS.md. - Submit a pull request!