Package: pyairvisual
☀️ pyairvisual: a thin Python wrapper for the AirVisual© APIpyairvisualis a simple, clean, well-tested library for interacting withAirVisualto retrieve air quality information.Python VersionsInstallationAPI KeyCommunityStartupEnterpriseUsageUsing the Cloud APIWorking with Node/Pro UnitsContributingPython Versionspyairvisualis currently supported on:Python 3.10Python 3.11Python 3.12InstallationpipinstallpyairvisualAPI KeyYou can get an AirVisual API key fromthe AirVisual API site.
Depending on the plan you choose, more functionality will be available from the API:CommunityThe Community Plan gives access to:List supported countriesList supported statesList supported citiesGet data from the nearest city based on IP addressGet data from the nearest city based on latitude/longitudeGet data from a specific cityStartupThe Startup Plan gives access to:List supported stations in a cityGet data from the nearest station based on IP addressGet data from the nearest station based on latitude/longitudeGet data from a specific stationEnterpriseThe Enterprise Plan gives access to:Get a global city ranking of air qualityUsageUsing the Cloud APIimportasynciofrompyairvisual.cloud_apiimportCloudAPIasyncdefmain()->None:"""Run!"""cloud_api=CloudAPI("<YOUR_AIRVISUAL_API_KEY>")# Get data based on the city nearest to your IP address:data=awaitcloud_api.air_quality.nearest_city()# ...or get data based on the city nearest to a latitude/longitude:data=awaitcloud_api.air_quality.nearest_city(latitude=39.742599,longitude=-104.9942557)# ...or get it explicitly:data=awaitcloud_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=awaitcloud_api.air_quality.nearest_station()data=awaitcloud_api.air_quality.nearest_station(latitude=39.742599,longitude=-104.9942557)data=awaitcloud_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=awaitcloud_api.air_quality.ranking()# pyairvisual gives you several methods to look locations up:countries=awaitcloud_api.supported.countries()states=awaitcloud_api.supported.states("USA")cities=awaitcloud_api.supported.cities("USA","Colorado")stations=awaitcloud_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), anaiohttpClientSessioncan be used for
connection pooling:importasynciofromaiohttpimportClientSessionfrompyairvisual.cloud_apiimportCloudAPIasyncdefmain()->None:"""Run!"""asyncwithClientSession()assession:cloud_api=CloudAPI("<YOUR_AIRVISUAL_API_KEY>",session=session)# ...asyncio.run(main())Working with Node/Pro Unitspyairvisualalso allows users to interact withNode/Pro units, both via
the cloud API:importasynciofromaiohttpimportClientSessionfrompyairvisual.cloud_apiimportCloudAPIasyncdefmain()->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=awaitcloud_api.node.get_by_node_id("<NODE_ID>")asyncio.run(main())...or over the local network via Samba (the unit password can be foundon the device itself):importasynciofromaiohttpimportClientSessionfrompyairvisual.nodeimportNodeSambaasyncdefmain()->None:"""Run!"""asyncwithNodeSamba("<IP_ADDRESS_OR_HOST>","<PASSWORD>")asnode:measurements=awaitnode.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=awaitnode.async_get_history()asyncio.run(main())Check out the examples, the tests, and the source files themselves for method
signatures and more examples.ContributingThanks to all ofour contributorsso far!Check for open features/bugsorinitiate 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/activateInstall the dev environment:script/setupCode 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 testsUpdateREADME.mdwith any new documentation.Submit a pull request!