The airvisual sensor platform queries the AirVisual API for air quality data on the nearest city to a latitude and longitude. The resulting information creates sensors for the Air Quality Index (AQI), the human-friendly air quality level, and the main pollutant of that area. Sensors that conform to either/both the U.S. and Chinese air quality standards can be created.

This platform requires an AirVisual API key, which can be obtained here. Note that the platform was designed using the “Community” package; the “Startup” and “Enterprise” package keys should continue to function, but actual results may vary (or not work at all).

The “Community” API key is limited to 10,000 calls per month. In order to leave a buffer, the airvisual platform queries the API every 10 minutes.

Configuring the Platform

To enable this platform, add the following lines to your configuration.yaml file:

  - platform: airvisual
    api_key: abc123
      - us
      - cn
    latitude: 42.81212
    longitude: 108.12422
    radius: 500

Configuration variables:

  • api_key (Required): your AirVisual API key
  • monitored_conditions (Required): the air quality standard(s) to use (us for U.S., cn for Chinese)
  • latitude (Optional): the latitude to monitor; if excluded, the latitude defined in configuration.yaml will be used
  • longitude (Optional): the longitude to monitor; if excluded, the longitude defined in configuration.yaml will be used
  • radius (Optional): the radius (in meters) around the latitude/longitude to search for the nearest city; defaults to 1000

Sensor Types

When configured, the platform will create three sensors for each configured air quality standard:

Air Quality Index

Description: This sensor displays a numeric air quality index (AQI), a metric for the overall “health” of the air.

Example Sensor Name: sensor.chinese_air_quality_index

Example Sensor Value: 32


AQI Status Description
0 - 50 Good Air quality is considered satisfactory, and air pollution poses little or no risk
51 - 100 Moderate Air quality is acceptable; however, for some pollutants there may be a moderate health concern for a very small number of people who are unusually sensitive to air pollution
101 - 150 Unhealthy for Sensitive Groups Members of sensitive groups may experience health effects. The general public is not likely to be affected
151 - 200 Unhealthy Everyone may begin to experience health effects; members of sensitive groups may experience more serious health effects
201 - 300 Very unhealthy Health warnings of emergency conditions. The entire population is more likely to be affected
301+ Hazardous Health alert: everyone may experience more serious health effects

Air Polution Level

Description: This sensor displays the associated Status (from the above table) for the current AQI.

Sample Sensor Name: sensor.us_air_pollution_level

Example Sensor Value: Moderate

Main Pollutant

Description: This sensor displays the pollutant whose value is currently highest.

Sample Sensor Name: sensor.us_main_pollutant

Example Sensor Value: PM2.5


Pollutant Symbol More Info
Particulate (<= 2.5 μm) PM2.5 EPA: Particulate Matter (PM) Pollution
Particulate (<= 10 μm) PM10 EPA: Particulate Matter (PM) Pollution
Ozone O EPA: Ozone Pollution
Sulpher Dioxide SO2 EPA: Sulfur Dioxide (SO2) Pollution
Carbon Monoxide CO EPA: Carbon Monoxide (CO) Pollution in Outdoor Air