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.

In an era where environmental health is intertwined with our well-being, keeping tabs on the air quality outside our homes has never been more important. For those living in urban areas or near zones prone to wildfires, the air we breathe can significantly impact our health, particularly for individuals with respiratory issues like asthma. While the idea of monitoring this vital environmental parameter might conjure images of complex setups or costly investments in hardware, there's a surprisingly straightforward solution that brings this capability into our homes with minimal fuss. Enter the World Air Quality Index (WAQI) project, a global initiative that offers real-time air quality data from a vast network of sensors. This guide is designed to help you seamlessly integrate WAQI's extensive environmental monitoring services with Home Assistant, providing you with actionable insights right at your fingertips.


Step-by-Step Guide to Integrating WAQI with Home Assistant

The detailed walkthrough below outlines the seamless process of connecting WAQI's comprehensive environmental data with Home Assistant. This step-by-step guide is crafted to ensure that even beginners can successfully enhance their Home Assistant ecosystem with vital air quality information.

Screenshot of Shenzhen's real-time Air Quality Index (AQI) dashboard. A large red box displays an AQI of 163 labelled 'Unhealthy,' updated on Monday at 19:00 with a temperature of 26 °C. Below, a bar graph tracks the past 48 hours of AQI data for PM2.5, PM10, ozone, and other pollutants, with colours grading from green to red based on severity. A map on the right shows various AQI readings across Shenzhen, with numbers in coloured boxes reflecting local AQI levels from green (low) to red (high).

Obtain a WAQI API Token

Your journey begins with acquiring an API token from the World Air Quality Index project. This token is essential for accessing the data from their vast network of air quality sensors. Thankfully, the process is straightforward and only requires your email address and name. Visit the WAQI token page to request your token, which will be sent via email. Once received, add this token to your secrets.yaml file in Home Assistant, labelling it appropriately for easy reference.

Configure the WAQI Sensor in Home Assistant

Integrating the WAQI sensor into your Home Assistant is not yet possible via the dashboard and requires manual addition to the configuration.yaml file. Here's an example configuration that I used:

  - platform: waqi
    token: !secret WAQI_API_TOKEN
      - vaduz

By specifying the city name, Home Assistant creates sensors for all associated stations within that area. For those in regions with multiple sensors, like Vaduz, specifying the exact station name from the WAQI website (e.g., Vaduz Landesbibliothek) can narrow down the data source to your preferred location.

Waqi Home Assistant 01

Making Sense of WAQI Sensor Data

Upon integrating the WAQI sensor and restarting Home Assistant, you'll notice the sensor displays an index value. To make this data more comprehensible, setting up a template sensor that translates these values into actionable insights is advisable. This template can classify the air quality into categories ranging from “Good” to “Hazardous,” based on the AQI value.

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 and states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float <= 100 %}Moderate
      {% elif states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float > 100 and states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float <= 150 %}Unhealthy for Sensitive Groups
      {% elif states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float > 150 and states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float <= 200 %}Unhealthy
      {% elif states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float > 200 and states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float <= 250 %}Very Unhealthy
      {% elif states.sensor.waqi_vaduz_landesbibliothek_switzerland.state | float > 250 %}Hazardous
      {% endif %}

Utilizing WAQI Data for Smart Home Automation

With WAQI data integrated into your Home Assistant, the possibilities for smart home automation are vast. For instance, you could set up notifications to alert you when air quality drops to “Unhealthy” levels, especially if windows are open, or program your voice assistant to provide daily air quality updates. These automations not only enhance convenience but also contribute significantly to your health and well-being.

Waqi Home Assistant 03
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...