PurpleAir

PurpleAir makes sensors that measure hyper-local air quality data and share it with the public.

Configuration

To add the PurpleAir integration to your Home Assistant instance, use this My button:

Options

Options for PurpleAir can be set via the user interface, by taking the following steps:

• Browse to your Home Assistant instance.
• Go to Settings > Devices & Services.
• If multiple instances of PurpleAir are configured, choose the instance you want to configure.
• Select the integration, then select Configure.

Creating an API key

To add this integration, you need a (free) Purple Air API Key. A new account currently comes with 1 million free points. After that, you need to buy additional points to continue to use the API. The current plugin uses ~30K points/day. The 1 million points last about a month. A lack of points will trigger API errors until you buy more points.

Detailed instructions can be found here but in summary you:

• Create an account at https://develop.purpleair.com/ (which uses Single Sign-On through a Google account).
• On the ‘keys’ page press the “plus” button to create an API key. Leave the defaults of Read and Enabled.
• Go to the ‘projects’ page and select the edit (pencil) button on the listed Project. Add points (for example 1,000,000), then select Update.
• Go back to the ‘keys’ page and copy the API key. It will be a value like XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX.
• Paste that API key into the API Key field when creating the integration in Home Assistant.

Note that if you are using your own sensor, it will need to be set to Public to be visible.

Creating an AQI Rating from Raw Particulate Data

The PurpleAir API does not provide AQI data; therefore, the integration does not create an AQI sensor automatically. However, sensors providing raw particulate data can be used to create a human-friendly AQI rating sensor.

Understanding EPA Guidelines

The United States Environmental Protection Agency (EPA) provides guidelines on correlating the concentration of pollution over a time period to overall “healthiness.” For example, a PM2.5 concentration between 0.0 and 12.0 µg/m³ over a 24-hour period equates to a “Good” AQI rating.

Therefore, a common strategy would be to use the guidelines for the particulate types provided by the PurpleAir integration and “merge” them into a single AQI rating.

Creating Statistics Sensors

With the EPA guidelines in hand, the next step is to create statistics sensors for each particulate sensor you are interested. This example uses PM2.5 and PM10.0 over a 24-hour period:

sensor:
  - platform: statistics
    name: "Average Outdoor PM2.5 (24h)"
    entity_id: sensor.sensor_pm2_5_mass_concentration
    state_characteristic: mean
    max_age:
      hours: 24

  - platform: statistics
    name: "Average Outdoor PM10.0 (24h)"
    entity_id: sensor.sensor_pm10_0_mass_concentration
    state_characteristic: mean
    max_age:
      hours: 24

Creating the AQI Rating Sensor

The statistics sensors can then be combined into a template sensor. Note that this example takes a conservative approach: the “worse” of the two values (PM2.5 or PM10.0) is used to determine the overall rating.

template:
  - sensor:
    - name: "Local Outdoor Air Quality"
      state: >
        {% set pm2_5_avg = states("sensor.average_outdoor_pm2_5_24h") | int %}
        {% if 0 <= pm2_5_avg <= 12.0 %}
          {% set pm2_5_rating = 0 %}
        {% elif 12.0 < pm2_5_avg <= 35.4 %}
          {% set pm2_5_rating = 1 %}
        {% elif 35.4 < pm2_5_avg <= 55.4 %}
          {% set pm2_5_rating = 2 %}
        {% elif 55.4 < pm2_5_avg <= 150.4 %}
          {% set pm2_5_rating = 3 %}
        {% elif 150.4 < pm2_5_avg <= 250.4 %}
          {% set pm2_5_rating = 4 %}
        {% else %}
          {% set pm2_5_rating = 5 %}
        {% endif %}

        {% set pm10_0_avg = states("sensor.average_outdoor_pm10_0_24h") | int %}
        {% if 0 <= pm10_0_avg <= 54.0 %}
          {% set pm10_0_rating = 0 %}
        {% elif 54.0 < pm10_0_avg <= 154.0 %}
          {% set pm10_0_rating = 1 %}
        {% elif 154.0 < pm10_0_avg <= 254.0 %}
          {% set pm10_0_rating = 2 %}
        {% elif 254.0 < pm10_0_avg <= 354.0 %}
          {% set pm10_0_rating = 3 %}
        {% elif 354.0 < pm10_0_avg <= 424.0 %}
          {% set pm10_0_rating = 4 %}
        {% else %}
          {% set pm10_0_rating = 5 %}
        {% endif %}

        {% set rating = [pm2_5_rating, pm10_0_rating] | max %}
        {% if rating == 0 %}
          Good
        {% elif rating == 1 %}
          Moderate
        {% elif rating == 2 %}
          Unhealthy for sensitive groups
        {% elif rating == 3 %}
          Unhealthy
        {% elif rating == 4 %}
          Very unhealthy
        {% else %}
          Hazardous
        {% endif %}
      unique_id: local_outdoor_air_quality