---
title: "Air quality across one municipality"
method: GET
path: "/api/v1/kunta/{kuntaCode}/air-quality"
tags: ["Air quality"]
---

# Air quality across one municipality

`GET /api/v1/kunta/{kuntaCode}/air-quality`

## Request

- Base URL: `https://suomiatlas.com`
- URL: `https://suomiatlas.com/api/v1/kunta/{kuntaCode}/air-quality`
- Auth: one of:
  - none
  - HTTP bearer

The median reading across every station in a municipality, with `kuntaProvenance` naming the stations behind it instead of the single-station `provenance`. Same `data`-or-`gap` rule per pollutant as the area endpoint.

**Free-tier limit, Pro-only** — an Area Pass covers one postal code and cannot cover a municipality: every `data.series` is emptied, while the latest reading and benchmarks stay, and `locked` names `pollutants[].data.series` with `requires: pro`.

Example request: https://suomiatlas.com/api/v1/kunta/091/air-quality

## Path parameters

- `kuntaCode` string, required

## Response `200`

Air quality, series possibly emptied.

- AirQuality
  - `areaCode` string, nullable, required: The postal code asked for; null on the municipality endpoint.
  - `kuntaCode` string, required
  - `kuntaName` string, required
  - `pollutants` PollutantBlock[], required: All four pollutants, always present: aq_pm25_avg, aq_pm10_avg, aq_no2_avg, aq_o3_avg.
    - `code` 'aq_pm25_avg' | 'aq_pm10_avg' | 'aq_no2_avg' | 'aq_o3_avg', required
    - `unit` string, required
    - `benchmarks` AirQualityBenchmarks, nullable, required: Reference limits for this pollutant, for saying whether a reading is high.
      - `who2021` number, double, required
      - `euLimit` number, double, required
      - `eu2030` number, double, required
    - `data` AirQualityData, nullable, required
      - `latest` AirQualityYearValue, required
        - `year` integer, required
        - `value` number, double, required
      - `series` AirQualityYearValue[], required: **Empty without Pro or an Area Pass for this area** — withheld, not unmeasured, and the response's `locked` names `pollutants[].data.series` when that happened. An empty `series` with no `locked` entry is genuinely empty. `latest` stays populated either way.
        - `year` integer, required
        - `value` number, double, required
    - `provenance` StationProvenance, nullable, required: Which station the reading came from. Quote the distance: a reading from 25 km away describes the region, not the street.
      - `fmisid` integer, required: The FMI station identifier.
      - `name` string, required
      - `distanceKm` number, double, required
      - `tier` 'local' | 'regional', required
    - `kuntaProvenance` KuntaProvenance, nullable, required
      - `stations` StationRef[], required
        - `fmisid` integer, required
        - `name` string, required
      - `stationCount` integer, required
    - `gap` AirQualityGap, nullable, required: Why this pollutant has no reading. Present exactly when `data` is null — and it means no station is close enough, never that the air is clean.
      - `reason` 'TOO_FAR' | 'NO_STATION', required: `TOO_FAR`: a station exists but is beyond the threshold. `NO_STATION`: none measures this pollutant at all.
      - `nearestStation` string, nullable, required: Null when `reason` is NO_STATION.
      - `distanceKm` number, double, nullable, required
      - `maxKm` number, double, nullable, required: The threshold applied: 15 km for NO2 and PM10, 30 km otherwise.
  - `locked` LockedField[]: Absent — the key is missing, not an empty array — when nothing was withheld for this caller. May name: `pollutants[].data.series` (`area-pass` on the postal endpoint, `pro` on the municipality endpoint).
    - `field` string, required: Path into this response, e.g. `entries`, `years`, `series.housing_*`, `pollutants[].data.series`, `composites[].components[].percentile`.
    - `requires` 'pro' | 'area-pass', required: `pro`: only a Pro subscription lifts it. `area-pass`: Pro, or an Area Pass for this exact postal code.
    - `reason` string, required: One sentence naming what is withheld. Always ends "The data exists — it is withheld, not missing."
    - `upgrade` string, uri, required

## Other responses

- `404`: No such place, or no data for it. Also what a non-numeric `year` produces, because query-parameter conversion fails before the operation runs.

---

[API](https://skmtc.dev/suomiatlas/apis/suomiatlas-read-api.md) · [All operations](https://skmtc.dev/suomiatlas/apis/suomiatlas-read-api/llms.txt) · [OpenAPI document](https://skmtc.dev/suomiatlas/apis/suomiatlas-read-api/revisions/b2627414938d?raw)