API documentation

Range

Given a postcode and a maximum search distance, enter the surrounding zip codes. The output is sorted from near to far.

Mandatory parameters

Use one of the two mandatory parameters:

  • nl_fourpp: enter the Dutch postcode (4 digits).
  • city_key: enter the unique identification of a Dutch place, which is determined with a previous call to the suggest endpoint.

Optional parameters

  • range: the desired circumference in which searches are made - in meters. The default is 5000. Maximum 100000.
  • per_page: the maximum number of postcodes as a result. By default this is 10. Maximum of 1000 results per page.
  • page: the desired result page with a maximum of ’per_page’ results. By default this is page 10.

Result example

undefined/v1/range?auth_key=YOUR_AUTH_KEY&nl_fourpp=5408

This request gives the following result:

{
  "status": "ok",
  "results": [
    {
      "nl_fourpp": "5408",
      "distance": 0,
      "lng": 5.6584,
      "lat": 51.6434
    },
    {
      "nl_fourpp": "5405",
      "distance": 1486,
      "lng": 5.6475,
      "lat": 51.655
    },
    {
      "nl_fourpp": "5404",
      "distance": 2966,
      "lng": 5.6175,
      "lat": 51.6516
    },
    ...
  ]
}

Please note: the validity of city_key is limited. In practice, the key will be valid for at least 24 hours.

Error messages

  • ‘Parameter nl_fourpp is required’
    Provide the ‘nl_fourpp’ parameter to the web service. This is allowed both in the URL (GET) and in the body (POST).
  • ‘Invalid nl_fourpp format’
    The format must consist of 4 digits. Extra spacing is automatically corrected.
  • ‘nl_fourpp not found’
    The requested postcode is not known in the database.
  • ‘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.
  • ‘Parameter range expected int as datatype’
    The ‘range’ parameter must contain a number.
  • ‘The value of range should be between 1 and 100000’
    The ‘range’ parameter must contain a circumference (in meters) between 0 and 100000.

Example code

The range 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>Range tutorial</title>
  </head>
  <body></body>
</html>

Download our JavaScript library range.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 postcode.

<form action="#" class="pro6pp_range">
  Postcode: <input class="postcode" maxlength="4" /><br />
  Range:
  <select class="range">
    <option value="5" selected="selected">5 km</option>
    <option value="15">15 km</option>
    <option value="50">50 km</option>
  </select>
  <span class="message"></span><br />
  <div class="output"></div>
</form>

Step 2: add interaction

Add the following code between the <head> and </head> tags.

<script src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
<script src="range.js"></script>
<script>
  var pro6pp_auth_key = 'YOUR AUTH_KEY';
  $(document).ready(function() {
    $('.pro6pp_range').applyRange();
  });
</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 range.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.

Extensions to this example

Show more data

Show the found results in a different way. Replace this JavaScript line...

$(".pro6pp_range").applyRange();

...with the following code:

$(".pro6pp_range").applyRange({ 'assemble_func': assemble_one });
  // This function is called for each postcode found.
  function assemble_one(result) {
    return "Distance to " + result.nl_fourpp + " is " +
        result.distance + " meters from your location.&lt;br /&gt;";
}

You can see the pattern here. Instead of nl_fourpp and distance you may use any of these fields to construct your output: lat, lng.

Using custom field identifiers

Instead of adding classes to your form, you can instruct applyRange() to use custom field identifiers. jQuery selector syntax is accepted.

This example overrides the default identifier of the fields by using their name or id attributes.

... Postcode: <input name="zipcode" />
<span id="range-errors"></span>
... ... $(document).ready(function() { $(this).applyRange({ postcode: 'input[name="zipcode"]',
message: '#range-errors', }); });

You can see the pattern here. Instead of the postcode and message parameters, you may use any of these:

Parameter range assigns the input or select element containing search ranges to choose from.
Parameter message assigns the container element in which to display error messages.
Parameter spinner assigns an (image) element to hide/show during API communication. Parameter output assigns the container element in which to display results.