Skip to content

Autocomplete API

In the examples below, the following address is used: Amersfoort Krankeledenstraat 30 3811BN. This address Onze Lieve Vrouwetoren - Amersfoort is the central point according to the Dutch map projection of the Dutch national triangulation system (with coordinates +155 000 m +463 000 m).

The Autocomplete API is a progressive search API that makes it possible to create a drill-down menu, among other things. Of course, it can also be used for other applications. An example (demo) of this API can be tested on the homepage of postcode-api.nl.

The API works in steps:

  1. Search city → context ID
  2. Search city (with context)
  3. Search street (with context)
  4. Search house number (with context)

Within this API, some facets are important:

  • Context ID
  • X-AutocompleteSessionId

Context ID, this can be seen in the JSON. You use the Context ID for the next search query (in other words: when the user has chosen a specific item/object).

X-AutocompleteSessionId, this is an HTTP Header that you must always include. Without this header, the search query is not valid. The X-AutocompleteSessionId always has a value; a random string is sufficient, for example: 

function generateSessionId() {
    return Math.random().toString(36).substr(2, 9);
}

Ensure that the X-AutocompleteSessionId remains the same throughout the search query.

In step 1, "city" can be any other term such as: "province, municipality, street name, and/or a postcode"

Step 1: Search City

The user types in: "Amersfoort"

HTTP Request: 

GET /v1/autocomplete/nl?search=Amersfoort&per_page=50&page=1
Headers: Authorization: Bearer $YOUR_TOKEN
Headers: X-AutocompleteSessionId: abc123xyz

HTTP JSON Response from https://api.postcode-api.nl 

{
  "results": [
    {
      "value": "Amersfoort, ",
      "label": "Amersfoort",
      "description": "municipality in Utrecht",
      "precision": "GroupedCities",
      "context": "7e9891800bac72d2"
    },
    {
      "value": "Amersfoortseweg, ",
      "label": "Amersfoortseweg",
      "description": "(11 places)",
      "precision": "GroupedStreets",
      "context": "4d0a93575446d379"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 2,
    "total_pages": 1
  }
}

Step 2: Search City (with context)

In the previous step we searched for "Amersfoort", but like many municipalities in the Netherlands, the city name is the same as the municipality name and vice versa. We therefore also choose the context id: 7e9891800bac72d2.

HTTP Request: 

GET /v1/autocomplete/nl?context=7e9891800bac72d2&per_page=50&page=1
Headers: Authorization: Bearer $YOUR_TOKEN
Headers: X-AutocompleteSessionId: abc123xyz

HTTP JSON Response from https://api.postcode-api.nl 

{
  "results": [
    {
      "value": "Amersfoort (streets), ",
      "label": "Amersfoort",
      "description": "Place 'Amersfoort'",
      "precision": "City",
      "context": "1a6f5e841f05dde0"
    },
    {
      "value": "Hoogland, ",
      "label": "Hoogland",
      "description": "Place in municipality Amersfoort",
      "precision": "City",
      "context": "d6a7e1d41c723cb2"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 2,
    "total_pages": 1
  }
}

Step 3: Search Street (with context)

We're repeating ourselves, but we're one step closer to our goal. In this case, the user chooses the context id: 1a6f5e841f05dde0. The place "Amersfoort" has been selected, now a result set with streets of Amersfoort follows.

HTTP Request: 

GET /v1/autocomplete/nl?context=1a6f5e841f05dde0&per_page=50&page=1
Headers: Authorization: Bearer $YOUR_TOKEN
Headers: X-AutocompleteSessionId: abc123xyz

{
  "results": [
    {
      "value": "Amersfoort, 's Gravesandestraat",
      "label": "'s Gravesandestraat",
      "description": "Street in place 'Amersfoort'",
      "precision": "Street",
      "context": "39c9d5c2fe7fb8"
    },
    {
      "value": "Amersfoort, 't Haartje",
      "label": "'t Haartje",
      "description": "Street in place 'Amersfoort'",
      "precision": "Street",
      "context": "7c0f2cba8c312217"
    },
    {
      "value": "Amersfoort, 't Zand",
      "label": "'t Zand",
      "description": "Street in place 'Amersfoort'",
      "precision": "Street",
      "context": "5c25f875914993f4"
    },
     .. snip .. 
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 1020,
    "total_pages": 21
  }
}

Step 4: Search House Number (with context)

We are looking for: "Krankeledenstraat 30", the context id of this street is: 

    {
      "value": "Amersfoort, Krankeledenstraat",
      "label": "Krankeledenstraat",
      "description": "Street in place 'Amersfoort'",
      "precision": "Street",
      "context": "3e722fbff62bf717"
    },

The context id: 3e722fbff62bf717 will lead to the street with the house numbers: 

GET /v1/autocomplete/nl?context=3e722fbff62bf717&per_page=50&page=1
Headers: Authorization: Bearer $YOUR_TOKEN
Headers: X-AutocompleteSessionId: abc123xyz

{
  "results": [
    {
      "value": "Amersfoort, Krankeledenstraat, 1A",
      "label": "Krankeledenstraat 1A",
      "description": "3811BN Amersfoort",
      "precision": "House",
      "context": "fdb8d2d859514fe8"
    },
    {
      "value": "Amersfoort, Krankeledenstraat, 4F",
      "label": "Krankeledenstraat 4F",
      "description": "3811BN Amersfoort",
      "precision": "House",
      "context": "a588fe06c3256308"
    },
     .. snip .. 
    {
      "value": "Amersfoort, Krankeledenstraat, 30",
      "label": "Krankeledenstraat 30",
      "description": "3811BN Amersfoort",
      "precision": "House",
      "context": "af653277a0545ce4"
    },
    .. snip ..
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 26,
    "total_pages": 1
  }
}

If we search using the context id of Krankeledenstraat 30, we get the complete address data. The Autocomplete API therefore has two response shapes:

  • Intermediate results with results and pagination
  • A final address object once an exact house result has been selected

For the final case, the response looks like this: 

{
  "city": "Amersfoort",
  "housenumber": "30",
  "municipality": "Amersfoort",
  "postcode": "3811BN",
  "province": "Utrecht",
  "street": "Krankeledenstraat",
  "location": {
    "rd": [
      155014.59,
      462985.67
    ],
    "wgs84": [
      52.15504560250615,
      5.387419406464223
    ]
  }
}