GIOŚ smart home integration, free and open source
Air quality of the official Polish GIOŚ stations: index and pollutants, hour by hour.
Published by guim31
- Devices
- Version 1.0.0
- Requires Gladys >=5.2.0
- ★ 0
The air quality measured by the official stations of GIOŚ, the Polish Chief Inspectorate of Environmental Protection (Główny Inspektorat Ochrony Środowiska): the Polish air quality index and the pollutants, station by station, hour by hour.
Not affiliated with GIOŚ. The data come from its open API
(api.gios.gov.pl), used as GIOŚ publishes it.
What it does
- Reads the GIOŚ stations you choose (10 at most), with no account and no key.
- Creates one device per station: the Polish air quality index (0 to 5) and its level as a word, the pollutants the station measures (PM2.5, PM10, NO₂, O₃, SO₂, CO, benzene) and the age of the data.
- Adds a GIOŚ air quality dashboard widget, two scene triggers (air quality degraded, back to normal) and a scene action Get the air quality.
- Finds a station by its name or city, or the nearest ones to your house.
Read only: the integration only reads public data.
Requirements
- Gladys Assistant 5.2.0 or later.
- Internet access from Gladys to
api.gios.gov.pl. - To search around your house: its location, in Settings → Houses.
Configuration
Choose the stations
- Open the integration's Configuration tab.
- Click Find a station: type a name or a city (
Kraków,Gdansk: accents are optional), or leave it empty to list the stations nearest to your house, with their distance. - Copy the numbers you want into Stations, separated by commas: for
example
530, 401. Save. - In the Discovery tab, add the stations to Gladys.
The map of the stations shows them all.
Other settings
- Refresh: every 30 minutes (default) or every hour. GIOŚ publishes hourly averages, a little after each hour: reading more often would bring nothing.
- Language: language of the feature names (set when a device is added, so choose it first) and of the scene texts. French by default.
The Check the stations button reads every station now and tells what each one answers.
Devices
One device per station, named GIOŚ <station>.
| Feature | Values |
|---|---|
| Air quality index | 0 to 5 (Polish index, below) |
| Air quality | the level as a word, in your language |
| PM2.5, PM10, NO₂, O₃, SO₂, CO, C₆H₆ | µg/m³, hourly average |
| Measurement age | minutes since the hour of the latest data |
Only the pollutants the station measures are created. CO and benzene have no dedicated type in Gladys in µg/m³: they appear as plain values, named by their formula.
The Polish air quality index (Polski indeks jakości powietrza) has six levels: 0 Very good (Bardzo dobry), 1 Good (Dobry), 2 Moderate (Umiarkowany), 3 Sufficient (Dostateczny), 4 Bad (Zły), 5 Very bad (Bardzo zły). It is computed by GIOŚ from PM2.5, PM10, NO₂, O₃ and SO₂; the worst one sets it.
A value older than 3 hours is no longer published as current: Gladys keeps the last one with its date, and the widget says the data are outdated.
Widget
GIOŚ air quality:
- with a station chosen: up to four pollutant tiles, the index level colored (green, orange, red) and the age of the data;
- without: one row per station, its level colored.
Scenes
Trigger: GIOŚ: air quality degraded
Fires when the index of a station rises to Moderate or worse, or gets worse again (Moderate then Bad fires twice). Filters: the station, and the new level: tick the levels from your threshold up (for example Bad and Very bad). Information for the actions: station name, level, its index, the previous index, the pollutant that sets the level, a ready-made summary.
Trigger: GIOŚ: air quality back to normal
Fires when the index comes back to Good or Very good after a degradation. Filters: the station, and the worst level the degradation reached (tick the same levels as above to pair both scenes). Information: the new level, the worst level reached, a summary.
The first index read after the installation sets the starting level and fires nothing; a restart does not fire the same change twice.
Action: GIOŚ: get the air quality
The air quality of one station, or of the station with the worst index: summary, level, index, pollutant, PM2.5, PM10, NO₂, O₃ and the age of the data, for the next actions (a message, a condition).
Scene examples
- Close the windows: trigger air quality degraded with the levels Bad and
Very bad → send
{{triggerEvent.data.summary}}and switch the ventilation off. - Air again: trigger back to normal with the same levels → send "You can open the windows again".
- Morning briefing: at 7:30, action get the air quality without station, then send its summary in the morning message.
- Purifier: when the PM2.5 feature of your station goes above 25 µg/m³, switch the air purifier on.
Troubleshooting
- "No station yet" on the Configuration screen: type at least one station number in Stations.
- "not a GIOŚ station" in the check: the number is not in the GIOŚ list; use Find a station.
- No PM2.5 on a station that measures it: some stations only have a manual PM2.5 sensor, whose results GIOŚ publishes weeks later. Only the automatic, hourly sensors are read.
- "The GIOŚ API does not answer": the values are kept and read again at the next refresh. The Logs tab tells the error once, and its end.
- Air quality index without value: GIOŚ gives no index for this hour ("Brak indeksu"), for example after a measurement outage.
- Details in the integration's Logs tab (
LOG_LEVEL=debugfor more).
Limits
- Hourly data, published by GIOŚ a little after each hour: the last hour is often still missing, and the values lag by 1 to 2 hours.
- These are measurements, not forecasts.
- GIOŚ limits its API (1500 requests per minute on the current data, 2 per minute on the station list): the integration reads 10 stations at most, one request per pollutant, and the station list once a day.
- The index triggers follow GIOŚ's hourly index as published: an index that hesitates between two levels fires each change.
Configuration settings
These are the settings GIOŚ asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Polish air quality stations | section | No | Reads the official measuring stations of GIOŚ, the Polish Chief Inspectorate of Environmental Protection, through its open API (no account). Not affiliated with GIOŚ. |
| Stations | string | No | The numbers of the GIOŚ stations to read, separated by commas (10 at most). The "Find a station" button below gives them, by name or around a house. |
| Refresh | select | No | GIOŚ publishes hourly averages, a little after each hour. |
| Language | select | No | Language of the feature names (set when a device is added) and of the scene texts. |
How to install GIOŚ in Gladys
- In Gladys, open Integrations: GIOŚ appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-gios:1.0.0), 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/guim31/gladys-gios.
GIOŚ requires Gladys >=5.2.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
GIOŚ 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 guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation