---
title: "Nearby places in one postal code area"
method: GET
path: "/api/v1/postal-codes/{postalCode}/pois"
tags: ["Nearby places"]
---

# Nearby places in one postal code area

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

## Request

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

Transit stops (bus, tram, metro, train, ferry) from Digitransit; daycare centres from the Suomi.fi service catalogue (PTV); services (kindergartens, schools, higher and further education, health clinics, pharmacies, supermarkets, libraries) from OpenStreetMap; and swimming pools (indoor halls and open-air pools) and beaches (public beaches and smaller swimming sites) from LIPAS, the national register of sports facilities, located inside the area's boundary. The one exception is a LIPAS beach whose point falls just into the water, outside every postal area: it is listed under the postal code LIPAS gives it when that area's boundary is within 500 m.

A stop that serves several modes appears once per mode. `name` is null when the source has none, which is common for OpenStreetMap objects. Daycares (`KINDERGARTEN`) come first from PTV: an OpenStreetMap kindergarten is listed only when no PTV daycare lies within 250 m of it, in this area or the next. Health clinics cover public health centres and private medical centres alike: OpenStreetMap does not tell them apart reliably. `HIGHER_EDUCATION` covers universities, universities of applied sciences and vocational colleges; folk high schools and adult-education centres are left out. Coverage varies by municipality, so a missing daycare or school here does not mean the area has none.

**Within a radius.** With `withinKm` (up to 5 km) the list also holds places outside the area within that straight-line distance of its boundary, nearest first per category, each with `distanceKm` (0 inside the area), `inArea` (the place belongs to this area) and `postalCode`; `countsWithin` gives each category's full count before `limitPerCategory`. It is distance over the ground, not a walking or travel distance.

`sources` says when each source was last retrieved. Transit data is CC BY 4.0 (Digitransit), PTV data CC0 1.0, LIPAS data CC BY 4.0 (University of Jyväskylä, Lipas Liikuntapaikat.fi); the OpenStreetMap-derived data, the served daycare layer included, is ODbL 1.0 — see `/api/v1/license`. Free, no account needed. An area with nothing in it returns an empty `pois` array.

Example request: https://suomiatlas.com/api/v1/postal-codes/00530/pois

## Path parameters

- `postalCode` string, required

## Query parameters

- `withinKm` number
- `categories` string
- `limitPerCategory` integer

## Response `200`

The area's points of interest.

- PoiList
  - `pois` Poi[], required
    - `category` 'BUS' | 'TRAM' | 'METRO' | 'TRAIN' | 'FERRY' | 'KINDERGARTEN' | 'SCHOOL' | 'HIGHER_EDUCATION' | 'HEALTH_CLINIC' | 'PHARMACY' | 'SUPERMARKET' | 'LIBRARY' | 'SWIMMING_POOL' | 'BEACH', required
    - `name` string, nullable, required: Null when the source has no name.
    - `lat` number, required
    - `lon` number, required
    - `source` 'digitransit' | 'osm' | 'ptv' | 'lipas', required
    - `postalCode` string: Radius search only: the postal area the place belongs to.
    - `inArea` boolean: Radius search only: true when the place belongs to the requested area, even if it sits just outside the boundary (a beach at the water's edge).
    - `distanceKm` number: Radius search only: straight-line distance to the requested area's boundary in km, 0 inside it, to 0.01 km.
  - `sources` PoiSourceStamp[], required
    - `source` 'digitransit' | 'osm' | 'ptv' | 'lipas', required
    - `retrievedAt` string, date-time, required
  - `countsWithin` object: Radius search only: per category, the served places (after the daycare merge) in the area or within the radius, before limitPerCategory.

## Other responses

- `400`: A parameter was missing, malformed, or outside what this operation accepts. The message names the parameter.
- `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)