API Reverse Geocoder - PDOK/locatieserver GitHub Wiki

Reverse Geocoder

Dit document beschrijft de API van de Reverse Geocoder service van PDOK. Het doel van dit document is om afnemers inzicht te verschaffen hoe ze de reverse geocoder endpoint van de locatieserver kunnen aanspreken. Als search engine wordt Postgresql gebruikt in combinatie met Apache Solr.

De URL is als volgt: https://api.pdok.nl/bzk/locatieserver/search/v3_1/reverse.

De volgende types worden ondersteund:

De volgende types worden gebruikt:

Type Geometrie
provincie vlak
gemeente vlak
woonplaats vlak
weg lijn (uit NWB) of punt (centroïde van de omvattende adressen)
postcode punt (centroïde van de omvattende adressen)
adres punt
perceel vlak
appartementsrecht punten (groep van gekoppelde adressen)
hectometerpaal punt
waterschap vlak
wijk vlak
buurt vlak

De afstanden tot postcodes en tot wegen met een punt geometrie zijn niet accuraat omdat de afstand wordt berekent met een centroide van het vlak of lijn, inplaats van het vlak of lijn.

1. Reverse Geocoder service

Deze service is bedoeld om vanaf een punt de dichtsbijzijnde objecten te vinden.

1.1 Url Parameter

Verplicht: X=<x coördinaat>&Y=<y coördinaat> of lat=<latitude>&lon=<longitude>

| Hiermee wordt het coördinaat in X/Y (RD), of in lat/lon (WGS84) opgegeven. Vanaf dit coördinaat gaat de reverse geocoder zoeken.

Optioneel: rows=<aantal>

Hiermee wordt opgegeven wat het maximale aantal rijen (ofwel resultaten) is dat teruggegeven moet worden op deze bevraging. De default-waarde is "10". De maximum waarde is "50".

Optioneel: start=<index>

Hiermee wordt opgegeven wat de index is van het eerste resultaat dat teruggegeven wordt. Dit is zero-based. In combinatie met de rows-parameter kunnen deze services gepagineerd worden bevraagd. De default-waarde is "0". Gebruik de start parameter in intervallen van "rows" anders werkt de paginering niet goed.

Optioneel: type=<resultaat type>

Hiermee kan worden opgegeven welke resultaat types je terug krijgt in het resultaat. Voor elke type dat je wilt terugkrijgen moet je een aparte type parameter toevoegen, bijv. type=adres&type=gemeente&type=perceel. Met type=* krijg je alle types terug. Deze wordt voor het bepalen van de resultaten gebruikt en heeft dus geen invloed op aantal resultaten dat wordt teruggegeven. De default-waarde is "adres".

Optioneel: distance=<afstand>

Hiermee kan een maximale zoekstraal in meters worden opgegeven. Er zullen dan geen resultaten worden teruggegeven die verder liggen dan deze waarden.

Optioneel: fq=<filter query>

Hiermee kan een filter query worden opgegeven, bijv. fq=bron:BAG. Met fq=* kan de default filter query worden opgeheven. Deze wordt uitgevoerd nadat de dichtsbijzijnde resultaten zijn gevonden, dus resultaten die hier niet aan voldoen worden weggefilterd waardoor je minder resultaten dan het aantal rows kan terugkrijgen. De default-waarde is fq=*:*

Optioneel: fl=<velden>

Hiermee worden de velden opgegeven die teruggegeven dienen te worden. De default-waarde is "id type weergavenaam score afstand". afstand is een nieuw veld, waarin de afstand tot het punt wordt teruggeven in meters afgerond op 2 decimaal.

1.2 Success response

Wanneer er één of meerdere hits gevonden worden, wordt het volgende bericht teruggestuurd met HTTP statuscode 200. Standaard is de output in JSON-formaat.

{
  "response":{
    "numFound":<aantal>,
    "start":0,
    "maxScore":<maxScore>,
    "numFoundExact":true,
    "docs": [
      {   
        "type":"<objecttype>",
        "weergavenaam":"<weergavenaam>",
        "id":"<id>",
        "score":<score>,
        "afstand":<afstand>
      },
      ...
    ]
  }
}

Het docs-attribuut bevat de zoekresultaten. Per zoekresultaat worden de attributen id, weergavenaam, type, score en afstand standaard weergegeven.

1.3 Error response

Wanneer de zoektermen geen resultaten opleveren, wordt het volgende JSON-bericht teruggestuurd met HTTP status code 200.

{
   "response":{
      "numFound":0,
      "start":0,
      "maxScore":0.0,
      "numFoundExact":true,
      "docs":[
         
      ]
   }
}

1.4 Voorbeelden

https://api.pdok.nl/bzk/locatieserver/search/v3_1/reverse?X=194195.304&Y=465885.902

Resultaat:

{
   "response":{
      "numFound":10,
      "start":0,
      "maxScore":7.2798786,
      "numFoundExact":true,
      "docs":[
         {
            "type":"adres",
            "weergavenaam":"Laan van Westenenk 701, 7334DP Apeldoorn",
            "id":"adr-b78fd594f712007b916132b5c5e0480d",
            "score":7.2798786,
            "afstand":0.0
         },
         {
            "type":"adres",
            "weergavenaam":"Laan van Westenenk 731A, 7334DL Apeldoorn",
            "id":"adr-b721478e3a7df933eab19832c2be8f3a",
            "score":7.2798786,
            "afstand":57.52
         },
         {
            "type":"adres",
            "weergavenaam":"Laan van Westenenk 733A, 7334DL Apeldoorn",
            "id":"adr-e2cd56598ac0b60edc2eb04f0c894ca0",
            "score":7.2798786,
            "afstand":60.96
         },
         {
            "type":"adres",
            "weergavenaam":"Evert van 't Landstraat 20, 7334DR Apeldoorn",
            "id":"adr-365b1d2e8312630e44678e2630987405",
            "score":7.2798786,
            "afstand":61.95
         },
         {
            "type":"adres",
            "weergavenaam":"Evert van 't Landstraat 30A, Apeldoorn",
            "id":"adr-bc02f44b1fd9cc566fdcb321d1a32048",
            "score":7.2798786,
            "afstand":63.99
         },
         {
            "type":"adres",
            "weergavenaam":"Evert van 't Landstraat 22, 7334DR Apeldoorn",
            "id":"adr-e97ef16ada221115eae3809292a97c52",
            "score":7.2798786,
            "afstand":64.37
         },
         {
            "type":"adres",
            "weergavenaam":"Laan van Westenenk 737A, 7334DL Apeldoorn",
            "id":"adr-6f5bab02b6e4cde548c66ad14e28eab8",
            "score":7.2798786,
            "afstand":68.19
         },
         {
            "type":"adres",
            "weergavenaam":"Laan van Westenenk 735, 7334DL Apeldoorn",
            "id":"adr-e0e5a2dfc3b58419632c42da7a583ba8",
            "score":7.2798786,
            "afstand":69.1
         },
         {
            "type":"adres",
            "weergavenaam":"Evert van 't Landstraat 24, 7334DR Apeldoorn",
            "id":"adr-2276c5ecf64b33c3732082a7e2630526",
            "score":7.2798786,
            "afstand":69.76
         },
         {
            "type":"adres",
            "weergavenaam":"Evert van 't Landstraat 26, 7334DR Apeldoorn",
            "id":"adr-316a22b540b069ec40db69f7fd90767a",
            "score":7.2798786,
            "afstand":72.25
         }
      ]
   }
}

De 10 dichtsbijzijnde adressen vanaf de Laan van Westenenk 701, Apeldoorn. Het punt 194195.304,465885.902 zijn de rd-coördinaten van dit adres. Omdat rows standaard op 10 staat worden er maar 10 resultaten teruggestuurd, en omdat type standaard op adres staat worden er alleen adressen teruggestuurd.

https://api.pdok.nl/bzk/locatieserver/search/v3_1/reverse?X=194195.304&Y=465885.902&type=*&rows=30&distance=50

{
   "response":{
      "numFound":20,
      "start":0,
      "maxScore":15.870522,
      "numFoundExact":true,
      "docs":[
         {
            "type":"provincie",
            "weergavenaam":"Provincie Gelderland",
            "id":"pro-0f6c28f4b7319a68ded823f1a7d5ae49",
            "score":15.870522,
            "afstand":0.0
         },
         {
            "type":"gemeente",
            "weergavenaam":"Gemeente Apeldoorn",
            "id":"gem-a8a3618706b1ef00688847ed363baf47",
            "score":13.600058,
            "afstand":0.0
         },
         {
            "type":"woonplaats",
            "weergavenaam":"Apeldoorn, Apeldoorn, Gelderland",
            "id":"wpl-0bec2fbac4d93b0212919b83b1e08f00",
            "score":12.243917,
            "afstand":0.0
         },
         {
            "type":"postcode",
            "weergavenaam":"Laan van Westenenk, 7334DP Apeldoorn",
            "id":"pcd-994b971da40eb04abe3b15b1de7725af",
            "score":7.537676,
            "afstand":0.0
         },
         {
            "type":"adres",
            "weergavenaam":"Laan van Westenenk 701, 7334DP Apeldoorn",
            "id":"adr-b78fd594f712007b916132b5c5e0480d",
            "score":7.2798786,
            "afstand":0.0
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 4095",
            "id":"pcl-c8382cce222560670c36408719f35688",
            "score":7.133731,
            "afstand":0.0
         },
         {
            "type":"waterschap",
            "weergavenaam":"Waterschap Vallei en Veluwe",
            "id":"wsa-eff09d1d0bfe5b7389c943040484ba55",
            "score":6.9706764,
            "afstand":0.0
         },
         {
            "type":"buurt",
            "weergavenaam":"Wernem Apeldoorn",
            "id":"buu-dfdc913b13268c39ff427137f47a2850",
            "score":6.9706764,
            "afstand":0.0
         },
         {
            "type":"wijk",
            "weergavenaam":"Zuidwest Apeldoorn",
            "id":"wij-8a83b5abd27f99ca0fa9bac353844602",
            "score":6.9706764,
            "afstand":0.0
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 4094",
            "id":"pcl-401ebc073563e5ed8473204fc6784398",
            "score":7.133731,
            "afstand":10.3
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 5152",
            "id":"pcl-48816ebf3281b60d3800198e40c48a73",
            "score":7.133731,
            "afstand":21.95
         },
         {
            "type":"weg",
            "weergavenaam":"Laan van Westenenk, Apeldoorn",
            "id":"weg-562fa6cf1b6d38ffce8c4a2079f6463d",
            "score":9.024909,
            "afstand":25.15
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 4443",
            "id":"pcl-8c35d5f6b13120d0be444d4e1623901d",
            "score":7.133731,
            "afstand":28.21
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 5236",
            "id":"pcl-42b34ecb7e5d77ac6a70baf30a06c6e7",
            "score":7.133731,
            "afstand":28.35
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 4096",
            "id":"pcl-b24f6552c35e306f6a12ecde68d0516d",
            "score":7.133731,
            "afstand":30.7
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 4359",
            "id":"pcl-c4a3a73c9237d429d34ff65cb4f81610",
            "score":7.133731,
            "afstand":38.1
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 5216",
            "id":"pcl-ce66d022bf9276370547b07af8176704",
            "score":7.133731,
            "afstand":39.72
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 4097",
            "id":"pcl-bce7abdb5c986d6643d6eafb6495984e",
            "score":7.133731,
            "afstand":41.79
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 4093",
            "id":"pcl-2eee5ea97296d24f77a30348d75345aa",
            "score":7.133731,
            "afstand":48.43
         },
         {
            "type":"perceel",
            "weergavenaam":"Perceel Apeldoorn (APD03) AD 5215",
            "id":"pcl-6480fe8a03c4db231207c5509c01122b",
            "score":7.133731,
            "afstand":48.46
         }
      ]
   }
}

Deze zoekterm levert de 30 resultaten die binnen 50 meter van het punt bevinden. Vanwege type=* worden alle types meegenomen. Er zijn maar 20 resultaten die binnen 50 meter van het punt bevinden dus er zijn maar 20 resultaten teruggestuurd. En alle vlak geometrieën waar het punt in ligt hebben een afstand van 0.0 tot het punt.

⚠️ **GitHub.com Fallback** ⚠️