# Norwegian Postal Codes API

> Queryable HTTP/JSON API over Norwegian postal codes (5790 entries). No authentication. Source: Erik Bolstad's dataset.

Base URL: https://postalcodes.trydig.io

All responses are JSON unless otherwise noted. All endpoints are `GET`.

## Data shape

Every postal-code entry has the following fields:

- `code` (string): 4-digit postal code, zero-padded (e.g. "0001").
- `city` (string): Postal town (POSTSTAD). Original casing preserved.
- `lat` (number | null): Latitude in WGS84 decimal degrees. `null` if missing in source.
- `lon` (number | null): Longitude in WGS84 decimal degrees. `null` if missing in source.

## Endpoints

### GET /list

Returns every postal code in the dataset as a JSON array of entries.

Example:

```
curl https://postalcodes.trydig.io/list
```

Response: `Entry[]` (~5790 items, ~365 KB).

### GET /code/:postalCode

Look up a single entry by exact postal code. The path parameter must match the 4-digit code exactly (zero-padded).

- `200` with `Entry` if found.
- `404` with `{"error":"not found"}` if no match.

Example:

```
curl https://postalcodes.trydig.io/code/0001
{"code":"0001","city":"Oslo","lat":59.9116,"lon":10.7545}
```

### GET /list/city/:city

Returns all postal codes whose city (POSTSTAD) matches the given name. Matching is case-insensitive but otherwise exact (no fuzzy matching, no partial matches).

- `200` with `Entry[]` if at least one match.
- `404` with `{"error":"not found"}` if no match.

Example:

```
curl https://postalcodes.trydig.io/list/city/Bergen
```

### GET /nearest

Returns the top N nearest postal codes to a given coordinate, ordered by ascending distance. Distance uses the Haversine formula over a spherical Earth (R = 6371 km).

Query parameters:

- `lat` (number, required): Latitude in decimal degrees.
- `long` (number, required): Longitude in decimal degrees. Alias `lon` is also accepted; if both are present, `long` wins.
- `length` (integer, optional): Number of results to return. Range 1–5, default 5. Values outside the range are clamped.

Each result extends `Entry` with a `distanceKm` field (number, kilometres).

Errors:

- `400` with `{"error":"lat and long (or lon) query params required"}` if either coord is missing or non-numeric.

Example:

```
curl "https://postalcodes.trydig.io/nearest?lat=59.91&long=10.75&length=3"
```

## Notes for agents

- Postal codes must be passed as zero-padded 4-character strings ("0001", not "1").
- Entries with `null` coordinates are excluded from `/nearest` ranking but still returned by `/list`, `/code/:postalCode`, and `/list/city/:city`.
- The dataset is bundled into the worker and read-only. There are no write endpoints.
- Caching is not currently set via response headers; clients may cache responses freely as the dataset changes rarely (manual rebuild on source updates).