# POST /v1/addresses/lookup

> Index: https://kartpunkt.se/llms.txt

operationId: `lookupAddress`. One address by its id.
Tag: `addresses`.

The address one stored id names, as served now or at as_of: the id an earlier answer gave you, which is Lantmäteriet's own object identity of the address (se.lm.…), not Kartpunkt's. One id per call. A closed id is 404 address_closed, an id this key's dataset never held 404 address_unknown. To check many stored ids at once, use POST /v1/addresses/changes.

## Request

`POST https://api.kartpunkt.se/v1/addresses/lookup` with `Authorization: Bearer $KARTPUNKT_API_KEY` and `Content-Type: application/json`, from your backend (never browser code: the key would leak, and CORS is not enabled).

Example body:

```json
{
  "id": "se.syn.syn-0000t9b"
}
```

JSON body:

- `id` (string, max 100 chars, pattern `^se\.(lm|syn)\.[A-Za-z0-9-]{1,80}$`, required): One address id, as an earlier answer's id gave it: 'se.lm.' and Lantmäteriet's object identity of the belägenhetsadress for a kp_live_ key, 'se.syn.' and a code for a kp_test_ key. A street hit's id ('street:…') names no address.
- `as_of` (string, date-time (RFC 3339, with offset), optional): The version of the address served at this instant (RFC 3339 with offset), e.g. when your decision was made, so the same call answers the same again; left out, or later than now, the version served now. Not more than 24 months back: versions are kept that long.

## Response 200

Example:

```json
{
  "address": {
    "id": "se.syn.syn-0000t9b",
    "type": "address",
    "label": "Östra Ågatan 12B, 757 97 Uppsala",
    "street": "Östra Ågatan",
    "number": 12,
    "letter": "B",
    "postcode": "75797",
    "locality": "Uppsala",
    "municipality_code": "0380",
    "municipality": "Uppsala",
    "county_code": "03",
    "county": "Uppsala län",
    "district_code": "903801",
    "district": "Uppsala norra",
    "point": {
      "lat": 59.92238511056452,
      "lon": 17.582745460249157
    },
    "position_type": "entrance",
    "match_type": null,
    "score": 1
  },
  "provenance": {
    "synthetic": true,
    "sources": [
      {
        "id": "synthetic",
        "name": "Kartpunkt synthetic test addresses",
        "licence": "CC0-1.0",
        "attribution": "Syntetiska testadresser från Kartpunkt, inte verkliga adresser.",
        "url": "https://creativecommons.org/publicdomain/zero/1.0/",
        "updated": "2026-10-13",
        "as_of": "2026-10-13T07:00:00.000Z"
      }
    ]
  }
}
```

- `address` ([Address](https://api.kartpunkt.se/docs/shapes/Address.md)): The address the id names, as served at the instant read (score 1, match_type null: no words were sent).
- `provenance` ([Provenance](https://api.kartpunkt.se/docs/shapes/Provenance.md))

## Errors

Every error is `{ error, message, param?, doc_url }`; `message` says what to do next. All codes: [https://api.kartpunkt.se/errors](https://api.kartpunkt.se/errors). What to do on each, with retries: [https://api.kartpunkt.se/docs/recipes/errors-and-retries.md](https://api.kartpunkt.se/docs/recipes/errors-and-retries.md).

- [`invalid_request`](https://api.kartpunkt.se/errors/invalid_request) (400): The request does not match the API schema. Fix the fields named in this message; see /openapi.json.
- [`unauthorized`](https://api.kartpunkt.se/errors/unauthorized) (401): Missing or unknown API key. Send it as 'Authorization: Bearer <key>' (or 'x-api-key'), read from the KARTPUNKT_API_KEY environment variable. The user creates a kp_test_ key on their Kartpunkt account page (https://kartpunkt.se/konto) and puts it in KARTPUNKT_API_KEY themselves; never ask them to paste a key into chat.
- [`live_access_required`](https://api.kartpunkt.se/errors/live_access_required) (403): This account is not approved for live data: kp_live_ keys are for customers under contract. Use a kp_test_ key. To ask for live access, the account holder writes to hej@kartpunkt.se, or orders a plan at https://kartpunkt.se/konto#plan.
- [`use_not_permitted`](https://api.kartpunkt.se/errors/use_not_permitted) (403): This operation would use a data source in a way its licence or approval does not allow (see GET /v1/sources). It cannot be answered for this key.
- [`address_closed`](https://api.kartpunkt.se/errors/address_closed) (404): This address id is not served on the date asked (as_of, else now): a delivery of the register closed it (the address was removed from the register, or is no longer current there). The register names no successor, so find the address again with POST /v1/addresses/validate or POST /v1/geocode and store the new id; mark the old one closed rather than deleting it, since the register can serve the same id again. For the version served before it closed, send as_of an instant when it was served.
- [`address_unknown`](https://api.kartpunkt.se/errors/address_unknown) (404): No version of this address id in this key's dataset on the date asked. It was never issued, is past the 24 months of history kept, opened only after as_of, or is the other dataset's (a kp_test_ key reads only synthetic se.syn. ids, a kp_live_ key only Lantmäteriet's se.lm. ids). Send an id an earlier answer of this key gave; after going live, look your addresses up again with the kp_live_ key.
- [`quota_exceeded`](https://api.kartpunkt.se/errors/quota_exceeded) (429): Request limit or plan quota reached (per minute, per day, or the account plan's monthly quota). Wait the number of seconds in the Retry-After header, then retry; without Retry-After, no wait helps: tell the account holder what this message says.
- [`internal_error`](https://api.kartpunkt.se/errors/internal_error) (500): Something failed on our side. Retry after a few seconds; if it keeps failing, contact hej@kartpunkt.se.
- [`live_data_unavailable`](https://api.kartpunkt.se/errors/live_data_unavailable) (503): Live data is not available yet: it opens when Kartpunkt's import of Lantmäteriet's address register completes. Use a kp_test_ key until then.

## Limits

| Limit | Synchronous |
| --- | --- |
| Request body | 1 MB |

## Metering

With a `kp_live_` key, one live call per request; each address in the answer counts toward the plan's daily address limit.