---
title: "Rank areas nationally or within a scope"
method: GET
path: "/api/v1/rankings"
tags: ["Rankings"]
---

# Rank areas nationally or within a scope

`GET /api/v1/rankings`

## Request

- Base URL: `https://suomiatlas.com`
- URL: `https://suomiatlas.com/api/v1/rankings`
- Auth: one of:
  - none
  - HTTP bearer

Orders areas by any metric, optionally scoped to a municipality, a region, or a radius around a place.

**Free-tier limit:** `limit` is capped at **10** rows without Pro and 100 with it. Asking for 50 as a free caller returns 200 with 10 rows and a `locked` entry for `entries` (`requires: pro`). No `locked` key means the list is complete — you asked for 10 or fewer, or fewer rows than the cap exist.

**Composite metrics are paid:** `gentrification`, `family_prevalence`, `vitality` and `affluence` return **402** without Pro.

**Deprecated code:** `family_friendliness` was renamed to `family_prevalence` on 2026-09-29 because the old name asserted a judgement its components do not make. The old code is still accepted on `/rankings`, `/variable-values` and `/variable-years` and returns identical results; responses always carry `family_prevalence`.

**Crime and air-quality metrics change the unit of analysis.** For the four crime rates (`crime_total_rate`, `crime_violent_rate`, `crime_property_rate`, `crime_narcotics_rate`) and the four air-quality annual means (`aq_pm25_avg`, `aq_pm10_avg`, `aq_no2_avg`, `aq_o3_avg`, µg/m³, the median over each municipality's monitoring stations), municipalities are ranked rather than postal areas — both are published only at municipality level. The response shape is unchanged, so `entries[].postalCode` then carries a **3-digit municipality code** and `entries[].name` a municipality name. The `kunta` and `maakunta` filters are ignored for these metrics; `near`/`withinKm` measures to municipality centres. For air quality `order=bottom` lists the cleanest municipalities first — the same order and figures as `/api/v1/air-quality/kunta-ranking` — and `order=top` the most polluted; `percentile` is then the share of municipalities with a lower concentration. A municipality with no served station is absent from the list, which means unmeasured, not clean.

**`percentile` is a position, not a verdict.** It says where a value sits in the distribution, nothing about whether that position is good.

Example request: https://suomiatlas.com/api/v1/rankings?variableCode=hr_mtu&year=2024&limit=10

## Query parameters

- `variableCode` string, required
- `year` integer, required
- `order` 'top' | 'bottom' | 'balance'
- `limit` integer
- `kunta` string
- `maakunta` string
- `near` string
- `withinKm` number, double

## Response `200`

The ranking, capped as described above.

- Ranking
  - `variableCode` string, required
  - `year` integer, required
  - `order` 'top' | 'bottom' | 'balance', required
  - `entries` RankingEntry[], required: **At most 10 rows without Pro**, whatever `limit` asked for; when that cut rows, `locked` names `entries`.
    - `rank` integer, required: 1-based, within the scope requested.
    - `postalCode` string, required: A 5-digit postal code — **except for the four `crime_*_rate` metrics, where it is a 3-digit municipality code**, because crime is ranked by municipality.
    - `name` string, required: Area name, or municipality name for crime metrics.
    - `value` number, double, required
    - `percentile` number, double, nullable, required: Mid-rank position within the *scoped* distribution, so a scoped ranking's percentiles are not national ones.
    - `distanceKm` number, double: Absent unless a radius was requested. Straight-line, rounded to 0.1 km.
  - `origin` RankingOrigin: The place a radius was measured from.
    - `code` string, required
    - `name` string, required
    - `kind` 'postal_area' | 'municipality', required
  - `withinKm` number, double: Absent unless `near` was supplied.
  - `locked` LockedField[]: Absent — the key is missing, not an empty array — when nothing was withheld for this caller. May name: `entries` (`requires: pro`).
    - `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
  - `scope` 'pks' | 'hr14': Absent for a national variable. Present when the variable exists only for this region: ranks and percentiles are then within it, and `kunta` must be one of its municipalities (`maakunta` is rejected).
  - `scopeLabel` string: The region's English name; absent with `scope`.

## Other responses

- `400`: A parameter was missing, malformed, or outside what this operation accepts. The message names the parameter.
- `402`: This data needs a paid entitlement. **Note the different body shape** — `error`, not `code`/`message`. There is no 401 or 403 anywhere in this API: an anonymous caller is a valid caller with fewer entitlements.

---

[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)