Documentatie API v1

Range

Gegeven een postcode en een maximale zoekafstand, geef de omringende postcodes. De uitvoer is gesorteerd van dichtbij naar veraf.

Verplichte parameters

Gebruik één van beide verplichte parameters:

  • nl_fourpp: geef de Nederlandse postcode (4 cijfers) op.
  • city_key: geef de unieke identificatie van een Nederlandse plaats op, welke bepaald is met een eerdere aanroep naar de suggest endpoint.

Optionele parameters

  • range: de gewenste omtrek waarin gezocht wordt - in meters. Standaard is dit 5000. Maximaal 100000.
  • per_page: het maximaal aantal postcodes als resultaat. Standaard is dit 10. Maximaal 1000 resultaten per pagina.
  • page: de gewenste resultaatpagina met daarop ten hoogste ’per_page’ resultaten. Standaard is dit pagina 10.

Resultaat voorbeeld

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

Deze aanvraag geeft het volgende resultaat:

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

Let op: de geldigheid van city_key is beperkt. In de praktijk zal de sleutel ten minste 24 uur geldig zijn.

Foutmeldingen

  • ‘Parameter nl_fourpp is required’
    Geef de parameter ‘nl_fourpp’ mee aan de webservice. Dit mag zowel in de URL (GET) als in de body (POST).
  • ‘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.
  • ‘Parameter per_page expected int as datatype’
    Parameter ‘per_page’ dient een getal te bevatten.
  • ‘The value of per_page should be between 1 and 1000’
    Parameter ‘per_page’ dient een getal te bevatten tussen de 1 en 1000.
  • ‘Parameter range expected int as datatype’
    Parameter ‘range’ dient een getal te bevatten.
  • ‘The value of range should be between 1 and 100000’
    Parameter ‘range’ dient een omtrek (in meters) te bevatten tussen de 0 en 100000.

Voorbeeldcode

De range methode wordt gedemonstreerd in deze kant-en-klare voorbeelden:

We moedigen u aan om voorbeeldcode aan te vragen in de taal van uw voorkeur. In de tussentijd wilt 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 webpaginastructuur.

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

Download onze JavaScript-bibliotheek range.js 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 de 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>

Stap 2: voeg interactie toe

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

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

Stap 3: laat het werken

Om toegang te krijgen tot de Pro6PP webservice, moet u uw persoonlijke autorisatiesleutel aanvragen. Deze sleutel wordt direct na signing up naar u gemaild.

Vervang de bovenstaande tijdelijke aanduiding YOUR AUTH_KEY door uw persoonlijke autorisatiesleutel.

Stap 4: zie het in actie

Open range.html in uw browser. Het is klaar voor gebruik!
Het werkt niet? Probeer de kant-en-klare voorbeeldcode te downloaden op de pagina example code.

Uitbreidingen voor dit voorbeeld

Toon meer gegevens

Toon de gevonden resultaten op een andere manier. Vervang deze JavaScript-regel...

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

... met de volgende 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;";
}

Je kunt het patroon hier zien. In plaats van nl_fourpp en distance kunt u een van deze velden gebruiken om uw uitvoer samen te stellen: lat, lng.

Aangepaste veld-ID's gebruiken

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

Dit voorbeeld overschrijft de standaard-ID van de velden met behulp van hun name of id attributen.

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

Je kunt het patroon hier zien. In plaats van de parameters postcode en message kunt u een van deze gebruiken:

Parameter range wijst het invoer- of selecteerelement toe met zoekbereiken waaruit u kunt kiezen.
Parameter message wijst het containerelement toe waarin foutmeldingen worden weergegeven.
Parameter spinner wijst een (beeld) element toe om te verbergen / weergeven tijdens API-communicatie. Parameter output wijst het containerelement toe waarin de resultaten worden weergegeven.