Monitor the outdoor air quality using the WAQI integration with Home Assistant

Keeping an eye on the Air Quality Index (AQI) can be important depending on where you are located. Pollution caused by transport and industry and smoke from forest fires can be very unhealthy for your lungs (especially if you're an asthmatic like me!). You could buy an off-the-shelf air quality sensor for outdoor use or build your own sensor using ESPHome, but both of those options cost money and take some time to get set up.

Luckily, though, there might already be a sensor located close to where I live provided by the World Air Quality Index (WAQI) project you can access using Home Assistant. For me personally, the closest sensor is located within 5 km. This guide will show you how you can add the outdoor air quality to your Home Assistant using the WAQI integration.

Obtaining a World Air Quality Index (WAQI) API token

The first step of settings up the World Air Quality Index (WAQI) integration is obtaining an API token. You don't have to register, they just require your email address and name. Your code will then be sent to you. Once your code arrives you can save it to your secrets.yaml file with a fitting description.

Setting up the World Air Quality Index (WAQI) sensor

Integrating the World Air Quality Index (WAQI) hasn't yet been moved to the dashboard, and the sensor will have to be added into the configuration.yaml file. The following is my setup:

sensor:
  - platform: waqi
    token: !secret WAQI_API_TOKEN
    locations:
      - vaduz

Entering just the name of a city will create a sensor for all associated stations in the area. For my setup, that isn't an issue, as there is only one sensor in Vaduz. If you only want to import the data for one specific World Air Quality Index (WAQI) location, you can enter the exact name found on their website. In my case, the exact name of the location would be Vaduz Landesbibliothek.

Interpreting the World Air Quality Index (WAQI) sensor values

Once you have restarted Home Assistant you will notice that the sensor will just display a number which is the value of the index. Unless you know exactly what the values of the index stand for, this WAQI sensor won't be of much use to you.

In order to translate the number into something understandable for humans, you can set up a template sensor. This sensor won't display a value and will instead tell you whether the air quality is good, moderate, unhealthy for sensitive groups, unhealthy, very unhealthy, or hazardous.

platform: template
sensors:
  air_quality_waqi_vaduz:
    friendly_name: Air Quality
    value_template: >-
      {%if states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float<=50 %}Good
      {% elif states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float>50 | float<=100 %}Moderate
      {% elif states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float>100 | float<=150 %}Unhealthy for Sensitive Groups
      {% elif states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float>150 | float<=200 %}Unhealthy
      {% elif states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float>200 | float<=250 %}Very unhealthy
      {% elif states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float>250 | float<=300 %}Hazardous
      {%- endif %}

Using the World Air Quality Index (WAQI) in Home Assistant

There are many things you can do with the World Air Quality Index (WAQI) in Home Assistant. For example, you could have a notification sent to your smartphone whenever the air quality is unhealthy and there are windows open in your home. Or you could have your voice assistant tell the quality when you wake up.