Lookup

GEThttps://api.locapi.eu/v1/address/lookup

The address at a postal code and house number. The answer is found, multiple or not_found, all HTTP 200.

Parameters#

Parameter	Required	Description
`country`string	yes	ISO 3166-1 alpha-2 code of a country with lookup (see Countries).
`postalCode`string	yes	The full postal code, at most 10 characters. Spaces and case do not matter. In Latvia LV-4211, LV4211 and 4211 are the same postal code; in Lithuania likewise LT-44148, LT44148 and 44148.
`houseNumber`string	yes	The house number, optionally with its addition (23, 23A, 35/1, 31.1); at most 10 characters. Slovakia numbers every building twice: give the orientation number of the entrance (35, 48A), or both with the conscription number first (21/35). Without a street, give the conscription number. Czechia writes both as its law prescribes: give 1903/14a, the orientation number alone on a street (14a), or the building's number with its mark (č.p. 3, č.ev. 3). Latvia writes a building part after the number: give 195 k-1. A Latvian house name of digits (28) may be given here too; the answer has it as houseName. Lithuania writes the building part after the number with a K: give 120 K5 or 12A K2. Estonia writes a small letter and a second number after it: give 16a, 476/1 or 1a/1. Denmark writes a capital letter after the number: give 10K. France writes the repetition index after the number: give 42 bis or 58B; B and bis are different addresses.
`houseNumberAddition`string	no	The addition, when it is not in houseNumber (A, 1, bis). Compared on letters and digits: -1, /1 and 1 are the same.
`street`string	some countries	Required where one postal code covers several streets (see Countries); without it the answer is 400. When given, a filter: candidates on another street are left out. Where an address has no street but belongs to a village, give the village: the answer still has no street, and the village is its locality. In Slovakia and Czechia that may also be the municipality. In Latvia, for an address without a street, give the village, the city or the parish (Vecates pag., also Vecates pagasts), never the municipality. In Lithuania, for an address without a street, give the settlement as written or in the nominative (Senosios Būdos k., Senoji Būda), never the eldership or the municipality; a street type may be written out (Eglyno gatvė) or abbreviated (Eglyno g.). In Estonia, for an address without a street, give the small place, the city district or the settlement (Koiduvalguse AÜ, Järve linnaosa, Urge küla); a street or place type may be written out (Pärnu maantee, Koiduvalguse aiandusühistu) or abbreviated (Pärnu mnt). In Denmark the street name or its official short addressing name (Sønder Hostrup Østergade or Sdr Hostr Østergade); the answer has the street name. In France the street name or the post's capital form of it (Rue du Maréchal De Lattre De Tassigny or RUE DU MAL DE LATTRE DE TASSIGNY); the answer has the street name.
`city`string	no	A refinement that can help the source; not a filter. At most 100 characters.
`houseName`string	some countries	Instead of houseNumber, where a country's register names a house rather than numbering it: the house's name, with or without its quotation marks; accents, case and quotation marks do not matter. Not together with houseNumber or houseNumberAddition; in a country without house names the answer is 400. A name of digits only may also be given as houseNumber. Latvia's register names many houses on the land: "Riņņi" or Riņņi. Estonia's register names most farms (Nigula); a name with a number is one name (Uuetalu/3).

Example#

curl -G "https://api.locapi.eu/v1/address/lookup" \
  -H "X-Api-Key: $LOCAPI_API_KEY" \
  --data-urlencode "country=NL" \
  --data-urlencode "postalCode=3011 AD" \
  --data-urlencode "houseNumber=40"

Response · 200

{
  "outcome": "found",
  "requestId": "req_0192b0c4-…",
  "result": {
    "id": "adr_v1_…",
    "label": "Coolsingel 40, 3011 AD Rotterdam",
    "precision": "building",
    "address": {
      "street": "Coolsingel",
      "houseNumber": "40",
      "houseNumberAddition": null,
      "postalCode": "3011 AD",
      "city": "Rotterdam",
      "municipality": null,
      "region": null,
      "countryCode": "NL",
      "location": {
        "latitude": 51.9227229,
        "longitude": 4.4792039
      }
    },
    "retrievedAt": "2026-09-28T20:58:10Z"
  },
  "results": [],
  "attribution": []
}

Example with several candidates (multiple)

Response · 200 · multiple

{
  "outcome": "multiple",
  "requestId": "req_0192b0c4-…",
  "result": null,
  "results": [
    {
      "id": "adr_v1_…",
      "label": "Stadsplateau 1, 3521 AZ Utrecht",
      "precision": "building",
      "address": {
        "street": "Stadsplateau",
        "houseNumber": null,
        "houseNumberAddition": null,
        "postalCode": null,
        "city": "Utrecht",
        "municipality": null,
        "region": null,
        "countryCode": "NL",
        "location": null
      }
    },
    {
      "id": "adr_v1_…",
      "label": "Stadsplateau 1-BD, 3521 AZ Utrecht",
      "precision": "building",
      "address": {
        "street": "Stadsplateau",
        "houseNumber": null,
        "houseNumberAddition": null,
        "postalCode": null,
        "city": "Utrecht",
        "municipality": null,
        "region": null,
        "countryCode": "NL",
        "location": null
      }
    }
  ],
  "attribution": []
}

Response fields#

Response

outcomestring: found (exactly one address, proven unique), multiple (one or more candidates to confirm) or not_found. All are HTTP 200.
requestIdstring: The id of this request, also in the X-Request-Id header.
resultResolvedAddress | null: The address when found; otherwise null.
resultsSuggestion[]: The candidates when multiple (one to 10); otherwise empty. A candidate is never a confirmed match: pick or confirm one and resolve its id.
attributionAttribution[]: Credits the source requires for this response; can be empty.

`ResolvedAddress` object

idstring: The id you resolved; from a found lookup, one you can resolve later without being billed again.
labelstring: The full address as one line, in the country's own notation.
precisionstring: How exact the address is. A lookup only returns building.
addressAddress: The address parts.
retrievedAtstring: When the source answered (UTC).

`Address` object

streetstring | null: Street name, as the source writes it. Null where the house number belongs to a village rather than a street (see locality).
houseNumberstring | null: House number, without the addition. In Slovakia the number the post writes: the orientation number on a street, otherwise the conscription number. In Czechia as the law writes it: 1903/14 (the orientation number's letter is the addition), or č.ev. 3 for an evidence number.
houseNumberAdditionstring | null: Addition to the house number (A, 1, bis), normalised; in Czechia the lower-case letter the law prescribes (14a); in Latvia the letter, a second number and the building part as the register writes them (A, /13, k-1); in Lithuania the letter and the building part (A, K5, A K2); in Estonia the lower-case letter and a second number as the register writes them (a, /1, a/1); in Denmark the capital letter (K); in France the repetition index as the register writes it (bis, ter, B), where B and bis are different additions.
houseNamestring | null: The house's name, where the register names the house instead of numbering it (Latvia, on the land: Riņņi; Estonia, a farm: Nigula, or a name with a number as one name: Uuetalu/3); houseNumber is then null. Null for an address with a number. A name is never a number, even a name of digits only.
localitystring | null: The village or settlement the address belongs to, where the source names one (Slovenia: the naselje). Not the postal city: Mezgovci ob Pesnici 15 has the postal city Dornava. A name in two official languages reads "Slovenian / Italian". In Estonia the small place or garden cooperative (Koiduvalguse AÜ), else the city district (Kesklinna linnaosa). In Denmark the supplementary town name (Tørring). In France the former commune of a merged commune (Saint-Denis-du-Béhélan).
postalCodestring | null: Postal code from the source, never copied from your input.
citystring | null: The postal city, not a district. Slovakia's register has none; there it is the municipality, as the post allows, and Bratislava or Košice for their boroughs. In Prague, the district the law adds: Praha 6. Latvia has no separate postal city: there it is the city, or else the parish (Vecates pag.). In Lithuania the settlement as the post writes it: a city or town in the nominative (Kaunas), any other settlement in the genitive with its type (Voriškių k.); locality is the same settlement. In Estonia the settlement as the register writes it (Urge küla, Tartu linn); in a city district the city (Tallinn). In Denmark the place of the postal code (Lemvig, København K). In France the postal place: the commune's name where the post names the commune, the city of an arrondissement (Paris), else the post's own place as it writes it (JUAN LES PINS).
municipalitystring | null: Municipality, when the source provides a name. In Latvia the novads (Valmieras nov.), or the state city itself (Rīga). In Lithuania as the law writes it (Varėnos r. sav.). In Estonia the rural or city municipality (Kohila vald, Tallinn). In Denmark empty: the register gives only a code. In France the commune (Antibes); in Paris, Lyon and Marseille the arrondissement (Paris 2e Arrondissement).
regionstring | null: Region or state, when the source provides it.
countryCodestring: ISO 3166-1 alpha-2.
locationLocation | null: Latitude and longitude (WGS84), when the source provides them.

`Location` object

latitudenumber: Degrees north (WGS84).
longitudenumber: Degrees east (WGS84).

`Suggestion` object

idstring: Opaque id to pass to resolve. Valid for 24 hours; store the address, not the id.
labelstring: The full address as one line, in the country's own notation.
precisionstring: How exact the suggestion is: building, street, postal_area or unknown.
addressAddress: The address parts. Where every address is paid for (paid_only), only street, city and countryCode; the rest comes from resolve.

`Attribution` object

textstring: The credit line to show.
urlstring | null: Where the credit links to, if anywhere.
licensestring | null: The licence identifier, if the source names one.

Errors#

Status	code	Meaning
400	`invalid_request`	Invalid request
401	`invalid_api_key`	Invalid API key
402	`payment_required`	Payment required
403	`account_blocked`	Account blocked
422	`country_not_supported`	Country not supported
429	`fair_use_exceeded`	Fair use exceeded
429	`quota_exceeded`	Free allowance used
429	`rate_limit_exceeded`	Rate limit exceeded
429	`spend_cap_reached`	Monthly spend cap reached
503	`source_unavailable`	Address source temporarily unavailable

Good to know#

found is billed. multiple and not_found are not; with multiple, resolve the candidate the user picks, and that is billed.
Available in 14 countries. Where one postal code covers several streets, street is required and filters the candidates. See Countries and sources.
Without an addition, every addition at that number is a candidate: 23, 23A and 23-1 give multiple.
multiple means the address could not be proven unique; it can carry a single candidate, for example when the street you sent also names another street at that postal code. A candidate is never a confirmed match: confirm it with resolve.
Candidates in a paid-only country carry only street, city and countryCode, with the full label.