Skip to main content

A simple API for AirVisual air quality data

Project description

☀️ pyairvisual: a thin Python wrapper for the AirVisual© API

CI PyPI Version License Code Coverage Maintainability

Buy Me A Coffee

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!

  1. Check for open features/bugs or initiate a discussion on one.
  2. Fork the repository.
  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!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyairvisual-2023.12.0.tar.gz (14.1 kB view details)

Uploaded Source

Built Distribution

pyairvisual-2023.12.0-py3-none-any.whl (13.4 kB view details)

Uploaded Python 3

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

Hashes for pyairvisual-2023.12.0.tar.gz
Algorithm Hash digest
SHA256 bc668bf037f414821f216d888c81ea9e8f92f7574e340ef2509102357f3153fd
MD5 0b0d66dd1b555b4e76c35c0093cfa330
BLAKE2b-256 b2cbb600aa67910fa43bf530d4b503c731ca595ba2a0d31423dddaf3bf64dc95

See more details on using hashes here.

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

Hashes for pyairvisual-2023.12.0-py3-none-any.whl
Algorithm Hash digest
SHA256 ebdfe5ddeb65a853914a2f2e7febabc84d04fdf9346710cb2a6fcac8421f2b9b
MD5 ef97e67560ec3b9b25e96725534a9905
BLAKE2b-256 edd9b0ce00d7f266f25c3df0729f764aef2d9cd67bba8c7231e5b139a758e7c5

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page