Documentatie API v1

Autocomplete

Met deze API call kunnen Nederlandse adressen worden aangevuld.


Verplichte parameters

Gebruik één van beide verplichte parameters:

  • nl_sixpp: geef de Nederlandse postcode (4 cijfers, 2 letters) op, voor gedetailleerde gegevens (inclusief straat).
  • nl_fourpp: geef de Nederlandse postcode (4 cijfers) op, voor plaats gegevens.

Optionele parameters

Deze optionele parameters zijn mogelijk bij gebruik van de nl_sixpp parameter:

  • streetnumber: geef een huisnummer op. Wanneer deze optionele parameter is meegegeven wordt er gecontroleerd op geldigheid van het huisnummer.
  • extension: geef een huisletter en/of huisnummertoevoeging op. Wanneer streetnumber en deze optionele parameter zijn meegegeven wordt er gecontroleerd op geldigheid van het huisnummer met huisletter en/of huisnummertoevoeging.
Let op: Om het volledige adres te controleren, dienen zowel het streetnumber als extension velden te worden meegegeven naar de API. Ook wanneer de gebruiker het extension veld leeg heeft gelaten, moet expliciet een lege waarde voor extension worden meegestuurd. Bij het versturen van enkel streetnumber zonder extension veld, zal geen foutmelding gegeven worden wanneer de postcode en, huisnummer combinatie zonder opgave van een extensie niet bestaat. Alle beschikbare huisnummers inclusief extensies worden retourneert in het streetnumber veld. Hiermee kan ook een handige aanvul functie worden verschaft voor het kiezen van de juiste extensie.

Let op, het komt regelmatig voor dat bij een gelijke postcode huisnummer combinatie de huisnummer letters het verschil maken welke straat het adres bevat.

Postcode API voorbeelden

Postcode huisnummer en aanvulling

https://api.pro6pp.nl/v1/autocomplete?auth_key=YOUR_AUTH_KEY&nl_sixpp=8042AC&streetnumber=2&extension=t1

Deze aanvraag geeft het volgende resultaat:

{
  "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"
    }
  ]
}

Postcodes

Behalve het opvragen van een postcode wordt ook het XML uitvoer formaat gedemonstreerd.

Let op: Omdat er geen huisnummer wordt opgegeven worden alle huisnummers in de postcode geretourneerd als reeks. Inclusief de huisnummertoevoegingen.
https://api.pro6pp.nl/v1/autocomplete?auth_key=YOUR_AUTH_KEY&nl_sixpp=5408xb&format=xml

Deze aanvraag geeft het volgende resultaat:

<?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>

Postbussen

Postcodes welke gereserveerd zijn voor postbussen (dus geen gewoon adres met een straat) worden ook door Pro6PP geaccepteerd, maar niet gecontroleerd op specifieke postbusnummers. De uitvoer ziet er als volgt uit.

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

Postcode, huisnummer en aanvulhulp voor huisletter en/of huisnummertoevoeging

3133KK met huisnummer 2 bestaat niet. Maar huisnummer 2 met toevoeging a of b wel. Dat is een subtiel verschil, maar wel belangrijk. Het streetnumbers veld stelt ontwikkelaars in staat om gebruikers te helpen met de invoer van deze extensies en deze bijvoorbeeld in een dropdown beschikbaar te stellen.

https://api.pro6pp.nl/v1/autocomplete?auth_key=YOUR_AUTH_KEY&nl_sixpp=3133KK&streetnumber=2

Deze aanvraag geeft het volgende resultaat:

{
  "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"
    }
  ]
}

Foutmeldingen

  • 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.

Voorbeeldcode


De autocomplete methode wordt gedemonstreerd in deze gebruiksklare voorbeelden:

We raden u aan voorbeeldcode op te vragen in de taal van uw voorkeur. In de tussentijd kan u misschien kijken naar de autocomplete methode, die al in vele talen is gedemonstreerd.

Stap voor stap voorbeeld in JavaScript


Stap 1: bouw de HTML-pagina

We beginnen met het maken van een lege HTML-pagina met een minimale webpagina structuur.

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

Download onze JavaScript-bibliotheek autocomplete.zip waarmee we de Pro6PP-webservice kunnen integreren in deze webpagina. Kopieer het in dezelfde map als waarin u de bovenstaande webpagina hebt opgeslagen.

Voeg de volgende code toe tussen de tags <body> en </body>.

Het voegt de invoervelden toe voor het invoeren van het adres.

<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>

Stap 2: voeg interactie toe

Voeg de volgende code toe tussen de tags <head> en </head>. Hiermee wordt de straat en stad automatisch aangevuld wanneer een volledige postcode wordt ingevoerd.

<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>

Stap 3: laat het werken

Om toegang te krijgen tot de Pro6PP web service, moet u uw persoonlijke autorisatiesleutel aanvragen. Deze sleutel wordt direct na aanmelden naar u gemaild.

Vervang de tijdelijke aanduiding YOUR_AUTH_KEY door uw persoonlijke autorisatiesleutel.

Stap 4: zie het in actie

Open autocomplete.html in uw browser. Het is klaar voor gebruik! Werkt het niet? Probeer de kant-en-klare voorbeeldcode te downloaden.

Uitbreidingen voor dit voorbeeld


Geef meer data weer

Laten we de province ook laten zien. Voeg de volgende code toe net voor de tag </form>.

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

Je kunt het patroon hier zien. In plaats van de province kunt u een van deze gebruiken: municipality, areacode, lat, lng of streetnumbers.

Voeg een tweede postcode-adresblok toe

Webshops vereisen vaak een tweede adresblok, om factuur- en verzendadressen te scheiden. Dupliceer de adres invoervelden, maar zorg ervoor dat elk adresblok zijn eigen container heeft. Wijzig de

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

Nu we twee adresblokken hebben om automatisch aan te vullen, wijzigt u de regel waar staat ...applyAutocomplete(); naar:

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

Custom field identifiers gebruiken

In plaats van klassen aan uw formulier toe te voegen, kunt u applyAutocomplete() opdracht geven aangepaste veld-ID's te gebruiken. jQuery selector syntax wordt geaccepteerd.

Dit voorbeeld toont voorrang op de standaard-ID van de invoervelden voor postcode en huisnummer met behulp van hun ID.

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

Je kunt het patroon hier zien. In plaats van de parameters postcode en streetnumber kunt u een van deze gebruiken: street, city, municipality, province, areacode, lat, lng of streetnumbers.

Parameter message bepaalt het container element waarin errors worden weergegeven.
Parameter spinner laat een gegeven (image) element zien tijdens API communicatie.

Meer optionele instellingen

U kunt het standaardgedrag van de functie applyAutocomplete met behulp van deze parameters wijzigen:

Parameter timeout (standaard: 10000). Wacht 10 seconden voordat je de communicatie met de Pro6PP postcode database opgeeft.
Parameter enforce_validation (standaard: true). Indien ingesteld op 'true', heeft het script een geldig adres nodig dat aanwezig is in de Pro6PP-postcode database. Stel in op 'false' om het invoeren van een aangepast adres toe te staan.
Parameter gracefully_degrade (standaard: true). Indien ingesteld op 'true', zal het script het proces nooit blokkeren in geval van problemen met communicatie met de Pro6PP-postcode database. Stel in op 'false' om te voorkomen dat gebruikers een aangepast adres invoeren vanwege communicatiefouten.