Skip to main content

Simple PurpleAir integration for Home Assistant

With much of the western United States on fire, and blankets of smoke spanning much of the distance to the the midwest, I wanted to be able to integrate data from the PurpleAir free air quality platform. Inspired by @colohan's PurpleAir Air Quality Sensor using the REST platform I dug a little deeper and definitely went overboard with my solution.

Screenshot of the air quality sensor detail, showing the current PM2.5 value over time, and showing the current calculated air quality index value, and the PM1.0, PM2.5 and PM10 sensor values.

While the solution linked above works well, I wanted a solution that could work with multiple sensors and show up as a native air quality sensor in Home Assistant. After getting started with the base, I was able to accomplish all of my initial goals and managed to even release it to the public as well. It may or may not work with HACS, as I don't use it. You can find the repository on GitLab. It's released under the MIT license so feel free to do whatever with it.

The new integration only supports setup via the GUI, and by copying a sensor JSON url during setup. It's basic as heck, but it gets the job done. Once initialized, you will have an air quality sensor, providing the PM1.0, PM2.5, and PM10 data, plus a calculated US EPA Air Quality Index (AQI) value for PM2.5. Note that while Home Assistant actually supports PM0.1 data, PurpleAir only goes to 0.3, and only gives you a raw count at that, rather than calculating the µg/m³ value. I didn't feel comfortable attempting to calculate that with the data at hand and having people rely on it. Additionally, as well as giving you an air quality sensor, a generic sensor is also provided, surfacing the calculated AQI data itself, allowing for ease of use with any automations or dropping it on your dashboard.

Installation & Setup

Installation is as straightforward as it can be, simply download the source, and extract the purpleair directory in your <config>/custom_components directory (where <config> is the directory that contains your configuration.yaml file. Restart Home Assistant to get it to pick it up, and add the integration via the GUI.

Screenshot of adding a new PurpleAir sensor.

Adding the sensor couldn't be easier (well, it could be, but this was a one-day project)!

  1. Navigate to the PurpleAir Map.

  2. Find the nearest sensor to your location. It could be down the street or a couple counties over. It all depends on where you live!

  3. Click on the sensor, and click on the "Get This Widget" and copy the "JSON" link (this is the annoying part).

  4. Paste the URL in the integration dialog and submit. You should be golden!


There are a couple things to note though!

  • This was a one-day project, so it only supported what I needed to accomplish at the time.

  • It does not support accessing the local sensor data directly on your network. I don't have a device here to test with. To support batching, the API URL it uses is hard-coded.

  • It batches the API calls in an attempt to be nice to the free API service provided. It polls every 5 minutes and batches all configured sensors together. (PurpleAir updates their data every 2 minutes) This means that if you add a second station, it can take up to 5 minutes before the station starts showing data.

  • It averages out the data on stations that have two sensors. There was an attempt at determining a "confidence" score associated with it and trying to surface that somehow. I couldn't find any supporting documentation on how PurpleAir does it for their map, so it's left undone at this point. This does mean that if you have a sensor that's wildly out of whack, your AQI will reflect it accordingly. If it becomes an issue, I'll look at addressing it. You can see the confidence of the station by looking at the station card and looking for the small ✓100% label (I've only ever seen 100%).

  • There is NO ERROR HANDLING in this. Like, at all. If the network goes down or the API changes, it'll fail with error messages in your log file. If you want some insight on what it's doing, you can add the following snippet to your configuration.yaml file to get debug logging enabled for the component:

      default: info
        custom_components.purpleair: debug

Fancy-factor Dashboard Cards

To up the fancy-factor in displaying the AQI data, I ended up using the mini-graph-card and a little Lovelace configuration. It's amazing how far Home Assistant has come to be able to add this level of customization while keeping it relatively easy to use and extend.

Screenshot of the PurpleAir integration with the mini-graph-card graph and the current air quality index and micrograms per cubic meter displayed.

It's nothing much, it's a vertical stack with the mini graph card, and an entity list beneath it. To increase the visual information, the graph lines use the color threshold option to match the standard AQI color scheme. If you want a similar setup, here's the YAML for the whole setup. Simply copy out the mini-graph-card part if that's all you're interested in.

type: vertical-stack
  - type: 'custom:mini-graph-card'
      - sensor.broadlake_view_air_quality_index
    line_width: 5
    points_per_hour: 4
    hours_to_show: 6
      legend: false
      labels: false
      - value: 0
        color: '#68e143'
      - value: 50
        color: '#ffff55'
      - value: 100
        color: '#ef8533'
      - value: 150
        color: '#ea3324'
      - value: 200
        color: '#8c1a4b'
      - value: 300
        color: '#731425'
  - type: entities
      - entity: air_quality.broadlake_view

Please let me know if you use it or if you have any problems. You can reach me on the Home Assistant forums or open an issue in the repository.