API beschrijving

Onderstaande methoden zijn beschikbaar in de Pro6PP webservice.

autocomplete: adresgegevens opzoeken bij een postcode.
range: zoek postcodes in de buurt.
locator: zoek postcodes (uit eigen lijst) in de buurt.
suggest: plaatsnaam en straat aanvullen tijdens het typen.
reverse: vertaal coördinaten naar adres (reverse geocoding).
download/metadata ontvang gegevens voor het downloaden van de volledige database.
origin ^Beta : Detecteer locatie van web-gebruiker als coördinaten en plaats.
feedback: nieuwe gegevens aanbieden voor de Pro6PP database.

API methodes

Autocomplete

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.
be_fourpp ^Beta : geef het Belgische postnummer (4 cijfers) op, voor plaats gegevens.

Optionele parameters

streetnumber: geef een huisnummer op. Wanneer deze optionele parameter is meegegeven wordt er ook gecontroleerd op geldigheid van het huisnummer.

Resultaat voorbeeld

http://api.pro6pp.nl/v1/autocomplete?auth_key=YOUR_AUTH_KEY&nl_sixpp=5408xb&format=xml&pretty=True

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

Meer voorbeelden van de autocomplete methode.

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.

Range

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

Verplichte parameters

nl_fourpp: geef de Nederlandse postcode (4 cijfers) op.

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.
page: de gewenste resultaatpagina met daarop ten hoogste 'per_page' resultaten. Standaard is dit pagina 1.

Resultaat voorbeeld

http://api.pro6pp.nl/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},
              {"nl_fourpp":"5403","distance":2984,"lng":5.6349,"lat":51.6659},
              {"nl_fourpp":"5406","distance":3395,"lng":5.6146,"lat":51.6573},
              {"nl_fourpp":"5409","distance":3535,"lng":5.7095,"lat":51.6425},
              {"nl_fourpp":"5402","distance":3707,"lng":5.6186,"lat":51.6658},
              {"nl_fourpp":"5401","distance":3814,"lng":5.6097,"lat":51.6596},
              {"nl_fourpp":"5400","distance":3871,"lng":5.6167,"lat":51.6667},
              {"nl_fourpp":"5427","distance":4719,"lng":5.6787,"lat":51.6029}
            ]
}

Meer voorbeelden van de range methode.

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.

Locator

Gegeven een postcode en een eigen lijst postcodes, geef de dichtstbijzijnde locaties. De uitvoer is gesorteerd van dichtbij naar veraf.

Verplichte parameters

nl_fourpp: geef de Nederlandse postcode (4 cijfers) op.
target_nl_fourpps: geef een lijst van Nederlandse postcodes (4 cijfers) op. Gescheiden door komma's.

Optionele parameters

range: de gewenste omtrek waarin gezocht wordt - in meters. Standaard is dit heel Nederland. Maximale omtrek van 300000.
per_page: het maximaal aantal postcodes als resultaat. Standaard is dit 10.
order ^Beta: distance (standaard) sorteert uitvoer op oplopende afstand van startpunt tot zoekresultaten. input behoudt de volgorde van invoer bij de uitvoer.

Resultaat voorbeeld

http://api.pro6pp.nl/v1/locator?auth_key=YOUR_AUTH_KEY&nl_fourpp=5408&target_nl_fourpps=5652,2987

Deze aanvraag geeft het volgende resultaat:

{"status":"ok",
 "results": [{ "nl_fourpp": 5652,
               "city": "Eindhoven",
               "distance": 25626,
               "lng": 5.46667,
               "lat": 51.45
             },
             { "nl_fourpp": 2987,
               "city": "Ridderkerk",
               "distance": 76263,
               "lng": 4.6,
               "lat": 51.86667
             }
           ]
}

Meer voorbeelden van de locator methode.

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 target_nl_fourpps is required'
Geef de parameter 'target_nl_fourpps' mee aan de webservice. Dit mag zowel in de URL (GET) als in de body (POST).
'Invalid target_nl_fourpps format'
Het formaat dient te bestaan uit steeds 4 postcode cijfers, gescheiden door een komma. Extra spatiëring wordt automatisch gecorrigeerd.
'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 0 and 300000'
Parameter 'range' dient een omtrek (in meters) te bevatten tussen de 0 en 300000.

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

http://api.pro6pp.nl/v1/suggest?auth_key=YOUR_AUTH_KEY&per_page=2&nl_city=berg

Deze aanvraag geeft het volgende resultaat:

{"status":"ok",
 "results": [{ "city_key": "agZwcm82cHByJQsSDENpdHlTdWdnZXN0MiITYmVyZ2VuYmVyZ2VubGltYnVyZww",
               "city": "Bergen (Bergen, Limburg)",
               "official_city": "Bergen",
               "nl_fourpps": "5854",
               "province": "Limburg",
               "lat": 51.60137,
               "lng": 6.05422
             }, {
               "city_key": "agZwcm82cHByKgsSDENpdHlTdWdnZXN0MiIYYmVyZ2VuYmVyZ2Vubm9vcmRob2xsYW5kDA",
               "city": "Bergen (Bergen, Noord-Holland)",
               "official_city": "Bergen",
               "nl_fourpps": "1860,1861,1862",
               "province": "Noord-Holland",
               "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 geidentificeerd door de unieke city_key.

Verplichte parameters

city_key: geef de unieke indenticatie 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 geidentificeerd 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.
per_page: het maximaal aantal straten als resultaat. Standaard is dit 10.

Resultaat voorbeeld

http://api.pro6pp.nl/v1/suggest?auth_key=YOUR_AUTH_KEY&per_page=2&street=b&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
             }
            ]
}

Meer voorbeelden van de suggest methode.

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.

Reverse

Gegeven de locatie (latitude en longitude in minimaal 2 decimalen), ontvang provincie, gemeente, plaats. Bij 4 decimalen wordt ook de 6-karakter postcode en straat geretourneerd.

Verplichte parameters

lat: geef de latitude component van de locatie op.
lng: geef de longitude component van de locatie op.

Resultaat voorbeeld

http://api.pro6pp.nl/v1/reverse?auth_key=YOUR_AUTH_KEY&lat=51.5676&lng=5.0862

Deze aanvraag geeft het volgende resultaat:

{"status": "ok",
 "results": {"precision": 8,
             "province": "Noord-Brabant",
             "municipality": "Tilburg",
             "city": "Tilburg",             
             "streets": ["Veldhovenring"],
             "nl_sixpp": "5041BC",
             "lat": 51.56764,
             "lng": 5.08622}             
}

Meer voorbeelden van de reverse methode.

Download

Toon de gegevens van de laatst beschikbare versie van de te downloaden databases.

Verplichte parameters

asset: geef de gewenste download op. De voor u beschikbare bestandsnamen zijn zichtbaar in het CMS. Bijvoorbeeld "download_nl_sixpp.zip".

Resultaat voorbeeld

http://api.pro6pp.nl/v1/download/metadata?auth_key=YOUR_AUTH_KEY&asset=download_nl_sixpp.zip

Deze aanvraag geeft het volgende resultaat:

{"status": "ok",
 "results": {"last_updated": "201206010000",
             "filesize": 9704236,
             "download_link": "http://api.pro6pp.nl/v1/download?asset=download_nl_sixpp.zip&auth_key=YOUR_AUTH_KEY",
             "md5_hash": "e0380a5fc1c31d64e9388ca1913ddd25"
            }
}

Meer voorbeelden van het verwerken van de downloads.

Origin

Ontvang provincie, gemeente, plaats en locatie van waaruit deze API oproep wordt uitgevoerd.

Gemiddeld genomen is dit accuraat binnen een straal van 5km.

Verplichte parameters

Geen parameters

Resultaat voorbeeld

http://api.pro6pp.nl/v1/origin?auth_key=YOUR_AUTH_KEY

Deze aanvraag geeft het volgende resultaat:

{"status": "ok",
 "results": {"province": "Noord-Brabant",
             "municipality": "Veldhoven",
             "city": "Veldhoven",
             "nl_fourpp": "5501",
             "lat": 51.42,
             "lng": 5.41}             
}

Meer voorbeelden van de origin methode.

Feedback

Het komt voor dat Pro6PP geen straat paraat heeft voor een postcode. Om Pro6PP een handje te helpen kan dit adres worden aangeboden. Na controle zal dit adres worden toegevoegd aan de database.

Verplichte parameters

nl_sixpp: geef de postcode op.
street: geef de straat op.

Optionele parameters

streetnumber: geeft het huisnummer op.

Resultaat voorbeeld

http://api.pro6pp.nl/v1/feedback?auth_key=YOUR_AUTH_KEY&nl_sixpp=9999ZZ&street=knolweg

Deze aanvraag geeft het volgende resultaat:

{"status":"ok",
 "results": []
}

Meer voorbeelden van de feedback methode.

Foutmeldingen

'Parameter nl_sixpp is required'
Geef de parameter 'nl_sixpp' mee aan de webservice. Dit mag zowel in de URL (GET) als in de body (POST).
'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.

Standaard foutmeldingen

De methodes kunnen naast hun specifieke foutmeldingen ook deze algemene foutmeldingen geven:

'Parameter auth_key is required'
De meeste API calls stellen de 'auth_key' parameter verplicht. Dit is de key welke is toegewezen bij het openen van een Pro6PP (proef)account.
'auth_key does not exist'
De 'auth_key' parameter bestaat niet in de database. Controleer op invoerfouten of maak een nieuw Pro6PP (proef)account aan om een nieuwe key te ontvangen.
'auth_key is not activated yet'
Bij aanmelding van een Pro6PP (proef)account is een verificatie email verstuurd. Wanneer de verificatie link in deze email nog niet is bezocht is het account nog niet geactiveerd.
'auth_key has expired'
De geldigheid van het (proef)account is verlopen. Een proefaccount heeft een geldigheid van 2 maanden. Daarna kan de geldigheid worden verlengd in het CMS.
'auth_key has no more credits'
Bij een 'prepaid' abonnement krijgt u een hoeveelheid credits om API calls mee uit te voeren. Al uw credits zijn verbruikt. De credits kunnen worden opgehoogd in het CMS.
'Unable to get required HTTP_REFERER'
Zie de FAQ over beveiliging.
'This request is blocked due to javascript domain security settings'
Zie de FAQ over beveiliging.

Foutmeldingen worden in de volgende vorm getoond. (JSON)

{'status': 'error',
 'results': [],
 'error': {
   'message': 'nl_fourpp not found'
 }
}

#{title}

API beschrijving

API methodes

Autocomplete

Verplichte parameters

Optionele parameters

Resultaat voorbeeld

Foutmeldingen

Range

Verplichte parameters

Optionele parameters

Resultaat voorbeeld

Foutmeldingen

Locator

Verplichte parameters

Optionele parameters

Resultaat voorbeeld

Foutmeldingen

Suggest

Suggest deel 1: het vinden van een plaats

Verplichte parameters

Optionele parameters

Resultaat voorbeeld

Suggest deel 2: het vinden van een straat

Verplichte parameters

Optionele parameters

Resultaat voorbeeld

Foutmeldingen

Reverse

Verplichte parameters

Resultaat voorbeeld

Download

Verplichte parameters

Resultaat voorbeeld

Origin

Verplichte parameters

Resultaat voorbeeld

Feedback

Verplichte parameters

Optionele parameters

Resultaat voorbeeld

Foutmeldingen

Standaard foutmeldingen