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

Disclosure: This post contains affiliate links. If you click through and make a purchase, I will earn a commission, at no additional cost to you. Read my full disclosure here.

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.

The World Air Quality Index (WAQI) for Shenzhen
If I were living in Shenzhen, I would want to know the air quality at all times

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:

  - platform: waqi
    token: !secret WAQI_API_TOKEN
      - 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.

Setting up World Air Quality Index (WAQI) in Home Assistant
My nearest air quality monitor

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
    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.

A portrait photo oif Liam Alexander Colman, the author, creator, and owner of Home Assistant Guide wearing a suit.

About Liam Alexander Colman

is an experienced Home Assistant user who has been utilizing the platform for a variety of projects over an extended period. His journey began with a Raspberry Pi, which quickly grew to three Raspberry Pis and eventually a full-fledged server. Liam's current operating system of choice is Unraid, with Home Assistant comfortably running in a Docker container.
With a deep understanding of the intricacies of Home Assistant, Liam has an impressive setup, consisting of various Zigbee devices, and seamless integrations with existing products such as his Android TV box. For those interested in learning more about Liam's experience with Home Assistant, he shares his insights on how he first started using the platform and his subsequent journey.

Leave a comment

Share to...