Get address details

Get address information based on the provided autocomplete context. The context must have the precision `address`. A HTTP status 400 response is given when the provided context does not resolve to a single address.

This method is intended to provide address information using the result context from the autocomplete method. The result of this method can be used to complete an address in an order form for example.

Required session header

Both the autocomplete and getDetails methods require a custom HTTP header named X-Autocomplete-Session to be specified. Its value should identify a single address completion session (for example, one user filling out a checkout address) and remain the same for calls to both methods. You should not generate a new session identifier for each request, or reuse the same identifier for completing more than one address.

The value should be at least 8 characters and at most 64 characters long and contain only alphanumeric characters, "-", "_" and/or ".".

For example, our Javascript library generates a new random session header value of 32 hexadecimal characters each time a new autocomplete HTML input element is created. This session header value is used for the lifespan of that element, and is passed to the server-side proxy which forwards it to the Autocomplete API as an X-Autocomplete-Session session header.

Please ensure the session header is implemented correctly. Incorrect usage of this header will lead to increased API costs for your account.

The term and context parameters

Both the term and context parameters determine what results are suggested. They must be used correctly in order to prevent bugs in your implementation. For example, when a user selects a suggestion the next set of results might not contain the desired results.

First, make sure to correctly encode your parameters.

Secondly, make sure to provide the correct term parameter for a given context.
The autocomplete provides matches based on the current input. In order to select a match and drill down further, another call to the autocomplete method should be performed. For example, a user enters a street name and then selects the top suggestion to see specific addresses for that street. For the second call to the autocomplete: specify the context of the selected match, and use the 'value' of the selected match for the term parameter. Do not modify the value, or strip off any white-space. If the term parameter does not match the specified context, the drill down will not work as intented.

Address response

The response address can be found in the address struct split into the following fields: country, locality, street, postcode, building (formatted building number and building name), buildingNumber (can be null) and buildingName (can be null). In most countries the building number can be null, usually the building name is not null in this case, but there are a few addresses where both building number and building name are null.

Address struct without number and name

...
"address": {
	"country": "Germany",
	"locality": "Mittenwalde",
	"street": "Gelände Märchenwiese",
	"postcode": "15749",
	"building": "",
	"buildingNumber": null,
	"buildingNumberAddition": null
}
...

Country specific data

Countries have different address information and administrative regions, any country specific information can be found in the "details" property. The data provided per country can be found here:

URL template

The REST API requires GET requests. Parameters are added to the REST resource URL, and each parameter must be URL-encoded:

https://api.postcode.eu/international/v1/address/{context}/{dispatchCountry}

Example REST request

Retrieving /international/v1/address/bel6SVBbpsiriOTHIBOu9LISmTCTzVymIt8qTaveozBbMHLPzZPhaKDwTsP3z64fhxMDVxyuquqSVebBGFPdvNlruQet2oZxo8fuKEwzv1rDfBNRHcZwLxThfR9rovJwW7Yqu2Gu0ZPFHobgkC56R with the proper authentication would use the following HTTP Request:

GET /international/v1/address/bel6SVBbpsiriOTHIBOu9LISmTCTzVymIt8qTaveozBbMHLPzZPhaKDwTsP3z64fhxMDVxyuquqSVebBGFPdvNlruQet2oZxo8fuKEwzv1rDfBNRHcZwLxThfR9rovJwW7Yqu2Gu0ZPFHobgkC56R HTTP/1.1
Host: api.postcode.eu
Authorization: Basic 2eTpkU******…
X-Autocomplete-Session: f60c42561f8f5a6d7cc

Example response

The lookup is successful so we receive a 200 OK status in the headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

And a JSON response in the body:

{
    "language": "nl-BE",
    "address": {
        "country": "Belgium",
        "locality": "Antwerpen",
        "street": "Steenstraat",
        "postcode": "2180",
        "building": "1 bus 3",
        "buildingNumber": 1,
        "buildingNumberAddition": "bus 3"
    },
    "mailLines": [
        "Steenstraat 1 bus 3",
        "2180 Antwerpen"
    ],
    "location": {
        "longitude": 4.4173496469527205,
        "latitude": 51.277946183550426,
        "precision": "Address"
    },
    "isPoBox": false,
    "country": {
        "name": "Belgium",
        "iso3Code": "BEL",
        "iso2Code": "BE"
    },
    "details": {
        "belRegion": {
            "nisCode": 2000,
            "primaryName": "Vlaanderen",
            "nlName": "Vlaanderen",
            "frName": "Flandre",
            "deName": "Flandern",
        },
        "belProvince": {
            "nisCode": 10000,
            "primaryName": "Antwerpen",
            "nlName": "Antwerpen",
            "frName": "Anvers",
            "deName": "Antwerpen",
        },
        "belDistrict": {
            "nisCode": 11000,
            "primaryName": "Antwerpen",
            "nlName": "Antwerpen",
            "frName": "Anvers",
            "deName": "Antwerpen",
        },
        "belMunicipality": {
            "nisCode": 11002,
            "primaryName": "Antwerpen",
            "nlName": "Antwerpen",
            "frName": "Anvers",
            "deName": "Antwerpen",
            "officialLanguages": [
                "nl"
            ]
        },
        "belStreet": {
            "primaryName": "Steenstraat",
            "nlName": "Steenstraat",
            "frName": null,
            "deName": null
        },
        "belBuilding": {
            "number": 1,
            "bisNumber": null,
            "boxNumber": "3",
            "validated": true
        }
    }
}

Parameters

context: string

Context with precision address to get detailed address information.

dispatchCountry: string or null

Dispatching country ISO3 code, used to determine country address line presence. If not given, country is not added in mailLines.

Returns

language: string

Language of the matched address, derived from context or falls back to default.

address: struct

Address information for the contexts address.

Hide child parameters
country: string

Country name of the of postal address in English.

locality: string

Name of primary locality used in postal address.

street: string

Name of primary street used in postal address.

postcode: string

Postcode used in postal address.

building: string

Number and possible addition of the building in the postal address. (United Kingdom: multiple lines are comma separated)

buildingNumber: int or null

Building number of the postal address. Or null if not available.

buildingNumberAddition: string or null

Building number addition of the postal address, if available. (United Kingdom: multiple lines are comma separated)

mailLines: string[]

List of address lines as they should appear in an address space. The country name is included when a dispatchCountry parameter is provided which does not correspond with the address country.

location: struct or null

WGS-84 coordinates for the address if available, null otherwise.

Hide child parameters
latitude: double

Latitude coordinate.

longitude: double

Longitude coordinate.

precision: string

Precision of location. One of "Address", "Street", "PostalCode", "Locality"

isPoBox: boolean

Indicates if the address is a Post Office box

country: struct

Country information

Hide child parameters
name: string

The country name

iso3Code: string

The ISO 3166-1 Alpha-3 code for the country

iso2Code: string

The ISO 3166-1 Alpha-2 code for the country

details: struct

Country specific details about the address. The available details differ per country but can contain such things as country specific identifiers, official street name translations, administrative regions and an indication whether the full house number could be validated.