API documentation

Suggest

Given one or more initial letters of a place, give a list of place names. The output is sorted alphabetically.
After choosing one place, street name suggestions can also be given within this place.

If multiple nl_fourpps are returned, the zip code in the first position indicates the center, the others are in numerical order.

Suggest part 1: finding a place

It is possible to search on both The Hague and The Hague. The ’official_city’ field will in both cases give the Hague.

Accents and punctuation marks may also be omitted.

Required parameters

  • nl_city: enter one of several initial letters of a Dutch city.

Optional parameters

  • per_page: the maximum number of places as a result. The default is 10.

Result example

undefined/v1/suggest?auth_key=YOUR_AUTH_KEY&per_page=2&nl_city=bergen

This request gives the following result:

{
  "status": "ok",
  "results": [
    {
      "province": "Limburg",
      "municipality": "Bergen",
      "city_key": "bergenbergenlimburg",
      "city": "Bergen (Bergen, Limburg)",
      "official_city": "Bergen",
      "nl_fourpps": "5854",
      "lat": 51.60137,
      "lng": 6.05422
    },
    {
      "province": "Noord-Holland",
      "municipality": "Bergen",
      "city_key": "bergenbergennoordholland",
      "city": "Bergen (Bergen, Noord-Holland)",
      "official_city": "Bergen",
      "nl_fourpps": "1860,1861,1862",
      "lat": 52.66891,
      "lng": 4.70604
    }
  ]
}

Suggest part 2: finding a street

Some place names and / or municipality names are more common. This extra information is stated in brackets after the place name. To find the street names within the correct location, the location is then identified by the unique city_key. Please note: the validity of city_key is limited. In practice, the key will be valid for at least 24 hours.

Required parameters

  • city_key: geef de unieke identificatie van een Nederlandse plaats op, welke bepaald is in stap 1.
  • street: enter one or more initial letters of a Dutch street within the place identified by the city_key.

Optional parameters

  • streetnumber: enter a house number to get the exact postcode for this house number in the street.
  • extension: enter a house number addition to get the exact postcode for this house number in the street.
  • per_page: the maximum number of streets as a result. The default is 10.

Result example

undefined/v1/suggest?auth_key=YOUR_AUTH_KEY&per_page=2&street=a&city_key=agZwcm82cHByJQsSDENpdHlTdWdnZXN0MiITYmVyZ2VuYmVyZ2VubGltYnVyZwwa

This request gives the following result:

{
  "status": "ok",
  "results": [
    {
      "street": "Acaciastraat",
      "nl_sixpps": "5854GX",
      "lat": 51.59995,
      "lng": 6.05188
    },
    {
      "street": "Aijen",
      "nl_sixpps": "5854PP,5854PR",
      "lat": 51.58311,
      "lng": 6.0428
    }
  ]
}

Error messages

  • ‘Parameter city is required’
    Give the ‘city’ parameter to the web service. This is allowed both in the URL (GET) and in the body (POST).
  • ‘Parameter per_page expected int as datatype’
    Parameter ‘per_page’ must contain a number.
  • ‘The value of per_page should be between 1 and 1000’
    Parameter ‘per_page’ must contain a number between 1 and 1000.
  • ‘city not found’
    No place is known which starts with the specified letters.
  • ‘invalid city_key’
    The city_key is unknown.
  • ‘street not found’
    No street is known which starts with the specified letters.
  • ‘Specify either nl_city or city_key’
    Er mist een parameter.

Example code

The suggest method is demonstrated in these ready-to-use examples:

We encourage you to request example code in the language you prefer. In the meantime, you might want to look at the autocomplete method, which is already demonstrated in many languages.

Step by step example in JavaScript

Step 1: build the HTML page

We start by creating an empty HTML page, containing a minimal web page structure.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Suggest tutorial</title>
  </head>
  <body></body>
</html>

Download our JavaScript library suggest.js that allows us to integrate the Pro6PP webservice into this web page. Copy it in the same directory as you saved the above web page.

Add the following code between the <body and </body tags.

It adds the input fields for entering the address.

<form action="#" class="address">
  City: <input class="city" /> <span class="city_message"></span><br />
  Street: <input class="street" />
  <span class="street_message"></span>
</form>

Step 2: add interaction

Add the following code between the <head> and </head> tags. It suggests possible city names while the user is typing.

<script src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
<link rel="stylesheet" href="https://code.jquery.com/ui/1.11.2/themes/smoothness/jquery-ui.css" />
<script src="https://code.jquery.com/ui/1.11.2/jquery-ui.min.js"></script>
<script src="suggest.js"></script>
<script>
  var pro6pp_auth_key = 'YOUR AUTH_KEY';
  $(document).ready(function() {
    $('.address').applySuggest();
  });
</script>

Step 3: make it work

To access the Pro6PP webservice, you need to request your personal authorization key. This key is emailed to you right after signing up.

Replace the above placeholder YOUR AUTH_KEY with your personal authorization key.

Step 4: see it in action

Open suggest.html in your browser. It’s ready to use!
It doesn’t work? Try downloading the ready-to-use example code at the example code page.