🌼 Pollen Levels Integration for Home Assistant

Monitor real-time pollen levels from the Google Maps Pollen API directly in Home Assistant.
Get sensors for grass, tree, weed pollen, plus individual plants like OAK, PINE, OLIVE, and many more!

---

Requirements

• Requires Home Assistant 2026.3.0 or newer.
• This release line targets Python 3.14+, matching the Home Assistant runtime baseline.

🌟 Features

• Multi-language support — UI in 21 languages (EN, ES, CA, DE, FR, IT, PL, RU, UK, NL, ZH-Hans, SV, CS, PT-BR, DA, NB, PT-PT, RO, FI, HU, ZH-Hant) + API responses in any language.
• Dynamic sensors — Auto-creates sensors for all pollen types found in your location.
• Daily summary sensors — Adds plants in season today, overall pollen risk today, and top pollen types today.
• Multi-day forecast for TYPES & PLANTS —
  • forecast list with {offset, date, has_index, value, category, description, color_*}
  • Convenience: tomorrow_* and d2_*
  • Derived: trend and expected_peak
  • Per-day sensors: remain TYPES-only with selector options none, D+1, or D+1+2 (creates both (D+1) and (D+2) sensors). PLANTS expose forecast as attributes only (no extra entities).
• Smart grouping — Organizes sensors into:
  • Pollen Types (Grass / Tree / Weed)
  • Plants (Oak, Pine, Birch, etc.)
  • Pollen Info (Region / Date metadata)
• Configurable updates — Change update interval, language, forecast days, and per-day sensors without reinstalling.
• Manual refresh — Call pollenlevels.force_update to trigger an immediate update and reset the timer.
• Last Updated sensor — Shows timestamp of last successful update.
• Rich attributes — Includes inSeason, index description, health advice, color_hex, color_rgb, and plant details.
• Resilient startup — Retries setup automatically when the first API response lacks daily pollen info (dailyInfo types/plants), ensuring entities appear once data is ready.

---

🔒 Security & Privacy

• Your API key is stored by Home Assistant’s secure config entries.
• We never log your API key. As a safety net, if it ever appears in an error message, it is redacted as ***.
• We do not log request parameters (coordinates). Debug logs only include non-sensitive metadata (e.g., forecast days and whether a language is set).
• Diagnostics include a redacted daily_summary snapshot to help troubleshoot the daily summary sensors without exposing API keys or exact coordinates.
• Avoid sharing full debug logs publicly; review them for sensitive information before posting.
• Never share real Google API keys publicly, and do not paste full Google Pollen API URLs containing key=... into public issues. If a key was exposed, rotate it in Google Cloud Console and restrict it to the required API and allowed referrers/IPs where possible.

---

⚙️ Options

You can change:

• Update interval (hours) (1–24)
• API response language code
• Forecast days (1–5) for pollen TYPES
• Per-day TYPE sensors via create_forecast_sensors:
  • none → no extra sensors
  • D+1 → sensors for each TYPE with suffix (D+1)
  • D+1+2 → sensors for (D+1) and (D+2)

Validation rules:

• D+1 requires forecast_days ≥ 2
• D+1+2 requires forecast_days ≥ 3

The config and options flows use modern Home Assistant selectors and include links to Google’s API key setup and security best practices so you can follow the recommended restrictions.

After saving Options: if per-day sensors are disabled or forecast_days becomes insufficient, the integration removes any stale D+1/D+2 entities from the Entity Registry automatically. No manual cleanup needed.

Go to Settings → Devices & Services → Pollen Levels → Configure.

---

Daily summary sensors

The integration creates three current-day summary sensors in addition to the individual pollen type and plant sensors:

• plants_in_season_today
  • State: number of plants explicitly marked as in season today.
  • Key attributes: plant_codes, plant_names, in_season_count, out_of_season_count, unknown_season_count, total_plant_count, unknown_season_codes, and unknown_season_names.
  • Missing or non-boolean inSeason values are treated as unknown, not false.
• overall_pollen_risk_today
  • State: highest current-day pollen type index value.
  • Key attributes: category, description, top_pollen_codes, top_pollen_names, top_pollen_categories, and tie_count.
  • Tied top pollen types are preserved in the attributes.
• top_pollen_types_today
  • State: top pollen type name, or comma-separated names when tied.
  • Key attributes: top_value, top_pollen_codes, top_pollen_names, top_pollen_categories, and tie_count.

---

🗝️ Getting a Google API Key

You need a valid Google Cloud API key with access to the Maps Pollen API.

1. Open the Google Cloud Console.
2. Create or select a project and enable billing for it.
3. Go to APIs & Services → Library and enable the
   Maps Pollen API.
4. Go to APIs & Services → Credentials → Create credentials → API key.
5. Restrict your key (recommended):
   • API restrictions → Restrict key → select Maps Pollen API only.
   • Application restrictions (optional):
     • Prefer IP addresses for server-side usage (your HA host).
     • If your IP is dynamic, consider no application restriction and rely on the API restriction above.
6. Copy the key and paste it in the integration setup.

The setup form also links directly to the Google documentation for obtaining an API key and best-practice restrictions.

👉 See the FAQ for quota tips, rate-limit behavior, and best practices to avoid exhausting your free tier.

HTTP referrer (website) restrictions are intended for browser-based apps and are not supported by this integration.

Troubleshooting 403 errors

403 responses during setup or updates now include the API’s reason (when available). They often indicate billing is disabled, the Pollen API is not enabled, or your key restrictions do not match your Home Assistant host.

---

🔧 Showing colors in the UI

Home Assistant does not color icons natively from attributes.
If you want dynamic colors driven by color_hex / color_rgb, you have these options:

✅ Native options (no custom cards)

1. Entities card (attribute row)

type: entities
title: Grass
entities:
  - type: attribute
    entity: sensor.type_grass
    attribute: category
    name: Category
  - type: attribute
    entity: sensor.type_grass
    attribute: description
    name: Index description

Simple and robust. It shows attributes clearly but doesn’t color the icon.

2. Gauge card (color by severity based on numeric value)

type: gauge
entity: sensor.type_grass
min: 0
max: 5
severity:
  green: 0
  yellow: 2
  red: 4

Color is driven by thresholds, not by color_hex.

---

🧩 Custom cards (for real dynamic color binding)

Pollen dashboard card (recommended): pollenprognos-card

If you want a dedicated pollen Lovelace card with forecast visualizations and a visual editor UI, pollenprognos-card supports this integration since v2.9.0.

• Repo: pollenprognos-card
• Install: HACS → Frontend

If you need the icon/badge to follow the exact API color (color_hex):

Mushroom (mushroom-template-card)

type: custom:mushroom-template-card
entity: sensor.type_grass
primary: >-
  Grass: {{ states(entity) }} ({{ state_attr(entity, "category") }})
icon: mdi:grass
badge_icon: mdi:circle
badge_color: >-
  {{ state_attr(entity, "color_hex") or "var(--primary-color)" }}

button-card

type: custom:button-card
entity: sensor.type_grass
icon: mdi:grass
show_state: false
name: '[[[
  const s = states[entity];
  const cat = s?.attributes?.category ?? "";
  return `Grass: ${s?.state ?? "unknown"} (${cat})`;
]]]'
color: '[[[
  const s = states[entity];
  return s?.attributes?.color_hex || "var(--primary-color)";
]]]'

---

⚠️ Known caveats

• Localized plant codes: Google may localize plantInfo.code in some locales (e.g., GRAMINALES in ES) while others remain English (OLIVE, MUGWORT). Changing languageCode may recreate plant sensors with a different suffix. Recommendation: keep API language stable or rename entities in UI after changing it.

---

⚙️ Installation

Via HACS (recommended)

1. Open HACS → Integrations in Home Assistant.
2. Click Explore & Download Repositories.
3. Search for Pollen Levels or click the badge above.
4. Click Download and follow prompts.
5. Restart or Reload HA when prompted.

---

🔑 Configuration

1. Go to Settings → Devices & Services → Add Integration.

2. Search for Pollen Levels.

3. Enter:

   • Google API Key
   • Location
   • Update Interval (hours)
   • Language Code

---

🌐 Example API request

curl -X GET "https://pollen.googleapis.com/v1/forecast:lookup?key=YOUR_KEY&location.latitude=48.8566&location.longitude=2.3522&days=2&languageCode=es"

Note: Replace YOUR_KEY locally and never share full API URLs containing key=... publicly.

---

❤️ Support the project

If this integration helps you, consider supporting development:

---

📜 License

MIT © 2025 eXPerience83 Data Source: Google Maps Pollen API