Rank areas nationally or within a scope
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
Request
- Base URL: https://suomiatlas.com
- URL: https://suomiatlas.com/api/v1/rankings
- Auth: one of:
- none
- HTTP bearer
Query parameters
Any code from /api/v1/variables, a crime rate code, or an air-quality code (aq_pm25_avg, aq_pm10_avg, aq_no2_avg, aq_o3_avg — these four are not listed by /variables). Missing or blank is a 400. An unknown code is not an error: it returns an empty ranking, so check /api/v1/variable-years first.
Missing is a 400. Not range-checked: an implausible year returns an empty ranking rather than an error. A non-numeric value is a 404.
top is highest first, bottom lowest first, balance closest first to the metric's target value. balance is valid only for a metric that has a target — today that is gender_balance_20_39 alone, whose target is an even 1.0 — and is a 400 for any other metric.
Below 1 is a 400. Above 100 is silently clamped to 100, and above 10 is silently clamped to 10 for a free caller.
Rank only within this municipality. Takes precedence over maakunta, which is then ignored entirely. Not format-checked here. Ignored for municipality-grain metrics (crime, air quality), which always rank the whole country.
Rank only within this region. Ignored when kunta is also given, and for municipality-grain metrics (crime, air quality).
A postal code or municipality code to measure from. Must be given together with withinKm — one without the other is a 400. An unknown code is a 400.
Radius around near, in kilometres. Must be finite and greater than 0. Straight-line ground distance, not travel time; distances are rounded to 0.1 km.
Response
The ranking, capped as described above.
Example response
{
"locked": [
{
"upgrade": "https://suomiatlas.com/hinnat"
}
]
}Changes
No recorded changes to this operation across all 1 revision of this API.