---
title: "Compare several postal code areas side by side"
method: GET
path: "/api/v1/stats"
tags: ["Areas"]
---

# Compare several postal code areas side by side

`GET /api/v1/stats`

## Request

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

One column per area, grouped by metric group, with national benchmarks shared across the columns.

**Free-tier limit:** a free caller's list is **truncated to the first 2 areas**. Passing 5 codes returns 200 with 2 columns and a `locked` entry for `areas` (`requires: pro`) whose `reason` names the 3 dropped codes. Pro allows 12.

Asking for more than 12 is a 400 for everyone. Duplicates are removed, caller order preserved. `asOf` appears for metrics whose latest published year lags the year you asked for, so a single response can mix vintages — label them.

Example request: https://suomiatlas.com/api/v1/stats?postalCodes=00120,00180

## Query parameters

- `postalCodes` string, required
- `year` integer

## Response `200`

The comparison, possibly truncated to 2 columns.

- AreaComparison
  - `year` integer, required
  - `groups` ComparisonGroup[], required: Metric groups and their members, in display order.
    - `groupName` string, required
    - `variables` VariableRef[], required
      - `code` string, required
      - `name` string, required
  - `nationalMedians` NullableNumberMap, required: Metric code to value. A key may be present with a null value — Statistics Finland suppresses figures resting on too few people or dwellings.
  - `nationalBenchmarkBasis` StringMap, required
  - `nationalBenchmarkCoverage` NullableNumberMap, required: Metric code to value. A key may be present with a null value — Statistics Finland suppresses figures resting on too few people or dwellings.
  - `asOf` object, required: Present only for metrics whose latest published year lags the requested one — so a single response can mix vintages. Label those rows rather than presenting one year.
  - `areas` AreaColumn[], required: One column per area. **Truncated to 2 without Pro**; `locked` then names `areas` and its `reason` lists the codes that were dropped.
    - `postalCode` string, required
    - `name` string, required
    - `values` NullableNumberMap, required: Metric code to value. A key may be present with a null value — Statistics Finland suppresses figures resting on too few people or dwellings.
    - `percentiles` NullableNumberMap, required: Metric code to value. A key may be present with a null value — Statistics Finland suppresses figures resting on too few people or dwellings.
  - `locked` LockedField[]: Absent — the key is missing, not an empty array — when nothing was withheld for this caller. May name: `areas` (`requires: pro`; the `reason` lists the dropped codes).
    - `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

- `400`: A parameter was missing, malformed, or outside what this operation accepts. The message names the parameter.

---

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