Address guide

Two ways to get a verified address: autocomplete while your user types, or a lookup by postal code and house number. Both end with one complete, canonical address that you store in your own system.

Autocomplete: suggest, then resolve#

While the user types, send their text to suggest. You get up to 10 suggestions, each with a label to show and an id.
When the user picks one, send its id to resolve. You get the full address.
Store the address. An id is valid for 24 hours and is not a lasting reference.

Where every address is paid for (today: every supported country), a suggestion carries only the street, city and country, with the full label to show; the complete address comes from resolve. That is also the moment the address is billed.

Lookup: postal code and house number#

lookup takes a postal code and a house number (with an addition if there is one) and answers with one of three outcomes, all HTTP 200:

found: exactly one address. It is billed.
multiple: LocAPI cannot prove one unique address, so it gives one or more candidates to confirm. For example 23, 23A and 23-1 when you gave no addition, or a single address when the street you sent could also be read as another street at that postal code. A candidate is never a confirmed match, not even the only one: show it, and resolve the one the user picks or confirms; that is when it is billed.
not_found: the source answered and nothing matched. Not billed.

Lookup is available in 14 countries:

Netherlands: postal code and house number are enough.
Belgium, Switzerland, Czechia, Germany, Denmark, Estonia, Spain, France, Italy, Lithuania, Latvia, Slovenia, Slovakia: also send street, because one postal code covers several streets there. Without it the answer is 400.

Outcomes and failures#

not_found means the lookup was done and nothing usable came out. When a source is down or too slow (the budget is 1 s for suggest and 2 s for resolve and lookup), the answer is 503 source_unavailable, never not_found. Treat the two differently: a 503 is worth a retry, a not_found is not.

The address#

Every country answers in the same shape: street, houseNumber, houseNumberAddition, houseName, locality, postalCode, city, municipality, region, countryCode and an optional location. A field is only filled when the source provides it; nothing is guessed. The postal code always comes from the source, never from what the user typed.

houseName is the name a register gives a house instead of a number. Such an address has no houseNumber: a name is never a number, not even a name of digits. In a country whose register names houses, a lookup takes houseName instead of houseNumber.

city is the postal city. locality is the village or settlement the address belongs to, where the source names one. Where a house number belongs to a village rather than a street, street is empty and the village takes its place in the label: Mezgovci ob Pesnici 15, 2252 Dornava. To look such an address up, give the village as street. A street address in a village that the postal city does not name has the village after the street: Na vasi 22, Voglje, 4208 Šenčur.

Slovakia numbers every building twice: a conscription number for the building and, on a street, an orientation number for the entrance. The address carries the one the post writes: Einsteinova 35, Bratislava-Petržalka, 851 01 Bratislava or, without a street, Pernek 114, 900 53 Pernek. A lookup takes the orientation number, or both as 21/35; without a street, the part of the municipality or the municipality is the street.

Czechia writes an address as its law prescribes, with both numbers and the part of the municipality: Studentská 1903/14a, Dejvice, 160 00 Praha 6. A building without a street, in a part named like the municipality, is its number with the mark: č.p. 3, 743 01 Tísek and č.ev. 3, 743 01 Tísek are two buildings. A lookup takes both numbers, the orientation number alone on a street, or the marked number.

Latvia writes an address as its register does, and its register names many houses instead of numbering them: on the land a house has a name and no street. The address then has houseName and no houseNumber, and the label is the register’s own line, with the name in quotation marks: "Riņņi", Vecates pag., Valmieras nov., LV-4211. A lookup takes houseName, with the village, city or parish as street; a name of digits may also be given as houseNumber. On a street the letter and the building part are the addition: Jumaras iela 195 k-1, Valmiera, Valmieras nov., LV-4201. city is the city, or else the parish; the postal code may be given as LV-4211, LV4211 or 4211. Latvia’s register also has the addresses of building plots and planned addresses: an address found there is an officially assigned address, not proof that a building stands.

Lithuania writes an address in the order its register uses: the municipality (left out in its own centre), the eldership for a village, the settlement, the street with its type, the number and the postal code: Varėnos r. sav., Matuizų sen., Voriškių k., Eglyno g. 20, LT-65467, and in a city Kaunas, Savanorių pr. 120 K5, LT-44148. The letter and the building part are the addition: 120 with K5. city and locality are the settlement: a city or town in the nominative, any other settlement in the genitive with its type (Voriškių k.). Without a street, give the settlement as street, as written or in the nominative (Senosios Būdos k. or Senoji Būda). A street type may be written out or abbreviated: Eglyno gatvė and Eglyno g. are the same street. Two addresses that only the eldership tells apart are both candidates, each with its own label. The postal code may be given as LT-44148, LT44148 or 44148.

Estonia writes an address as its register does, from the county down, and the label is that line with the postal code after it: Harju maakond, Tallinn, Kesklinna linnaosa, P. Süda tn 4, 10119. In the countryside most houses have a farm name and no street or number: the address then has houseName and no houseNumber, as in Rapla maakond, Kohila vald, Urge küla, Nigula, 79743; a name with a number is one name: Uuetalu/3. On a street the letter and a second number are the addition: 476 with /1. city is the settlement as the register writes it (Urge küla, Tartu linn); in a district of Tallinn or Kohtla-Järve it is the city, with the district as locality, and a small place or garden cooperative is the locality. Without a street, give the small place, the district or the settlement as street. A street or place type may be written out or abbreviated: Pärnu maantee and Pärnu mnt are the same street. Two farm names that only an Estonian letter tells apart (Saare and Sääre) are both candidates, each with its own label.

Denmark writes an address as its register does: the street, the number with its letter, the supplementary town name where there is one, and the postal code with its place: Pragtstjernevej 2, Tørring, 7620 Lemvig. city is the place of the postal code and locality the supplementary town name; the register gives no municipality name, so municipality is empty. A letter after the number is the addition: 10 with K. A street may also be given by its official short addressing name, as it is written on mail: Sdr Hostr Østergade finds Sønder Hostrup Østergade, and the answer has the street name. Two streets whose names only an accent tells apart (Astrupvej and Åstrupvej) are both candidates where both have the number.

France writes an address as La Poste does, and a lookup’s label is put together from the register’s parts in that order: the number with its repetition index and the street, the former commune where the address has one, the commune where the post names another place, and the postal code with its place: 20 Boulevard Maréchal Juin, Antibes, 06160 JUAN LES PINS. city is 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. locality is the former commune of a merged commune and municipality the commune. The repetition index is the addition, as the register writes it: 42 with bis. B and bis are different additions: the register has both at some numbers. A street may also be given in the post’s capital form (RUE DU MAL DE LATTRE DE TASSIGNY); the answer has the street name. One postal code often covers several communes: the same street and number in two of them are both candidates, each with its own label. Lookup covers metropolitan France, Corsica and the five overseas departments; suggestions keep France’s own notation.

Precision#

precision says how exact an address is: building, street, postal_area or unknown. A house number only appears at building precision. A lookup only returns buildings.

Labels#

The label is the address on one line, in the country’s own notation. Show it as it is; to use the parts, read address, never parse the label.

Street 12A, Postcode City: Austria, Belgium, Switzerland, Czechia, Germany, Spain, Finland, Croatia, Hungary, Italy, Netherlands, Norway, Slovenia, Slovakia
Street 12A, Supplementary town, Postcode City (the register's own line): Denmark
County, Municipality, Settlement, Street 12a, Postcode (the register's full address): Estonia
12A Street, Postcode City: France, Luxembourg
12A Street, City Postcode: United Kingdom
Municipality, Eldership, Settlement, Street 12A, Postcode (the register's order): Lithuania
Street 12A, City, Municipality, Postcode (the register's own line): Latvia

Attribution#

Some sources require a credit. Each response lists them in attribution; show them where the source’s licence asks for it. The list can be empty.

Where the credit is that of an official register, the address is the register’s, with only these changes: coordinates converted to WGS84, the postal code written with its space, and the house number written as the country’s rules prescribe. In Lithuania the fields and the label are put together from the register’s parts, in the order its law prescribes. In Estonia the label is the register’s full address with the postal code after it. In Denmark it is the register’s own designation; where that lacks the street, the same parts in the same order. In France the label is put together from the register’s parts, in the order La Poste writes an address.