homebridge-pollen

Homebridge plugin that exposes pollen levels as HomeKit air quality sensors using the Google Pollen API.

Features

• Air quality sensors — Pollen index mapped to HomeKit's 5-level air quality scale (Excellent, Good, Fair, Inferior, Poor)
• Per-category sensors — Optionally add separate sensors for tree, grass, and weed pollen
• No runtime dependencies — Uses Node.js 20+ built-in fetch

Requirements

• Node.js 20.0.0 or later
• Homebridge 1.8.0 or later (including Homebridge 2.x)

Installation

Using the Homebridge UI

Search for homebridge-pollen in the Homebridge UI plugin search and install it.

Using npm

npm install -g homebridge-pollen

Getting an API key

This plugin requires a Google Maps API key with the Pollen API enabled.

1. Go to the Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable the Pollen API under APIs & Services > Library
4. Create an API key under APIs & Services > Credentials
5. Set up a billing account if you haven't already (required even for the free tier)

The free tier allows 5,000 requests per month. With the default 60-minute poll interval, the plugin uses approximately 720 calls per month.

Configuration

You can configure the plugin using the Homebridge UI or by editing your config.json directly.

Example configuration

{
  "platforms": [
    {
      "platform": "HomebridgePollen",
      "apiKey": "your-google-maps-api-key",
      "location": "10001"
    }
  ]
}

Configuration options

Option	Required	Default	Description
platform	Yes	—	Must be HomebridgePollen
apiKey	Yes	—	Your Google Maps API key with the Pollen API enabled
location	Yes	—	Zip code or place name. Geocoded to coordinates on first startup and cached.
pollInterval	No	60	How often to fetch pollen data, in minutes (minimum 15)
enableCategorySensors	No	false	Add 3 additional sensors for tree, grass, and weed pollen

How it works

The plugin creates an air quality sensor that displays the overall pollen level. The Google Pollen API provides a Universal Pollen Index (UPI) from 0–5, which maps to HomeKit's air quality scale:

UPI	Category	Air quality
0	None	Excellent
1	Very Low	Excellent
2	Low	Good
3	Moderate	Fair
4	High	Inferior
5	Very High	Poor

The overall sensor displays the worst (highest) pollen index across tree, grass, and weed categories.

Location geocoding

The plugin accepts a place name or zip code in the location config field. On first startup, it geocodes this to latitude/longitude coordinates using Nominatim (OpenStreetMap) and caches the result. Subsequent startups use the cached coordinates unless the location changes.

Optional sensors

When enableCategorySensors is enabled, you get 3 additional air quality sensors:

• Tree Pollen — Air quality based on tree pollen index
• Grass Pollen — Air quality based on grass pollen index
• Weed Pollen — Air quality based on weed pollen index