Pollens smart home integration, free and open source
Pollen risk for the locations you choose, from the Copernicus CAMS European forecast.
Published by prohand
- Devices
- Version 2.0.3
- Requires Gladys >=5.1.0
- ★ 0
This integration exposes the pollen risk of the locations you choose as Gladys devices: one device per location, with a 0-to-3 risk level — Gladys's own scale — for each pollen type. You add your Gladys houses in one click, or a location by typing its town.
No account to create, no API key to paste.
The risk also shows on your dashboard (two widgets) and drives your scenes (two triggers, two actions).
This version requires Gladys 5.1 or newer: an integration's dashboard widgets and scene cards do not exist before it.
Where the data comes from
Pollen concentrations come from the CAMS European air quality forecast (Copernicus Atmosphere Monitoring Service, the atmospheric service of the EU Copernicus programme, operated by ECMWF). It is the reference model in Europe, on a ~11 km grid.
It is queried through Open-Meteo, which republishes CAMS as open data with no account and no API key.
The towns you type are turned into coordinates by the Open-Meteo geocoding API, backed by the GeoNames database — also open and unauthenticated, and worldwide, so there is no country to pick anywhere in this integration.
What about Atmo France? Atmo France does publish a pollen index for France, but its API requires an account and an authentication token that every user would have to create before the integration works at all. CAMS was chosen because it is official and usable with zero setup.
Adding your Gladys houses, in one click
You have already told Gladys where you live: that is the map in Settings > Houses. The "Add my Gladys houses" button reads those houses and creates a location for each one that is not watched yet — no town to type.
Four things worth knowing:
- The access is a permission. Where you live is personal data: Gladys only shares it if you accepted the request on the integration's install screen. If the button answers that the access is refused, remove and re-install the integration, accepting the request shown there.
- A house you never placed on the map has no coordinates. It is named in the answer; locate it in Settings > Houses and click the button again.
- A house outside the CAMS European domain is named too, and left out: no pollen forecast covers it (see "Geographic coverage" below).
- This is not a sync. The houses are read at the moment you click. What comes out is an ordinary location, which you rename and remove like any other, and a house moved in Gladys afterwards does not move its location.
Clicking again is safe: a house already watched is reported, not added twice.
Reading the houses needs the house coordinates Gladys opened in 4.85.0 — this integration requires Gladys 4.86.0 or newer in any case.
Adding a location
- Open the integration's Configuration tab.
- Click Add a location.
- Type the town, e.g.
Montauban. Naming the location is optional: the town's name is used when you leave the field empty. - Submit.
Most place names are shared by several towns — there are two Montauban in France
alone, and a dozen Paris in the world. When that happens the integration lists
the candidates instead of guessing: run the action again with a comma and the
region, the country or the postal code, e.g. Montauban, Tarn-et-Garonne or
Paris, France.
You can also add a point directly: fill in the latitude and the
longitude (WGS-84 decimal degrees, both of them — one alone is not a point).
They are read with either decimal separator, so 48,8566 works as well as
48.8566. Coordinates win over the town, which is then only kept as the label
of the location.
The location then shows up in the Discovery tab, named
Pollens — <name>. Click it to create the device in Gladys — that is when it
becomes usable in dashboards and scenes.
You can add up to 20 locations.
Seeing and removing your locations
Show my locations prints them, numbered:
• 1. Home — Montauban, Tarn-et-Garonne, France (44.01810, 1.35490)
• 2. Office — Toulouse, Haute-Garonne, France (43.60426, 1.44367)
Those numbers are what the deletion dropdown offers, because a dropdown declared in a manifest can only hold fixed options — never your location names.
To remove one: click Remove a location, pick its number, tick I confirm and submit. Running it without the checkbox tells you which location would be removed. The location disappears from the Discovery tab immediately, and the locations below it move up a rank — so print the list again before deleting a second one.
If you had already added the device to Gladys, delete it from the device page too: an integration is not allowed to delete a device you created. Conversely, if you delete the device without removing the location, it comes back in the Discovery tab, ready to be added again.
What the device measures
Each device exposes sixteen measurements: an overall risk, its wording, the dominant pollen, the date of the data, then for each of the six pollens a risk index and the same risk spelled out.
| Measurement | Description |
|---|---|
| Overall pollen risk | The highest of the six risks below (0 to 3) |
| Overall pollen risk (text) | The measured risk spelled out: "4/5 (high)" |
| Dominant pollen | The name of the pollen driving that risk |
| Last data update | The date and hour the displayed forecast is for |
| Alder pollen risk | Risk from 0 to 3 |
| Alder pollen risk (text) | The measured risk spelled out: "4/5 (high)" |
| Birch pollen risk | Risk from 0 to 3 |
| Birch pollen risk (text) | The measured risk spelled out: "4/5 (high)" |
| Grass pollen risk | Risk from 0 to 3 |
| Grass pollen risk (text) | The measured risk spelled out: "4/5 (high)" |
| Mugwort pollen risk | Risk from 0 to 3 |
| Mugwort pollen risk (text) | The measured risk spelled out: "4/5 (high)" |
| Olive pollen risk | Risk from 0 to 3 |
| Olive pollen risk (text) | The measured risk spelled out: "4/5 (high)" |
| Ragweed pollen risk | Risk from 0 to 3 |
| Ragweed pollen risk (text) | The measured risk spelled out: "4/5 (high)" |
The "(text)" measurements are what a notification, a dashboard text box or a
voice assistant reads: a scene reading the index gets a 3, and 3 is what it
puts in its message. A pollen the model has no value for publishes nothing at
all, neither index nor wording.
The index and the wording are not on the same scale, on purpose. The index
is on the Gladys scale, 0 to 3 — the only one the core can name. The wording is
a plain string nobody re-reads downstream, so it carries the measurement
itself, 0 to 5, the European bands the CAMS data follows. A "high" day and a
"very high" day both read 3 on the index, but "4/5 (high)" and "5/5 (very
high)" on the text.
These are the names with the Language of the device names setting on English. It defaults to French (
Risque pollinique — Bouleau) — see The language of the names below.
The numeric measurements keep their history, so you can chart the pollen season of your town.
When the model has no value for a species at that position, nothing is published for that species — a missing measurement is not a zero risk.
How old are these numbers?
The Last data update measurement answers that. It shows the date and hour
the displayed forecast is for, as 2026-08-06 13:00.
It is the date of the data, not of the last request: CAMS publishes its forecast once a day and Open-Meteo interpolates it hour by hour, so a successful refresh usually re-reads exactly the same numbers. What you want to know is how old those numbers are, not when they were last fetched.
The hour shown is the location's own: a forecast is read against the clock of the town it covers. For a location in your timezone that is simply your time; for one further away it is the local time over there. It is also why this measurement sits on every device rather than on a single one shared by the whole integration: two locations do not necessarily carry the same.
If the date stays stuck in the past, the refresh is failing: the Test the pollen provider button shows the same date for every location, and says what is going wrong if anything is.
The risk scale
It is Gladys's scale, not one of our own. Gladys knows how to name four risk levels, and it is Gladys that writes the label next to the measurement in the "device in a room" box:
| Level | What Gladys shows | Colour |
|---|---|---|
| 0 | No Risk | Green |
| 1 | Low | Yellow |
| 2 | Medium | Orange |
| 3 | High | Red |
The integration publishes exactly those four levels and nothing else. So the device box, the widgets, the scene triggers and the notifications all say the same thing about the same number. The text measurements and the widgets add the scale to the word — "2/3 (medium)" — so you can place a level without knowing the scale by heart.
The CAMS data follows the bands of the European Aeroallergen Network (EAN), which has six of them. They are folded onto Gladys's four levels:
| EAN band (text measurement) | Published index | Gladys name |
|---|---|---|
| 0/5 (none) | 0 | No Risk |
| 1/5 (very low) | 1 | Low |
| 2/5 (low) | 1 | Low |
| 3/5 (moderate) | 2 | Medium |
| 4/5 (high) | 3 | High |
| 5/5 (very high) | 3 | High |
Nothing important is lost in the fold: the two quiet bands both mean "there is barely any", and the two loud ones both mean "stay inside if you react to it".
The measured band stays readable: the "(text)" measurements of the device show it as it is, from 0 to 5. That is the one place it survives, because a string is displayed exactly as it was stored where Gladys re-labels a number with its own words.
The level is derived from the concentration in pollen grains per cubic metre of air, using per-species thresholds: 30 grains/m³ is a quiet day for birch (level 2) but a heavy one for ragweed (level 3), whose allergenic power is far stronger.
Coming from a 0-5 version?
The first versions published the six EAN bands as they are, from 0 to 5. That did not work: Gladys only knows how to name four levels, so a level 3 showed up as "High" where it meant "medium", and levels 4 and 5 showed up as "Unknown". The published scale is now Gladys's own.
Two things to check after the update:
- The device. It shows up in the Discovery tab with an Update button: one click is enough. The history, the rooms and the scenes are kept.
- Your scenes. A trigger or a condition aimed at level 4 or 5 no longer matches anything: aim at level 3 ("high") instead. A level 3 that meant "moderate" becomes a 2.
The history already recorded keeps its old values: on a chart covering the switch, the points before it are on the 0-5 scale and the ones after on the 0-3 scale. It still reads, but a comparison across that period is not a fair one.
The measured 0-5 band is not gone, though: it is what the "(text)" measurements of the device display, next to the index. Only the numbers a scene or a chart reads are on the 0-3 scale.
The language of the names
Device and feature names are written in French by default: the measurements
read Risque pollinique global, Risque pollinique — Bouleau, and the dominant
pollen shows up as Bouleau. Set Language of the device names to English in
the Configuration tab to get the names in the table above.
Why a setting rather than your account language? Everything the integration displays — the message under a button, the status in the Supervision screen — is sent to Gladys in both languages, and Gladys picks the one of the person reading. A device name is not a message: it is a plain text stored as it is the day you create the device, and nothing in the integration API says which language you read. So it is chosen once, here.
One consequence: changing the setting renames the features of the devices yet to be created. A device already added to Gladys keeps the names it was created with — delete it and add it again from the Discovery tab to rename it (its history goes with the deleted device).
On your dashboard
Two widgets ship with the integration. Add them from a Gladys dashboard: Edit the dashboard, Add a box, then pick them from the list.
Pollen — one place
The card of one place: the overall level on a gauge, a Dominant pollen tile naming the species that level comes from, the risk spelled out — "3/3 (high)" — then the pollens actually in the air, the curve for today and tomorrow, and a Refresh button. A species at zero takes no row: a card showing nothing means there is nothing in the air, and it says so — with no pollen in the air there is no dominant one, and the tile is gone.
When the card is narrowed to a few species, the dominant pollen and the spelled out risk are about those species, like the gauge.
Three settings, per card:
| Setting | What it does |
|---|---|
| Place | The device to display. Only the devices you already added from the Discovery tab are offered. |
| Species followed | Tick the species you react to: the gauge, the list and the curve then only account for those. Nothing ticked means all of them. |
| Show the two-day forecast | The hour-by-hour curve. Untick it for a compact card. |
The curve shows today and tomorrow, hour by hour, with a marker at the current time. It is a forecast: Gladys keeps no history of it, so it is read again on every display. With four followed species or fewer, each gets its own curve; beyond that, a single curve shows the worst of them.
When you follow every species, the gauge is bound to the device measurement itself and follows the published values in real time. With a selection of species no measurement matches it — the gauge then shows the number the card computed.
Pollen — all places
One row per configured place, with its level and its dominant pollen, and a Refresh button that reads them all again. No settings: the card shows the list the Configuration tab manages. It stops at ten rows, and says so.
Both cards are written in the language of whoever is looking at them: unlike a device name, Gladys tells us here which language you read.
Using the risk in a scene
Three ways, from the simplest to the finest.
1. The measurements, like any sensor
The overall risk is a "risk" category measurement: it behaves like any numeric sensor. A few ideas:
- close the shutters or stop the ventilation when the overall risk goes above 3;
- send a notification in the morning if the "Grass" risk is ≥ 4;
- turn the air purifier on when the dominant pollen is the one you react to.
2. The triggers
In the scene editor, under the Integrations category:
| Trigger | When it fires |
|---|---|
| Overall pollen risk changed | The overall level of a place moves from one level to another |
| Pollen risk of one species changed | The level of one pollen changes at a place |
Both fire on a change only, never on every refresh: the CAMS forecast is republished once a day, so a scene firing on every reading would fire twenty-four times for the same value.
Each trigger can be filtered: the place (empty means any), the levels you care about (tick 3 to react to peaks only), the direction (rising to close the windows, falling to open them again), and for the second one the species.
The scene then gets what it needs to write its message:
{{triggerEvent.data.summary}} holds the ready-made sentence "Pollen in Home:
risk 3/3 (high), dominant Birch.", and location_name, level, level_label,
previous_level, direction, taxon, taxon_name and measured_at are
available on their own.
Two details:
- nothing fires at startup: the previous level is unknown then, and "unknown → 3" is not a change. The first real change fires normally;
- a species with no value fires nothing: a missing measurement is not a fall back to zero, and the last known level is kept.
3. The actions
Still in the scene editor, under Integrations:
| Action | What it does |
|---|---|
| Read the pollen risk | Reads a place now and hands the level, the dominant pollen and the ready-made sentence to the next actions |
| Refresh the pollen data | Reads the forecast again and republishes the measurements; leave the place empty for every place |
"Read the pollen risk" is what turns "every morning at 7 am" into "every morning
at 7 am, tell me the risk": pick the place, leave Overall risk (or pick a
species), then send a message containing the summary output. The level (0 to
3), level_label, taxon, taxon_name, concentration, location_name and
measured_at outputs are there if you would rather write your own sentence.
When the source answers nothing, the action does not fail: it returns an empty
leveland asummarysaying the data is unavailable. It is up to the scene to decide what to do with that.
Refresh interval
Each location is refreshed hourly by default. The CAMS forecast is recomputed once a day and interpolated hourly, so going below one hour gains nothing. The interval is configurable between 15 minutes and 24 hours in the Configuration tab. A device you have just created is refreshed straight away, without waiting for the next cycle.
Geographic coverage
The CAMS forecast covers the European domain. A location outside that area is refused when you add it, rather than creating a device that would never hold a value.
Troubleshooting
- "Test the pollen provider" button: it queries the source live for every location and prints one line per location, numbered like the listing. Each line ends with the date of the data it read, so a source stuck in the past shows up here too. The quickest way to tell a network problem from a configuration one.
- The logs: read the integration logs from the Gladys UI, or with
docker logs. SetLOG_LEVELtodebugto see the URLs being queried and the exact device payload sent to Gladys. - Nothing appears in the Discovery tab: check the integration's status in the Supervision screen — when Gladys refuses a device, the reason is reported there.
- A device stays empty: check that its location is still listed by "Show my locations". A device whose location was removed is no longer refreshed.
Configuration settings
These are the settings Pollens asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| How it works | section | No | Add a location with the button below: type a town, it is geocoded, and a pollen device appears in the Discovery tab, ready to be added to Gladys. Pollen data comes from the CAMS European air quality forecast (Copernicus), republished as open data by Open-Meteo, and places are searched through the Open-Meteo geocoding API: no account and no API key are needed. Coverage is Europe, wherever the CAMS model reaches. |
| General settings | section | No | These settings apply to every configured location. |
| Language of the device names | select | No | The language the pollen names are written in: "Bouleau" or "Birch". Everything else this integration displays already follows your Gladys language, but the name of a device and of its features is stored as it is published, so it has to be chosen here. A device already added to Gladys keeps the names it was created with: delete it and add it again from the Discovery tab to rename it. |
| Refresh interval (s) | number | No | How often each location is refreshed, in seconds. The forecast is updated once a day and interpolated hourly, so there is nothing to gain below one hour. |
| Your locations | section | No | Use the buttons below to add, list and remove your locations. "Add my Gladys houses" turns the houses you already placed on the map in Gladys into locations, in one click. They are not fields of this form: a list you build as you go cannot be one, so everything about them happens under a button, and the answer displayed there is what shows you the list. |
How to install Pollens in Gladys
- In Gladys, open Integrations: Pollens appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/prohand/gladys-pollen:2.0.3), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/prohand/gladys-pollen.
Pollens requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Pollens is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by prohand, not by the Gladys core team.
- Browse all external integrations
- Discover the native integrations built into Gladys
- Build and publish your own external integration
- Source code on GitHub — source of this documentation