Add an air quality indicator AQICN a Home Assistant

4 minutes of reading
Guide purposes
  • Add to the configuration of the profirst home automation on Home Assistant one or more grade sensorsnameatmospheric data starting from the data collected by the stations in the area
  • Difficulty level: bass
Concepts dealt with:
  • Software configuration
Software components used:
Physical devices used:
  • The device on which it resides Home Assistant (must be able to reach the Internet)
GUIDE more indicated for:

All environments

Notes and disclaimer
  • qualsiasi modifica all'impianto elettrico dev'essere progettata ed effettuata da personale qualificato;
  • any changes implemented in probefore is a propersonal responsibility as well as a profirst risk and danger (the contents of the present page are purely educational);
  • any changes implemented in proprior to a device it voids the guarantee, quality approvals and certifications.


Often - especially in the winter season, but not only - we hear about it of degree of inquinamento of our cities, expressing this degree through a series of indicators crucial, such as particle concentration PM 2.5-10, carbon dioxide and sulfur dioxide, and many others.

These indicators, duly assessed, converge towards a single indicator said "Air quality index"Which expresses (through a value to be compared at fixed intervals) the air quality.

To measure these parameters there are control units appdare: we see many, scattered throughout the territory. These control units - managed by private, public and academic bodies - collect this data and, in some cases, they publish them directly on the Internet.

Air quality control unit
A typical air quality control unit

Home Assistant, among its many components, it provides one that allows you to collect this data on the internet (at the site to expose them, such as sensors numerical, within ours personal home automation.

The purposes collecting this information can be multiple: simple curiosity, but also the provision of automations aimed, for example, at activating home automation air purifiers inside the home, close the finestre automatically (if mechanized and placed in home automation) when a certain threshold is exceeded, to send notifications / alarms, etc.

Initial information

Before venturing out in this integration, it is good to check - first of all - that the AQICN website contains the data of the pronear the area, as close as possible to the geographical position by the profirst home automation environment.

Then go to the site and, through the search internal, check that at the proin the area there are one or more control units. For this guide we will take the city of Rome as a reference; in his case, the "form" at AQICN will be similar to the following:


The mappa reports a large number of control units (six). The detail data displayed on the right column is that of the Via Arenula control unit, as can be seen by reading on the top left ("Arenula, Rome, Lazo AQI").

The reference values ​​of the air quality index are the following:

AQI indexStateDescription
0- 50GoodThe air quality is considered satisfactory, the inquirenameis limited and without particular risks.
51- 100moderateAir quality is acceptable; however for some pollutants there may be prohealth problems for a limited number of particularly sensitive peoplenamento.
101- 150Unhealthy for someMembers of large groups of subjects sensitive to pollutants could suffer prohealth problems. The mass should not be involved.
151- 200UnhealthyAnyone begins to feel the effects on prohealth due to the concentration of pollutants. Members of large groups of sensitive subjects suffer even greater damage.
201- 300Very unhealthyAnyone undergoes, in variable measures, damage to the proyour health.
301+HAZARDOUSAlert: anyone who suffers serious damage to the proyour health.

API tokens

To access the AQICN information it is necessary to equip yourself of a profirst Token API, which can easily be obtained by accessing to this form and filling in the data. A verification email will be sent in which you will find the link ("Confirm you email address") Which will provide direct access al profirst Token, who appwill appear as a string of characters as in the following example:

You token is:


Basic configuration

To add to the configuration of Home Assistant a new sensor of type "waqi" (the name of the platform we will use), in configuration is the following:

  - platform: waqi
    token: ff4496cd11a907cbd145e6cfc4f4d942e6a19b94
      - Arenula, Roma, Lazio

The variables available for configuration customization are the following:

token(string | required) The Token key obtained through AQICN
locations(list | mandatory) The list of control units to be monitored. A specific sensor will correspond to each control unit / location. The name to be specified is the one identified in the "Initial Information" section of this guide.
In the example the "Arenula, Rome, Lazio" control unit was used.
stations(list | optional) The list of substations possibly present at the various "locations"

Such a definition creates aentity (sensor type) so modeled:

WAQI Home Assistant - sensor example

As noted easily, the sensor (called "sensor.waqi_arenula_roma_lazio_italy") Contains in profirst "state" the air quality index (in this case "50").
In parallel, the sensor contains a whole series of attributes which can then be used as desired: quantities of PM 2,5-10, carbon dioxide and various others (the list may vary depending on the unit in use).

Sensor customization

As explained, the index provided by AQICN is numeric a number which helps little in understanding the quality status of the air.

To remedy this proWe will create a sensor using the platform "template Sensor"Of Home Assistant which provides a verbal description instead of the index, mappin fact the numerical values ​​as follows:

Value rangecorrespondence
101-150Unhealthy for some
201-300Very unhealthy

The configuration to add it's the following:

  - platform: template   
        friendly_name: "Qualità dell'aria di Roma" #campo customizzabile
        value_template: >-
          {% if states('sensor.waqi_arenula_roma_lazio_italy')|int <= 50 %}
          {% elif states('sensor.waqi_arenula_roma_lazio_italy')|int <= 100 %}
          {% elif states('sensor.waqi_arenula_roma_lazio_italy')|int <= 150 %}
          Insalubre per alcuni
          {% elif states('sensor.waqi_arenula_roma_lazio_italy')|int <= 200 %}
          {% elif states('sensor.waqi_arenula_roma_lazio_italy')|int <= 300 %} Molto insalubre {% elif states('sensor.waqi_arenula_roma_lazio_italy')|int >= 300 %}
          {% endif %}%}

This configuration generates aentity sensor type call (in this case) "sensor.aqici“, Which, at the frontend, appare so (the example is consistent with the rest of the guide):

WAQI Home Assistant - example custom sensor

Home Assistant Official LogoATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Home Assistant, for any doubt, question, information on the specific merit of these components.

Please comment below