Particle Man Air Quality - FREE Comprehensive Google API solution

Share your Projects! Custom Integrations
1

Hi community,

I spent the past few weeks building an air quality integration that solves problems I have here in Chicago. I have allergies, and until the wildfires a couple years ago didn’t realize how sensitive I was to particulates. Home Assistant came to the rescue, sort of. I found a fragmented landscape of air quality and pollen sources, and was disappointed by the lack of forecast data I knew existed — super helpful for both pollen and wildfire awareness.

So I built Particle Man, which pulls (almost) all possible information from the Google Pollen and
Google Air Quality APIs.

While this is the first release and it is self-published, it currently passes HACS validation and meets, to my best understanding, all HA Bronze quality standards (Gold is my goal).

Please review if you’d like, give it a try, and send me feedback publicly or privately — whatever
you’re comfortable with. Full docs at
mnestrud.github.io/particle-man.

Features: Current Conditions

  • Universal AQI (UAQI) with health category, dominant pollutant, and trend
  • Pollutant sensors — concentration, unit, EPA health category (where applicable), dominant
    pollutant flag, sources, effects, and trend. Split by EPA breakpoint availability:
    • With EPA health category: PM2.5, PM10, Ozone (O3), Nitrogen Dioxide (NO2), Carbon Monoxide
      (CO), Sulfur Dioxide (SO2)
    • Concentration only: Additional pollutants returned by the API for your region
  • Pollen sensors by type (Grass, Tree, Weed) with index, color, and trend
  • API usage tracking — billing-period call counts with projected usage and free-tier warnings
    (details)

Forecast

All forecast data is stored as sensor attributes (hourly_forecast, daily_forecast) for use in
dashboard charts and automations.

  • Hourly AQI forecast up to 96 hours
  • Daily AQI forecast up to 5 days — peak AQI per day
  • Hourly pollutant forecast up to 96 hours per pollutant
  • Daily pollutant forecast up to 5 days — peak concentration per day
  • Daily pollen forecast up to 5 days with trend and expected peak (no hourly pollen data available
    from Google)

Optional

  • Regional AQI index — US AQI and 12 other country-specific indices (supported
    indices    )
  • Health recommendations — text guidance included as sensor attributes
  • Per-plant pollen sensors — individual species (Oak, Ragweed, etc.) with index, trend, and peak
  • Plant descriptions — family, genus, and cross-reaction info added to plant sensor attributes
  • Enforce API limits — suspend polling when a monthly call limit is reached, keeping usage within
    the free tier

Pictures (no code yet, but here’s my working dashboard)

image
image1438×755 85.1 KB

image
image2241×750 47 KB

AI was harmed, cussed at, but in the end effectively used to help engineer this integration.

2 Likes
2

“How fast can someone get to working sensors?” is the question I’ve been asking myself since the initial post about this. I value the user experience a lot, and so this question has led to a lot of feature updates and changes for this update. In particular I have had some fun learning the new (as of 2024) Configuration and Options flow frameworks, which are f’ing awesome for simplifying the user experience (hat tip @epenet ).

ALSO: WEATHER Weather sources are a hot topic and finding good free sources can be challenging. This solves it if you’re in need of a different solution. Its also part of the automagic free tier maximization. The biggest concern with google as a source is running out of data half way through the month. If you use automagic mode that won’t happen. If you have a paid API turn off automagic.

This was the last huge update before moving on to publish on HACS. I wanted to harden this integration so I voluntarily massaged it into HA Platinum status - which doesn’t really apply to custom integrations, but provides some gold standard code audits, checking, and quality control that is confidence building.

TODO, maybe: My alert sensor setup isn’t my favorite / customizable enough, but I have to think through the balance of simplicity + detail. Anything that comes up in the next week or so will get fixed before then as well.

Full changelog below.

## Particle Man v1.5.0

  ### Added

  - **Google Weather API** — full HA weather entity with hourly, daily, and twice-daily forecasts; current conditions include temperature, humidity,
   wind, pressure, UV index, visibility, and precipitation
  - **Extra weather sensors** — Thunderstorm Probability, Heat Index, Wind Chill
  - **Weather Alerts sensor** *(optional)* — count of active warnings with severity, event type, and full alert details as attributes
  - **Air Quality Advisory sensor** — simplified 4-level (None / Caution / Warning / Alert) mapped from Universal AQI; intended for automations that
   don't need numeric thresholds
  - **Pollen Advisory sensor** — worst pollen level across all in-season types in a single sensor
  - **Multi-location support** — monitor multiple locations per API key; add, edit, and remove locations via Configure without re-adding the
  integration
  - **Per-API toggles** — Air Quality, Pollen, and Weather can be independently enabled or disabled
  - **Automagic mode** — calculates a safe polling interval automatically based on enabled APIs, monthly limits, and number of locations; eliminates
   manual interval tuning to stay within free tier
  - **Quota enforcement** — each API pauses independently when its monthly free-tier limit is reached and resumes automatically at the start of the
  next billing period
  - **Quiet hours** — configurable overnight polling pause (default 23:00–05:00)
  - **Projected usage preview** — options form shows estimated monthly API calls before saving, with a suggested minimum interval based on enabled
  APIs and number of locations
  - **3 automation blueprints** — AQI Alert, Morning Pollen Brief, Outdoor Activity Check

  ### Changed

  - Options flow restructured into multi-step pages: Polling & Limits, APIs, Air Quality, Pollen, Weather, Custom Limits
  - Billing period reset: configurable reset day replaced with fixed 1st of month at midnight Pacific Time, matching Google's actual billing cycle
  - Quota tracking is now shared across multiple config entries using the same API key
  - Documentation site refactored from 8 pages to 6 with a quick-start-first structure
  - Self-assessed compliance with all HA Integration Quality Scale criteria through Platinum tier (Bronze 16/16, Silver 9/9, Gold 18/18, Platinum
  3/3 — note: the official Platinum designation is awarded by Nabu Casa to core HA integrations only)

  ### Removed

  - Configurable billing reset day (replaced by fixed Pacific Time billing cycle)
3

Allright, I’ve submitted this to HACS so we’ll see how it goes. Lots of changes under the hood. Much better documentation. Working cards with forecasts etc. all baked in.

One notable addition is that I pointed claude code to the Home Assistant ADRs and had it audit compliance, which resulted in a few changes above and beyond. Review the full changelog below, its a lot. I also used this framework to build an integration template for claude code that allows me to develop integrations fully compliant with all known coding standards and quality goals (HA Platinum, ADRs, APIs changelogs, etc.). That is going to be the fun part!

For those that are paying attention it seems they are in about a 2 month lag on getting acceptance.

As far as I’m concerned this is ready to go if anyone wants to give it a try, or wait for HACS - whatever floats your boat.

1 Like