Autocomplete an address

Get a list of autocomplete matches based on a single (partial) address term. Depending on the input different types of matches may be returned, such as streets, postal codes or a specific address.

This method is intended for interactive address entry where a user enters (part) of an address and matching suggestions are shown. Depending on the matches a user may keep typing, or may select a match after which additional input can still be entered.

The matching algorithm takes into account possible typos as well as missing or irrelevant words.

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.

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/autocomplete/{context}/{term}/{language}

Example REST request

Retrieving /international/v1/autocomplete/bel/vlaamsegaai with the proper authentication would use the following HTTP Request:

GET /international/v1/autocomplete/bel/vlaamsegaai 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:

{
  "matches": [
    {
      "value": "9320 Aalst, Vlaamsegaaistraat ",
      "label": "Vlaamsegaaistraat",
      "description": "9320 Aalst",
      "precision": "Street",
      "context": "bel3erZ25b6KdtUzzxMVdclyv5VIBsLUFPjeAvLk0j9x1XG6ACtQiVSF7O6iKUNWstqjMCHFtKFnqy3UUG4oZQ58Koaebzsy10eeZf0CTnA9yBTwkirbkLWznS1cHJNkwwFDm",
      "highlights": [[0, 11]]
    },
    {
      "value": "3080 Tervuren, Vlaamsegaaienlaan ",
      "label": "Vlaamsegaaienlaan",
      "description": "3080 Tervuren",
      "precision": "Street",
      "context": "bel3erZ25b6FxlO2NYYDUVFSy9ljtSGAlR7pgybRTpV9kqYIi2vEOUoEpHvvZWQ4PL8PKwwTLANMdlu7A2uLDtPPEeNcwvsmlSJbpL45PnKxd4fvKgxd73LikUU5Y6KTDoZh9",
      "highlights": [[0, 11]]
    },
    {
      "value": "Vlaamsekaai, ",
      "label": "Vlaamsekaai",
      "description": "(2 municipalities)",
      "precision": "None",
      "context": "bel83WXCGfTGvfqyDG8ZsUYy22ZbrYkJRsapHabS7TptJC8xmNjgOUxre8A71AVv",
      "highlights": [[0, 7], [8, 11]]
    }
  ]
}

Parameters

context: string: The autocomplete context. Specify a lowercase 3-letter ISO 3166-1 Alpha-3 country code to start a new address search. When a user selects a match, subsequent calls to this method should provide the context for the selected match.
term: string: The address search term. May be a complete or partial address.
language: string or null: The language to use for the presentation of search results, specified as an IETF language tag (e.g. 'nl', or 'nl-NL'). Supported languages are: en-GB (default), en-US, nl-NL, de-DE.

Returns

matches: struct[]

List of matches for the specified context and term.

Hide child parameters

value: string: The value represents all matched address information. If the user selects this match the current term input must be replaced with this value.
label: string: Label describing this match. For example, a street or municipality name.
description: string: Additional information relevant to this match, helps with disambiguation between similar labels. For example, a postal code associated with a matched street.
precision: string: Match precision, used to know what type of address information is available. E.g. "Locality", "PostalCode", "Street", "PartialAddress", "Address"
context: string: If the user selects this match, use this as the context parameter in subsequent autocomplete call. Contexts may expire and should not be stored.
highlights: array[]: List of [start, end] character offsets to highlight in the label in order to indicate what was matched.