Dokumentation API v1

Autovervollständigung

Mit diesem API-Aufruf können niederländische Adressen ergänzt werden.


Obligatorische Parameter

Verwenden Sie einen der beiden obligatorischen Parameter:

  • nl_sixpp: Geben Sie die niederländische Postleitzahl (4-stellig, 2 Buchstaben) für detaillierte Daten (einschließlich Straße) ein.
  • nl_fourpp: Geben Sie die niederländische Postleitzahl (4-stellig) für die Ortsdaten ein.

Optionale Parameter

Diese optionalen Parameter sind bei Verwendung des Parameters nl_sixpp möglich:

  • streetnumber: Geben Sie eine Hausnummer ein. Wenn dieser optionale Parameter angegeben wird, wird die Gültigkeit der Hausnummer überprüft.
  • extension: Geben Sie einen Hausbuchstaben und/oder ein Hausnummernzusatz ein. Wenn streetnumber und dieser optionale Parameter angegeben sind, wird die Gültigkeit der Hausnummer mit Hausbrief und/oder Hausnummernzusatz überprüft.
Vorsicht: Um die vollständige Adresse zu überprüfen, müssen sowohl die streetnumber als auch die extension sein. Felder, die an die API übergeben werden sollen. Auch wenn der Benutzer extension ist. Feld leer gelassen wurde, muss ein leerer Wert für extension explizit angegeben werden. Wenn Sie nur streetnumber ohne extension senden. Wenn die Kombination aus Postleitzahl und Hausnummer ohne Erweiterung nicht vorhanden ist, wird keine Fehlermeldung ausgegeben. Alle verfügbaren Hausnummern einschließlich Nebenstellen werden im Feld streetnumber zurückgegeben. Dies kann auch eine nützliche Zusatzfunktion zur Auswahl der richtigen Erweiterung sein.

Bitte beachten Sie, dass es regelmäßig vorkommt, dass bei gleicher Postleitzahl-Hausnummernkombination die Buchstaben der Hausnummer den Unterschied ausmachen, welche Straße die Adresse enthält.

Postleitzahl-API-Beispiele

Postleitzahl Hausnummer und Zusatz

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

Diese Anwendung liefert das folgende Ergebnis:

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

Postleitzahlen

Neben der Anforderung einer Postleitzahl wird auch das XML-Ausgabeformat demonstriert.

Vorsicht: Da keine Hausnummer angegeben ist, werden alle Hausnummern in der Postleitzahl als Serie zurückgegeben. Einschließlich der Hausnummernzusätze.
https://api.pro6pp.nl/v1/autocomplete?auth_key=YOUR_AUTH_KEY&nl_sixpp=5408xb&format=xml

Diese Anwendung liefert das folgende Ergebnis:

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

Postfächer

Postleitzahlen, die für Postfächer reserviert sind (d.h. keine gewöhnliche Adresse mit einer Straße), werden von Pro6PP ebenfalls akzeptiert, aber nicht auf bestimmte Postfachnummern überprüft. Die Ausgabe sieht wie folgt aus.

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

Postleitzahl, Hausnummer und Zusatzhilfe für Hausbrief und/oder Hausnummernzusatz

3133KKK mit der Hausnummer 2 existiert nicht. Aber Hausnummer 2 mit dem Zusatz a oder b ist. Das ist ein subtiler Unterschied, aber er ist wichtig. Das Feld streetnumbers ermöglicht es Entwicklern, Benutzern bei der Eingabe dieser Erweiterungen zu helfen und diese z.B. in einem Dropdown-Menü zur Verfügung zu stellen.

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

Diese Anwendung liefert das folgende Ergebnis:

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

Fehlermeldungen

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

Beispielcode


Die Methode autocomplete wird in diesen gebrauchsfertigen Beispielen demonstriert:

Wir empfehlen Ihnen, einen Mustercode in Ihrer bevorzugten Sprache anzufordern. In der Zwischenzeit sollten Sie einen Blick auf die Autovervollständigung werfen, die bereits in vielen Sprachen demonstriert wurde.

Schritt-für-Schritt Beispiel in JavaScript


Schritt 1: Erstellen der HTML-Seite

Wir beginnen damit, eine leere HTML-Seite mit einer minimalen Webseitenstruktur zu erstellen.

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

Laden Sie unsere JavaScript-Bibliothek autocomplete.zip herunter, mit der wir den Pro6PP-Webservice in diese Webseite integrieren können. Kopieren Sie es in den gleichen Ordner, in dem Sie die obige Webseite gespeichert haben.

Füge den folgenden Code zwischen den Tags <body> und </body> hinzu.

Es fügt die Eingabefelder für die Eingabe der Adresse hinzu.

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

Schritt 2: Interaktion hinzufügen

Füge den folgenden Code zwischen den Tags <head> und </head> hinzu. Dadurch werden Straße und Ort bei Eingabe einer vollständigen Postleitzahl automatisch aufgefüllt.

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

Schritt 3: Lass es funktionieren

Um auf den Pro6PP-Webservice zuzugreifen, müssen Sie Ihren persönlichen Autorisierungsschlüssel anfordern. Dieser Schlüssel wird Ihnen unmittelbar nach sich[Akk] anmelden per E-Mail zugesandt.

Ersetzen Sie die temporäre Kennung YOUR_AUTH_KEY durch Ihren persönlichen Autorisierungsschlüssel.

Schritt 4: Sehen Sie es in Aktion

Öffnen Sie autocomplete.html in Ihrem Browser. Es ist gebrauchsfertig! Funktioniert es nicht? Versuchen Sie, den vorgefertigten Beispielcode von der Seite herunterzuladen.

Erweiterungen für dieses Beispiel


Mehr Daten anzeigen

Lassen Sie uns auch die province zeigen. Füge den folgenden Code kurz vor dem Tag </form> hinzu.

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

Sie können das Muster hier sehen. Anstelle der province kannst du eine davon verwenden: >- municipality, areacode, lat, lng oder streetnumbers.

Einen zweiten Postleitzahlen-Adressblock hinzufügen

Webshops benötigen oft einen zweiten Adressblock, um Rechnungs- und Lieferadressen zu trennen. Duplizieren Sie die Adresseingabefelder, stellen Sie aber sicher, dass jeder Adressblock einen eigenen Container hat. Ändern Sie den Code zwischen den Tags <form> und </form> wie folgt:

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

Nun, da wir zwei Adressblöcke haben, die automatisch aufgefüllt werden müssen, ändern Sie die Zeile, in der es heißt ...applyAutocomplete();:

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

Verwendung benutzerdefinierter Feldbezeichner

Anstatt Klassen zu Ihrem Formular hinzuzufügen, können Sie applyAutocomplete() anweisen, benutzerdefinierte Feld IDs zu verwenden. jQuery selector syntax wird akzeptiert.

In diesem Beispiel wird die Priorität gegenüber der Standard-ID der Eingabefelder Postleitzahl und Hausnummer anhand ihrer ID angezeigt.

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

Sie können das Muster hier sehen. Anstelle der Parameter postcode und streetnumber können Sie einen davon verwenden: street, city, municipality, province, areacode, lat, lng oder streetnumbers.

Der Parameter message definiert das Containerelement, in dem Fehler angezeigt werden.
Der Parameter spinner zeigt ein bestimmtes (Bild-)Element während der API-Kommunikation an.

Weitere optionale Einstellungen

Mit diesen Parametern können Sie das Standardverhalten der Funktion applyAutocomplete ändern:

Parameter timeout (Standard: 10000). Warten Sie 10 Sekunden, bevor Sie die Kommunikation mit der Postleitzahlendatenbank Pro6PP aufnehmen.
Parameter enforce_validation (Standard: wahr). Wenn auf 'true' gesetzt, benötigt das Skript eine gültige Adresse, die in der Pro6PP-Postleitzahlendatenbank vorhanden ist. Auf 'false' setzen, um die Eingabe einer benutzerdefinierten Adresse zu ermöglichen.
Parameter gracefully_degrade (Standard: wahr). Wenn auf "true" gesetzt, blockiert das Skript den Prozess nie, wenn es Probleme mit der Kommunikation mit der Pro6PP-Postleitzahlendatenbank gibt. Setzen Sie diese Option auf "false", um zu verhindern, dass Benutzer aufgrund von Kommunikationsfehlern eine geänderte Adresse eingeben.