Autocomplete

Addresses can be supplemented with this API call.

Required parameters

Use one of both mandatory parameters:

• nl_sixpp: Enter the Dutch zip code (4 digits, 2 letters), for detailed information (including streets).
• nl_fourpp: enter the Dutch zip code (4 digits), for location data.

Optional parameters

These optional parameters are possible when using the nl_sixpp parameter:

• streetnumber: enter a house number. When this optional parameter is provided, the house number is checked for validity.
• extension: enter a house letter and/or house number addition. When the street number and this optional parameter have been provided, the validity of the house number with house letter and/or house number addition is checked.

Please note, it often happens that with the same zip code house number combination the house number letters make the difference which street contains the address.

Postcode API Examples

Postcode, house number and addition

undefined/v1/autocomplete?auth_key=YOUR_AUTH_KEY&nl_sixpp=8042AC&streetnumber=2&extension=t1

This request gives the following result:

{
  "status": "ok",
  "results": [
    {
      "nl_sixpp": "8042AC",
      "streetnumber": 2,
      "extension": "T 1",
      "street": "Hasselterweg",
      "street_nen5825": "Hasselterweg",
      "city": "Zwolle",
      "municipality": "Zwolle",
      "province": "Overijssel",
      "lat": 52.5153137,
      "lng": 6.0706741,
      "areacode": "038"
    }
  ]
}

Postcode without house number

In addition to requesting a zip code, the XML output format is also demonstrated.

undefined/v1/autocomplete?auth_key=YOUR_AUTH_KEY&nl_sixpp=5408xb&format=xml

This request gives the following result:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <results>
    <result>
      <nl_sixpp>5408XB</nl_sixpp>
      <street>Reestraat</street>
      <street_nen5825>Reestraat</street_nen5825>
      <streetnumbers>10-56</streetnumbers>
      <city>Volkel</city>
      <municipality>Uden</municipality>
      <province>Noord-Brabant</province>
      <lat>51.64464</lat>
      <lng>5.6526</lng>
      <areacode>0413</areacode>
    </result>
  </results>
</response>

PO Boxes

Postal codes reserved for mailboxes (so no ordinary address with a street) are also accepted by Pro6PP, but not checked for specific mailbox numbers. The output looks like this.

{
  "status": "ok",
  "results": [
    {
      "nl_sixpp": "5460AC",
      "street": "Postbus",
      "city": "Veghel",
      "municipality": "Veghel",
      "province": "Noord-Brabant",
      "lat": null,
      "lng": null,
      "areacode": "0413"
    }
  ]
}

Postcode, house number and supplement help for house letter and / or house number addition

3133KK with house number 2 does not exist. But house number 2 with the addition a or b does. That is a subtle difference, but it is important. The streetnumbers field allows developers to assist users with the input of these extensions and make it available in a dropdown, for example.

undefined/v1/autocomplete?auth_key=YOUR_AUTH_KEY&nl_sixpp=3133KK&streetnumber=2

This request gives the following result:

{
  "status": "ok",
  "results": [
    {
      "nl_sixpp": "3133KK",
      "street": "James Wattweg",
      "city": "Vlaardingen",
      "municipality": "Vlaardingen",
      "province": "Zuid-Holland",
      "streetnumbers": "4-6;10-12;16-46;68-70;74;80;84;9;2 a;2 b;2 c;2 d;2 e;2 f;2 g;2 h;2 j;2 k;2 l;2 m;2 n;2 p;2 q;2 r;2 s;2 t;2 u;2 v;2 w;2 x;2 y;2 z;20 a;28 A;4 a;42 A",
      "lat": 51.90135,
      "lng": 4.31459,
      "areacode": "010"
    }
  ]
}

Error messages

• ‘Invalid nl_sixpp format’
  Het formaat dient te bestaan uit 4 cijfers en 2 letters. Extra spatiëring en gebruik van hoofd- of kleine letters worden automatisch gecorrigeerd.
• ‘nl_sixpp not found’
  De opgevraagde postcode is niet bekend in de database.
• ‘Invalid nl_fourpp format’
  Het formaat dient te bestaan uit 4 cijfers. Extra spatiëring wordt automatisch gecorrigeerd.
• ‘nl_fourpp not found’
  De opgevraagde postcode is niet bekend in de database.
• ‘Missing nl_fourpp or nl_sixpp parameter’
  één van beide parameters opgeven is verplicht.
• ‘Streetnumber not found’
  De ‘streetnumber’ parameter is meegegeven maar het opgegeven huisnummer bestaat niet volgens onze database.
• ‘streetnumber is missing a number’
  De ‘streetnumber’ parameter is meegegeven maar bevat geen (geldige) waarde.
• ‘extension not found’
  De ‘extension’ parameter is meegegeven maar de opgegeven huisletter of huisnummertoevoeging bestaat niet volgens onze postcode database.
• ‘Streetnumber without extension not found’
  De ‘extension’ parameter is meegegeven maar het huisnummer bestaat niet zonder een huisletter of huisnummertoevoeging.

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>Autocomplete tutorial</title>
  </head>
  <body></body>
</html>

Download our JavaScript library autocomplete.zip 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">
  Postcode: <input class="postcode" /> Streetnumber: <input class="streetnumber" />
  <span class="message"></span><br />
  Street: <input class="street" readonly /><br />
  City: <input class="city" readonly />
</form>

Step 2: add interaction

Add the following code between the <head> and </head> tags. It autocompletes the street and city when a full postcode is entered.

<script src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
<script src="autocomplete.js"></script>
<script>
  var pro6pp_auth_key = 'YOUR AUTH_KEY';
  $(document).ready(function() {
    $('.address').applyAutocomplete();
  });
</script>

Step 3: make it work

To access the Pro6PP web service, 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 autocomplete.html in your browser. It’s ready to use! It doesn’t work? Try downloading the ready-to-use example code.

Extensions to this example

Show more data

Let’s show the province as well. Add the following code just before the </form> tag.

Province: <input class="province" readonly />

You can see the pattern here. Instead of the province you may use any of these: municipality, areacode, lat, lng or streetnumbers.

Add a second postcode address block

Webshops often require a second address block, to seperate billing and shipping addresses. Duplicate the address input fields, but make sure each address block has its own container. Change the code between the <form> and </form> tags like this:

<form action="#">
  <div class="billing-address">
    Postcode: <input class="postcode" />
    ...
  </div>
  <div class="shipping-address">
    Postcode: <input class="postcode" />
    ...
  </div>
</form>

Now that we have two address blocks to autocomplete, change the line where it says ...applyAutocomplete(); to:

$(".billing-address").applyAutocomplete();
$(".shipping-address").applyAutocomplete();

Using custom field identifiers

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

This example shows overrides the default identifier of the postcode and street number input fields by using their id.

... Postcode: <input id="billing-zipcode" /> Streetnumber: <input id="billing-streetnumber" />
... ... $(document).ready(function() { $(this).applyAutocomplete({ postcode: '#billing-zipcode',
streetnumber: '#billing-streetnumber', }); });

You can see the pattern here. Instead of the postcode and streetnumber parameters, you may use any of these: street, city, municipality, province, areacode, lat, lng or streetnumbers.

Parameter message assigns the container element in which to display error messages.
Parameter spinner assigns an (image) element to hide/show during API communication.

More optional settings

You’re able to change the default behaviour of the applyAutocomplete function using these parameters:

Parameter timeout (default: 10000). Wait for 10 seconds before giving up on communication with Pro6PP postcode database.
Parameter enforce_validation (default: true). When set to ’true’, the script will required a valid address present in the Pro6PP postcode database. Set to ’false’ to allow entering a custom address.
Parameter gracefully_degrade (default: true). When set to ’true’, the script will never block the process in case of trouble communicating with Pro6PP postcode database. Set to ’false’ to prevent users from entering a custom address because of communication failures.