API — powietrze z paczkomatów

API tylko do odczytu, JSON. Wymaga klucza — wysyłaj go w nagłówku X-API-Key (albo w parametrze ?api_key=). Klucz wydaje administrator strony; każdy klucz ma własny limit zapytań na minutę i może zostać unieważniony. Dane odświeżane są co ok. godzinę, więc pytanie częściej niż co 10–15 minut nic nie daje.

curl -H "X-API-Key: alm_…" https://air-locker-map.studio-colorbox.com/api/v1/sensors/KAP02M

Bez klucza: 401, zły lub unieważniony klucz: 403, przekroczony limit: 429. Sama mapa na stronie głównej jest publiczna.

Źródło: nieoficjalne odczyty czujników z paczkomatów InPost, stacje GIOŚ jako odniesienie. Projekt hobbystyczny, bez gwarancji dostępności. Kod: github.com/szmidtpiotr/air-locker-map.

Endpointy

Adres	Co zwraca
`GET /api/v1/stats`	Statystyki całego kraju: liczba czujników, mediany, rozkład klas, województwa, trend.
`GET /api/v1/sensors`	Wszystkie działające czujniki. Opcje: `province=mazowieckie`, `include_suspect=true`.
`GET /api/v1/sensors/{kod}`	Jeden czujnik, np. `/api/v1/sensors/KAP02M`.
`GET /api/v1/sensors/{kod}/history?hours=24`	Surowe odczyty (do 90 dni wstecz).
`GET /api/v1/sensors/{kod}/daily?days=30`	Dzienne średnie i maksima (trzymane bezterminowo).
`GET /api/v1/nearest?lat=52.27&lon=20.46&n=5`	Najbliższe działające czujniki do punktu, z odległością.
`GET /api/v1/lockers/{kod}/nearest?n=5`	Najbliższe czujniki do dowolnego paczkomatu (także bez czujnika), np. `KAP01M`.

Przykład odpowiedzi czujnika

{
  "name": "KAP02M", "address": "Niepokalanowska 2B, 05-085 Kampinos",
  "lat": 52.27, "lon": 20.46, "elevation": 86, "distance_m": 564,
  "updated": 1790871312, "status": "ok", "level": "VERY_GOOD",
  "measurements": { "pm1": 3.7, "pm25": 5.4, "pm4": null, "pm10": 6.2,
                    "pressure": 1029.1, "pressure_sl": 1029.1, "humidity": 59, "temperature": 20.3 },
  "suspect": false, "flags": []
}

pressure_sl — ciśnienie zredukowane do poziomu morza (porównywalne między miastami); pressure — surowe z czujnika.
temperature i humidity mierzone są w obudowie paczkomatu — w słońcu temperatura bywa mocno zawyżona.
suspect: true + flags — czujnik wygląda na zepsuty (zawieszony, zalany, nierealny odczyt, odstaje od sąsiadów). Domyślnie takie czujniki są pomijane.
updated, changed — czas uniksowy ostatniego odczytu i ostatniej zmiany wartości.

Home Assistant — najbliższy czujnik do domu

Do configuration.yaml (albo do pakietu). Bierze współrzędne strefy zone.home i co 15 minut pobiera najbliższy działający czujnik. Jeśli najbliższy się zepsuje, API samo poda następny. W sieci domowej możesz zamiast domeny wpisać adres lokalny serwera.

rest:
  - resource_template: >-
      https://air-locker-map.studio-colorbox.com/api/v1/nearest?n=1&lat={{ state_attr('zone.home', 'latitude') }}&lon={{ state_attr('zone.home', 'longitude') }}
    scan_interval: 900
    headers:
      X-API-Key: !secret air_locker_map_key
    sensor:
      - name: "Paczkomat PM2.5"
        unique_id: paczkomat_pm25
        value_template: "{{ value_json.sensors[0].measurements.pm25 }}"
        unit_of_measurement: "µg/m³"
        device_class: pm25
        state_class: measurement
        json_attributes_path: "$.sensors[0]"
        json_attributes: [name, address, distance_m, updated, flags]
      - name: "Paczkomat PM10"
        unique_id: paczkomat_pm10
        value_template: "{{ value_json.sensors[0].measurements.pm10 }}"
        unit_of_measurement: "µg/m³"
        device_class: pm10
        state_class: measurement
      - name: "Paczkomat PM1"
        unique_id: paczkomat_pm1
        value_template: "{{ value_json.sensors[0].measurements.pm1 }}"
        unit_of_measurement: "µg/m³"
        device_class: pm1
        state_class: measurement
      - name: "Paczkomat ciśnienie"
        unique_id: paczkomat_cisnienie
        value_template: "{{ value_json.sensors[0].measurements.pressure_sl }}"
        unit_of_measurement: "hPa"
        device_class: atmospheric_pressure
        state_class: measurement

Zamiast YAML-a możesz użyć gotowej integracji HACS: github.com/szmidtpiotr/ha-air-locker-map.

W secrets.yaml: air_locker_map_key: alm_…. Konkretny paczkomat zamiast „najbliższego”: resource: https://…/api/v1/sensors/KAP02M i value_template: "{{ value_json.measurements.pm25 }}".