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

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}

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

{
  "newContext": null,
  "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]]
    }
  ]
}