---
title: "One metric's value for every area"
method: GET
path: "/api/v1/variable-values"
tags: ["Metadata"]
---

# One metric's value for every area

`GET /api/v1/variable-values`

## Request

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

Every postal code area's value for a single metric and year — roughly 3,000 entries, intended for painting a choropleth. For the question "which areas score highest", `/api/v1/rankings` is the better fit.

**Composite metrics are paid:** a composite code returns **402** without Pro. Everything else, including crime and dwelling prices, is free. Nulls are Statistics Finland suppression, not withholding.

Example request: https://suomiatlas.com/api/v1/variable-values?variableCode=hr_mtu&year=2024

## Query parameters

- `variableCode` string, required
- `year` integer, required

## Response `200`

Postal code to value.

- VariableValues
  - `variableCode` string, required
  - `year` integer, 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.

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