LocAPI
Documentation menu

Suggest

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

Suggestions for what the user has typed so far, best first. Show the label; when the user picks one, resolve its id.

Parameters#

ParameterRequiredDescription
countrystringyesISO 3166-1 alpha-2 code of a supported country, e.g. DE.
qstringyesWhat the user typed: 3 to 200 characters after whitespace normalisation.
postalCodestringnoA filter, not a ranking hint: only suggestions with exactly this postal code.
limitintegernoNumber of suggestions, 1 to 10. Default 5.

Example#

curl -G "https://api.locapi.eu/v1/address/suggest" \
  -H "X-Api-Key: $LOCAPI_API_KEY" \
  --data-urlencode "country=DE" \
  --data-urlencode "q=Unter den Linden 77"
Response · 200
{
  "outcome": "found",
  "requestId": "req_0192b0c4-…",
  "results": [
    {
      "id": "adr_v1_…",
      "label": "Unter den Linden 77, 10117 Berlin",
      "precision": "building",
      "address": {
        "street": "Unter den Linden",
        "houseNumber": null,
        "houseNumberAddition": null,
        "postalCode": null,
        "city": "Berlin",
        "municipality": null,
        "region": null,
        "countryCode": "DE",
        "location": null
      }
    }
  ],
  "attribution": []
}

Response fields#

Response

outcomestring
found or not_found. Both are HTTP 200.
requestIdstring
The id of this request, also in the X-Request-Id header. Quote it when you contact us.
resultsSuggestion[]
The suggestions, best first. Empty when not_found.
attributionAttribution[]
Credits the source requires for this response. Show them where the licence asks for it; can be empty.

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.

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

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#

StatuscodeMeaning
400invalid_requestInvalid request
401invalid_api_keyInvalid API key
402payment_requiredPayment required
403account_blockedAccount blocked
422country_not_supportedCountry not supported
429fair_use_exceededFair use exceeded
429quota_exceededFree allowance used
429rate_limit_exceededRate limit exceeded
429spend_cap_reachedMonthly spend cap reached
503source_unavailableAddress source temporarily unavailable

Good to know#

  • Not billed. Where every address is paid for, each call counts towards your fair-use allowance (2,000 suggestions a month, plus 20 for every billed address).
  • Call it only after the user pauses typing (250–300 ms), and not twice for the same text.
  • A suggestion in a paid-only country carries only street, city and countryCode; the full address comes from resolve.
  • not_found is HTTP 200 with an empty results.