API documentation

Locator

Given a postcode or lat / lng combination and your own list of postcodes, enter the nearest locations. The output is sorted from near to far.

Mandatory parameters

  • target_nl_fourpps: Provide a list of Dutch postal codes (4 digits). Separated by commas.

Optional parameters

  • nl_fourpp: enter the Dutch zip code (4 digits) as the search location.
  • lat: Specify the latitude as the search location.
  • lng: enter the longitude as the search location.
  • range: the desired circumference in which searches are made - in meters. This is standard throughout the Netherlands. Maximum circumference of 300,000.
  • per_page: the maximum number of zip codes as a result. The default is 10.
  • order Beta: distance (default) sorts output by increasing distance from starting point to search results. input retains the order of input with the output.

Result example

undefined/v1/locator?auth_key=YOUR_AUTH_KEY&nl_fourpp=5408&target_nl_fourpps=5652,2987

This request gives the following result:

{
  "status": "ok",
  "results": [
    {
      "nl_fourpp": 5652,
      "distance": 25626,
      "lng": 5.46667,
      "lat": 51.45,
      "city": "Eindhoven",
      "municipality": "Eindhoven",
      "province": "Noord-Brabant"
    },
    {
      "nl_fourpp": 2987,
      "distance": 76263,
      "lng": 4.6,
      "lat": 51.86667,
      "city": "Ridderkerk",
      "municipality": "Ridderkerk",
      "province": "Zuid-Holland"
    }
  ]
}

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 ëring is automatically corrected.
  • ‘nl_fourpp not found’
    The requested postcode is not known in the database.
  • ‘Parameter target_nl_fourpps is required’
    Provide the ‘target_nl_fourpps’ parameter to the web service. This is allowed both in the URL (GET) and in the body (POST).
  • ‘Invalid target_nl_fourpps format’
    The format must always consist of 4 zip codes, separated by a comma. Extra spacing ëring is automatically corrected.
  • ‘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 parameter ‘range’ parameter must contain a number.
  • ‘The value of range should be between 0 and 300000’
    The ‘range’ parameter must contain a circumference (in meters) between 0 and 300000.

Example code

The locator 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>Locator tutorial</title>
  </head>
  <body></body>
</html>

Download our JavaScript library locator.js that allows us to integrate the Pro6PP web service 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="locator">
  Postcode: <input class="postcode" maxlength="4" />
  <input class="target_nl_fourpps" type="hidden" value="1012, 9301, 5042, 4834, 5408" /><br />
  <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="locator.js"></script>
<script>
  var pro6pp_auth_key = 'YOUR AUTH_KEY';
  $(document).ready(function() {
    $('.locator').applyLocator();
  });
</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 locator.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

Instead of the stores postcode, let’s show the city. Replace this JavaScript line...

$(".locator").applyLocator();

...with the following code:

$(".locator").applyLocator({'assemble_func':assemble_one });
// This function is called for each store found.
function assemble_one(result){
  return "Store found in " + result.city + ", " +
    result.distance + " meters from your location.<br />";
}

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

Using custom field identifiers

Instead of adding classes to your form, you can instruct applyLocator() 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="zipcode-errors"></span>
... ... $(document).ready(function(){ $(this).applyLocator({ postcode:'input[name="zipcode"]',
message:'#zipcode-errors', }); });

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

Parameter target_nl_fourpps assigns the (hidden) input element containing all possible store postcodes.
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.