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, a user filling out one checkout address) and remain the same for calls to both methods.

The X-Autocomplete-Session HTTP session header should be at least 8 characters and at most 64 characters long. The value must only contain alphanumeric characters (case insensitive), "-", "_" and/or ".".

Reusing the same session identifier for completing more than one address is not recommended as it may lead to increased 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.

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:

• Austria
• Belgium
• France
• Germany
• Luxembourg
• Spain
• Switzerland
• The Netherlands
• United Kingdom

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}

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

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

{
    "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"
    },
    "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
        }
    }
}