Documentatie API v1

Suggest

Gegeven één of meerdere beginletters van een plaats, geef een lijst van plaatsnamen. De uitvoer is alfabetisch gesorteerd.
Na één plaats te hebben gekozen kunnen ook straatnaam suggesties worden gegeven binnen deze plaats.

Indien meerdere nl_fourpps worden teruggeven geeft de postcode in de eerste positie het centrum aan, de overige zijn op numerieke volgorde.

Suggest deel 1: het vinden van een plaats

Het is mogelijk te zoeken op zowel ’s-Gravenhage als Den Haag. Het ’official_city’ veld zal in beide gevallen ’s-Gravenhage geven.

Ook mogen accenten en leestekens worden weggelaten.

Verplichte parameters

  • nl_city: geef één of meerdere beginletters van een Nederlandse plaats op.

Optionele parameters

  • per_page: het maximaal aantal plaatsen als resultaat. Standaard is dit 10.

Resultaat voorbeeld

undefined/v1/suggest?auth_key=YOUR_AUTH_KEY&per_page=2&nl_city=bergen

Deze aanvraag geeft het volgende resultaat:

{
  "status": "ok",
  "results": [
    {
      "province": "Limburg",
      "municipality": "Bergen",
      "city_key": "bergenbergenlimburg",
      "city": "Bergen (Bergen, Limburg)",
      "official_city": "Bergen",
      "nl_fourpps": "5854",
      "lat": 51.60137,
      "lng": 6.05422
    },
    {
      "province": "Noord-Holland",
      "municipality": "Bergen",
      "city_key": "bergenbergennoordholland",
      "city": "Bergen (Bergen, Noord-Holland)",
      "official_city": "Bergen",
      "nl_fourpps": "1860,1861,1862",
      "lat": 52.66891,
      "lng": 4.70604
    }
  ]
}

Suggest deel 2: het vinden van een straat

Sommige plaatsnamen en/of gemeentenamen komen vaker voor. Deze extra informatie wordt tussen haakjes vermeld achter de plaatsnaam. Om de straatnamen binnen de juiste plaats te vinden wordt hierna de plaats geïdentificeerd door de unieke city_key. Let op: de geldigheid van city_key is beperkt. In de praktijk zal de sleutel ten minste 24 uur geldig zijn.

Verplichte parameters

  • city_key: geef de unieke identificatie van een Nederlandse plaats op, welke bepaald is in stap 1.
  • street: geef één of meerdere beginletters van een Nederlandse straat op binnen de plaats geïdentificeerd door de city_key.

Optionele parameters

  • streetnumber: geef een huisnummer op, om de exacte postcode voor dit huisnummer in de straat als resultaat te verkrijgen.
  • extension: geef een huisnummer toevoeging op, om de exacte postcode voor dit huisnummer in de straat als resultaat te verkrijgen.
  • per_page: het maximaal aantal straten als resultaat. Standaard is dit 10.

Resultaat voorbeeld

undefined/v1/suggest?auth_key=YOUR_AUTH_KEY&per_page=2&street=a&city_key=agZwcm82cHByJQsSDENpdHlTdWdnZXN0MiITYmVyZ2VuYmVyZ2VubGltYnVyZwwa

Deze aanvraag geeft het volgende resultaat:

{
  "status": "ok",
  "results": [
    {
      "street": "Acaciastraat",
      "nl_sixpps": "5854GX",
      "lat": 51.59995,
      "lng": 6.05188
    },
    {
      "street": "Aijen",
      "nl_sixpps": "5854PP,5854PR",
      "lat": 51.58311,
      "lng": 6.0428
    }
  ]
}

Foutmeldingen

  • ‘Parameter city is required’
    Geef de parameter ‘city’ mee aan de webservice. Dit mag zowel in de URL (GET) als in de body (POST).
  • ‘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.
  • ‘city not found’
    Er is geen plaats bekend welke start met de opgegeven letters.
  • ‘invalid city_key’
    De city_key is onbekend.
  • ‘street not found’
    Er is geen straat bekend welke start met de opgegeven letters.
  • ‘Specify either nl_city or city_key’
    Er mist een parameter.

Voorbeeldcode

De suggest methode wordt gedemonstreerd in deze gebruiksklare 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 mReverse.demoTitlep voorbeeld in JavaScript

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

Download onze JavaScript bibliotheek suggest.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 het adres.

<form action="#" class="address">
  City: <input class="city" /> <span class="city_message"></span><br />
  Street: <input class="street" />
  <span class="street_message"></span>
</form>

Stap 2: voeg interactie toe

Voeg de volgende code toe tussen de tags <head> en </head>. Het suggereert mogelijke plaatsnamen terwijl de gebruiker aan het typen is.

<script src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
<link rel="stylesheet" href="https://code.jquery.com/ui/1.11.2/themes/smoothness/jquery-ui.css" />
<script src="https://code.jquery.com/ui/1.11.2/jquery-ui.min.js"></script>
<script src="suggest.js"></script>
<script>
  var pro6pp_auth_key = 'YOUR AUTH_KEY';
  $(document).ready(function() {
    $('.address').applySuggest();
  });
</script>

Stap 3: laat het werken

Voor toegang 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 suggest.html in uw browser. Het is klaar voor gebruik!
Lukt het niet? Probeer de kant-en-klare voorbeeldcode te downloaden.