---
title: "Per-year series for composite scores and trend metrics"
method: GET
path: "/api/v1/postal-codes/{postalCode}/derived-history"
tags: ["Areas"]
---

# Per-year series for composite scores and trend metrics

`GET /api/v1/postal-codes/{postalCode}/derived-history`

## Request

- Base URL: `https://suomiatlas.com`
- URL: `https://suomiatlas.com/api/v1/postal-codes/{postalCode}/derived-history`
- Auth: one of:
  - none
  - HTTP bearer

The history behind `/composites` and `/trends`: up to 10 years per metric, index-aligned to `years`.

**Paid outright.** Without Pro or an Area Pass for this exact area the whole request is rejected with **402**, and that check runs *before* the area is looked up — so an unknown postal code also answers 402 to a free caller rather than 404. Do not read a 402 here as evidence the area exists. `/history` tells such a caller in advance, via a `derivedHistory` entry in its `locked` list, that this endpoint will answer 402; an entitled caller may still get 404 for an area with no derived rows.

Example request: https://suomiatlas.com/api/v1/postal-codes/00120/derived-history

## Path parameters

- `postalCode` string, required

## Response `200`

Derived series.

- DerivedHistory
  - `postalCode` string, required
  - `years` integer[], required: Ascending, at most 10.
  - `series` object, required: Composite id or trend metric code to values, index-aligned to `years`.
  - `names` StringMap, required
  - `units` StringMap, required

## Other responses

- `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.
- `404`: No such place, or no data for it. Also what a non-numeric `year` produces, because query-parameter conversion fails before the operation runs.

---

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