Rank Finnish areas by a metric
rank_areasRank Finnish postal areas by any metric — highest or lowest income, population, unemployment, education, housing prices — nationally or within one municipality or region. Crime rates (crime_total_rate and friends) and air quality (aq_pm25_avg, aq_pm10_avg, aq_no2_avg, aq_o3_avg — annual means in µg/m³) rank municipalities instead, since both are published only at that grain; the aq_ codes are not in list_variables, pass them directly. For air quality order="bottom" gives the cleanest municipalities first and order="top" the most polluted, so "which municipality has the cleanest air?" is rank_areas with aq_pm25_avg and order="bottom" — get_air_quality answers for one place only. A municipality absent from an air-quality or crime ranking has no published value there: report it as unmeasured, never as clean or safe. A null in additionalValues means that metric is unpublished for that area, not zero. For gender_balance_20_39 the useful question is usually which areas are closest to an even split, not which are most skewed: pass order="balance" for that, since both a high and a low ratio mean imbalance. Get valid metric codes from list_variables. near plus withinKm narrows the ranking to areas within a straight-line radius of another place. That is distance over the ground, never a travel or commute time. To screen areas on several metrics at once — "above-average family share and below-average housing prices" — rank by one metric and pass the rest as includeVariables; that is a single call. Do not call get_place_stats per area to collect a second metric.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| near | No | Keep only areas within `withinKm` of this place — a postal area or municipality, by name or code, e.g. "Tampere", "00100". Distance is centre to centre in a straight line. | |
| year | No | Year; defaults to the newest with data. | |
| limit | No | Rows to return, 1–100 (default 10). | |
| order | No | Highest first (default), lowest first, or — for a metric whose ideal value is a specific number rather than an extreme — closest to that value first. "balance" is currently valid only for gender_balance_20_39, whose target is an even 1.0; asking for it on any other metric is an error. For aq_* metrics "bottom" is cleanest first. | |
| scope | No | Limit to one municipality or region by name or code, e.g. "Espoo", "Uusimaa". Not applicable to crime or air-quality rankings, which are national lists of municipalities — use `near` + `withinKm` to narrow those. | |
| withinKm | No | Radius in kilometres around `near`. Required with `near`, and only with it. | |
| variableCode | Yes | Metric code from list_variables, e.g. "hr_mtu", "unemployment_rate", or an air-quality code such as "aq_pm25_avg". | |
| includeVariables | No | Extra metric codes to report for each ranked area, as `additionalValues` on every row. Each metric's own year is given in `includedVariables`, since the sources run to different years. Not available for municipality-grain rankings (crime, air quality). |