# Suomiatlas > Suomiatlas is a statistics atlas of Finland: income, population, education, > employment, housing, crime and air-quality data for every Finnish postal code > area (~3,000) and municipality, built on official Statistics Finland (Paavo) > and Finnish Meteorological Institute open data, plus four 0–100 composite > scores built from those variables — Suomiatlas's own interpretation of them, > not official statistics. The statistics are CC BY 4.0; the map's nearby > places add Digitransit (CC BY 4.0), the Suomi.fi service catalogue (CC0 1.0), > OpenStreetMap (ODbL 1.0) and LIPAS (CC BY 4.0) — see /api/v1/license for > machine-readable attribution. ## Content - [Sitemap](https://suomiatlas.com/sitemap.xml): every postal-code area page (`/alue/-`), municipality page (`/kunta/`), and national ranking page (`/sijoitukset/`) — static HTML with the full stat tables, not JavaScript-rendered. - [Metric guide](https://suomiatlas.com/mittarit): what every published metric counts, when Statistics Finland withholds it, and the reading of it that most often goes wrong — grouped exactly as `/api/v1/variables` groups them (also [in English](https://suomiatlas.com/en/metrics)). Start here before quoting a figure: several of these variables are routinely misread. - [MCP server docs](https://suomiatlas.com/mcp): how to connect an AI assistant to this data as a live tool (also `/en/mcp`, `/sv/mcp`). - [About the data](https://suomiatlas.com/tietoa): sources, how each figure is computed, and the documented limits of the data — what it cannot tell you (also `/en/about`, `/sv/om`). Carries `Dataset` schema.org metadata. ## MCP server Model Context Protocol server at `https://suomiatlas.com/api/mcp` (Streamable HTTP), hosted — nothing to install. No authentication required for free-tier data; an API key sent as `Authorization: Bearer sk_live_...` (minted in an account's API keys panel) unlocks that account's Pro entitlements or Area Pass. Tools: `search_places` (name → code), `get_place_stats` (pass `includeCompositeScores` for the four 0–100 scores), `get_place_history`, `get_air_quality`, `get_nearby_places` (stops and services inside one postal area, or with `withinKm` the nearest within a few km of it), `compare_areas`, `rank_areas`, `find_similar_areas`, `list_variables`, `get_area_report` (PDF download link for one area, Pro or Area Pass). Resources: `suomiatlas://license`, `suomiatlas://variables`. Every REST response that withheld something for the caller's tier carries a `locked` array naming the field and whether Pro or an Area Pass for that one area lifts it (`requires`) — those fields are paywalled, not missing, and a response without `locked` withheld nothing. The MCP tools pass the same list through. ## API Read-only JSON API at `https://suomiatlas.com/api/v1/`, no authentication required for free-tier data. The full machine-readable contract — every endpoint, parameter, response schema and free-tier cap — is an OpenAPI 3.0 document at [https://suomiatlas.com/openapi.json](https://suomiatlas.com/openapi.json), suitable for a ChatGPT Custom GPT action or any schema-driven agent. The endpoints most callers need are below. Every URL is absolute and directly fetchable as written — substitute your own code or year. Postal codes are 5 digits, municipality codes 3. - `GET https://suomiatlas.com/api/v1/search?q=kallio&limit=5` — resolve a place name to a code (`kind` = `postal_area`, `municipality` or `region`). Diacritic-insensitive, so `q=toolo` finds Töölö. Every other endpoint takes codes, so start here. - `GET https://suomiatlas.com/api/v1/postal-codes` — bulk GeoJSON export of all postal code areas (optionally scoped to one municipality via `?kunta=091`). - `GET https://suomiatlas.com/api/v1/kunta/091/stats` — one municipality's statistics: inhabitants, crime rates, housing sale price medians, its postal areas. - `GET https://suomiatlas.com/api/v1/postal-codes/00120/stats?year=2024` — one area's statistics, national/regional percentiles. - `GET https://suomiatlas.com/api/v1/postal-codes/00120/history` — full time series for one area. - `GET https://suomiatlas.com/api/v1/postal-codes/00120/composites?year=2024` — the four composite scores for one area, each 0–100 with a national rank: `gentrification`, `family_prevalence`, `vitality`, `affluence`. These are Suomiatlas's own indices, not official statistics — the weighting is ours, so attribute them to Suomiatlas, not to Statistics Finland. Every response names each component and its weight, and [/mittarit](https://suomiatlas.com/mittarit) covers what the scores are and how they are meant to be read. Score and rank are free; the per-component `percentile` is withheld without Pro or an Area Pass, coming back `null` with a `locked` entry naming it. Ranking the whole country by a composite answers 402 without Pro: `https://suomiatlas.com/api/v1/rankings?variableCode=family_prevalence&year=2024`. `total` is that composite's scored cohort, smaller than the ~3,000 areas and different between composites: an area is left out where a variable the score needs is withheld. - `GET https://suomiatlas.com/api/v1/rankings?variableCode=hr_mtu&year=2024&order=top&limit=10` — national or regional rankings by any metric, including crime rates (variableCode `crime_total_rate`, `crime_violent_rate`, `crime_property_rate`, `crime_narcotics_rate`) and air quality (`aq_pm25_avg`, `aq_pm10_avg`, `aq_no2_avg`, `aq_o3_avg`; `order=bottom` is cleanest first) — both ranked by municipality, not postal area. `order` is `top` (highest first, the default), `bottom` (lowest first), or `balance` (closest first to the metric's target value). `balance` applies only to a metric that has a target — today `gender_balance_20_39`, whose target is an even 1.0 — and is an error on any other metric. Percentiles in the response are plain value ranks: they say where a value sits in the distribution, not whether that position is good. - `GET https://suomiatlas.com/api/v1/stats?postalCodes=00120,00180` — side-by-side comparison of multiple areas. - `GET https://suomiatlas.com/api/v1/postal-codes/00120/air-quality` — nearest-station air quality (PM2.5, PM10, NO2, O3) for one postal area. - `GET https://suomiatlas.com/api/v1/kunta/091/air-quality` — median air quality across a municipality's stations. - `GET https://suomiatlas.com/api/v1/air-quality/kunta-ranking?pollutant=aq_pm25_avg&year=2024` — municipality ranking by pollutant. - `GET https://suomiatlas.com/api/v1/variables` — catalog of every available metric, incl. crime and air quality. - `GET https://suomiatlas.com/api/v1/postal-codes/00530/pois` — transit stops, daycare centres, schools, higher and further education, health and medical centres, pharmacies, supermarkets, libraries, swimming pools and beaches inside one postal area (a beach at the water's edge, just outside every area, is listed under the postal code LIPAS gives it, within 500 m). Add `?withinKm=2&categories=SWIMMING_POOL,BEACH` for the places within 2 km of the area's boundary too, nearest first, with `distanceKm` (straight-line, not travel distance; up to 5 km). - `GET https://suomiatlas.com/api/v1/license` — machine-readable data licence and source attribution, per source. Crime and air-quality figures are also embedded directly in `/api/v1/postal-codes/{code}/stats` (crime block) and in the prerendered `/alue/*` and `/kunta/*` pages — no separate call needed if you're already fetching an area's or municipality's stats page. ## Reuse The statistics are CC BY 4.0, from four sources — attribute the original publisher when reusing or citing figures from this site: - Income, population, education, employment, housing (Paavo) — Statistics Finland (Tilastokeskus). - Dwelling sale prices per m² (ashi) — Statistics Finland (Tilastokeskus). - Crime rates (reported offences, rpk) — Statistics Finland (Tilastokeskus). - Air quality — Finnish Meteorological Institute (FMI). The nearby places on the map have their own licences: - Public transport stops — Digitransit, CC BY 4.0. - Daycare centres — the Suomi.fi service catalogue (Palvelutietovaranto, Digital and Population Data Services Agency), CC0 1.0. OpenStreetMap fills in where the catalogue has no daycare within 250 m. - Kindergartens, schools, higher and further education, health and medical centres, pharmacies, supermarkets and libraries — © OpenStreetMap contributors, ODbL 1.0 (https://opendatacommons.org/licenses/odbl/1-0/). The database built from them, the daycare layer included, is available under ODbL 1.0. - Swimming pools and beaches — LIPAS, the national register of sports facilities (Jyväskylän yliopisto, Lipas Liikuntapaikat.fi), CC BY 4.0. See `/api/v1/license` for the exact attribution text and per-source links; for the four nearby-places sources it also describes how the database was derived from them.