---
title: "Composite scores for one postal code area"
method: GET
path: "/api/v1/postal-codes/{postalCode}/composites"
tags: ["Areas"]
---

# Composite scores for one postal code area

`GET /api/v1/postal-codes/{postalCode}/composites`

## Request

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

Four composite indices, each 0–100 with a national rank: `gentrification`, `family_prevalence`, `vitality` and `affluence`.

**Free-tier limit:** the headline `score`, `rank` and `total` are free, but without Pro or an Area Pass for this exact area every `components[].percentile` is **null** while `metric`, `name` and `weight` remain, and `locked` names `composites[].components[].percentile` (`requires: area-pass`). So the factors behind a score are named but not quantified. A caller with access sees real percentiles there.

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

## Path parameters

- `postalCode` string, required

## Query parameters

- `year` integer

## Response `200`

Composite scores, components possibly redacted.

- CompositeScores
  - `postalCode` string, required
  - `year` integer, required
  - `composites` CompositeScore[], required
    - `id` 'gentrification' | 'family_prevalence' | 'vitality' | 'affluence', required
    - `name` string, required
    - `version` integer, required: The scoring formula's version.
    - `score` number, double, nullable, required: 0–100.
    - `rank` integer, nullable, required: 1 is highest, out of `total`. Null when the area has no score.
    - `total` integer, required: How many areas have a score for this composite.
    - `components` ComponentBreakdown[], required
      - `metric` string, required
      - `name` string, required
      - `percentile` number, double, nullable, required: **Null for callers without Pro or an Area Pass for this area** — withheld, not unknown; the response's `locked` names `composites[].components[].percentile` when that happened.
      - `weight` number, double, required: This component's share of the score.
  - `locked` LockedField[]: Absent — the key is missing, not an empty array — when nothing was withheld for this caller. May name: `composites[].components[].percentile` (`requires: area-pass`).
    - `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

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