pyairvisual 4.3.0

A simple API for AirVisual air quality data

☀️ 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 asyncio
• 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.

Python Versions

pyairvisual is currently supported on:

• Python 3.6
• Python 3.7
• Python 3.8

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

pyairvisual starts within an aiohttp ClientSession:

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())

Using the Cloud API

Getting data from the AirVisual Cloud API is easy:

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:
        # If an API key isn't provided, only Nodes can be queried; everything else
        # requires an API key:
        client = Client(websession, api_key="<YOUR_AIRVISUAL_API_KEY>")

        # 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()

        # 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())

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 import Client


async def main() -> None:
    """Create the aiohttp session and run the example."""
    async with ClientSession() as websession:
        client = Client(websession)

        # The Node/Pro unit ID can be retrieved from the "API" section of the cloud
        # dashboard:
        data = await client.node.from_cloud_api("<NODE_ID>")


asyncio.get_event_loop().run_until_complete(main())

...or over the local network (the unit password can be found on the device itself):

import asyncio

from aiohttp import ClientSession

from pyairvisual import Client
from pyairvisual.node import NodeSamba


async def main() -> None:
    """Create the aiohttp session and run the example."""
    async with ClientSession() as websession:
        client = Client(websession)

        # Can take several optional parameters:
        #   1. include_history: include historical measurements (defaults to True)
        #   2. include_trends: include trends (defaults to True)
        #   3. measurements_to_use: the number of measurements to use when calculating
        #      trends (defaults to -1, which means "use all measurements")
        data = await client.node.from_samba(
            "<IP_ADDRESS_OR_HOST>",
            "<PASSWORD>",
            include_history=True,
            include_trends=True,
            measurements_to_use=10,
        )


asyncio.get_event_loop().run_until_complete(main())

Check out the examples, the tests, and the source files themselves for method signatures and more examples.

Contributing

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.
7. Write tests that cover your new functionality.
8. Run tests and ensure 100% code coverage: script/test
9. Update README.md with any new documentation.
10. Add yourself to AUTHORS.md.
11. Submit a pull request!