Dit document beschrijft de API van Locatieserver, de geocodeerservice van PDOK. Alle ondersteunde endpoints die via deze service beschikbaar komen, worden hier beschreven. Het doel van dit document is om afnemers inzicht te verschaffen hoe ze de services van Locatieserver kunnen aanspreken. Als search engine wordt Apache Solr gebruikt.

De dienst Locatieserver ontsluit op dit moment 4 services, die ieder een eigen endpoint hebben, nl:

• suggest: bedoeld om dynamisch locaties te vinden, bijv. d.m.v. autocomplete;
• lookup: bedoeld om gedetailleerde informatie over één object op te vragen;
• free: bedoeld als "klassieke" geocodeerservice;
• reverse: bedoeld om vanaf een punt de dichtsbijzijnde objecten te vinden.

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

Wanneer een geo-referentieobject (bijv. een adres of woonplaats) d.m.v. intypen gezocht moet worden, dan moet de suggest-service gebruikt worden. Deze is geschikt voor toepassingen die gebruik maken van autocomplete, vanwege de (relatief) kleine antwoorden en het gebruik van highlighting. Wanneer hiervan een object geselecteerd wordt, kan het ID-property van één van de teruggegeven objecten worden gebruikt om meer informatie op te vragen d.m.v. de lookup-service. De vrije geocodeerservice (het "free" endpoint) is bedoeld voor het klassieke geocoderen, waarbij een string (een adres, e.d.) wordt meegegeven en een lijst met matches wordt teruggegeven. De vrije geocodeerservice komt het meest overeen met de functionaliteit van de oude PDOK geocoder. De reverse-service is bedoeld om op basis van een punt de dichtsbijzijnde objecten te vinden. Voor meer informatie zie de inleidende teksten in de hoofdstukken voor de suggest-, lookup-, reverse- en vrije geocoderservices.

Leeswijzer:

1. Allereerst worden de generieke parameter van de Solr-services beschreven;
2. Vervolgens wordt een beschrijving geven van de algemene zoektermen;
3. Hierna wordt de suggest-service beschreven, ...
4. ... gevolgd door de lookup-service ...
5. ... dan de vrije geocoder-service ...
6. ... en tenslotte door de reverse geocoder-service.

Een aantal parameters van de services die gebruik maken van Solr zijn generiek.

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" en het maximum 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" en het maximum is "10.000".

Optioneel: lat=<latitude>&lon=<longitude>

Hiermee kan een coördinaat (in lat/lon, ofwel WGS84) worden opgegeven. Met behulp van deze parameters worden de gevonden zoekresultaten gesorteerd op afstand van het meegegeven punt. Wanneer de locatie van de gebruiker bekend is, kan op deze manier effectiever worden gezocht.

Het meegeven van een coördinaat is met name nuttig voor de suggest- en vrije geocoder-services. Hier worden meestal meerdere resultaten teruggegeven. Als decimaal scheidingsteken moet een punt worden opgegeven i.p.v. een komma.

Voorbeeld: lat=52.09&lon=5.12

De resultaten worden gesorteerd op afstand van een bepaald punt in het centrum van Utrecht.

Optioneel: fq=<filter query>

Hiermee kan een filter query worden opgegeven, bijv. fq=bron:BAG. De default filter voor de suggest- en vrije geocoder-services is type:(gemeente OR woonplaats OR weg OR postcode OR adres)

Het gebruik van zoektermen bij de Solr-services verdient een eigen hoofdstuk. Dit is vanwege de complexiteit en de regels die hierop toegepast worden. Bij de suggest- en vrije geocoder-services wordt de q-parameter gebruikt om zoektermen op te geven. Bij de lookup-service wordt de id-parameter gebruikt (alleen voor de unieke ID). De reverse geocoder gebruikt de X/Y-parameter of de lat/lon-parameter

Om de kans op succesvolle matches bij met name adressen en straatnamen te verhogen, wordt toegestaan dat waarden niet exact overeen komen. De volgende regels worden losgelaten op velden waarin straatnamen en woonplaatsen zitten. Deze zijn ook van toepassing op het vrije-service.

• De zoektermen zijn niet hoofdlettergevoelig. In de index en bij het bevragen worden alle zoektermen naar kleine letters omgezet, zodat de vergelijking niet hoofdlettergevoelig is.
• Accenten zijn optioneel. Karakters met accenten worden zowel bij het indexeren als bij het bevragen omgezet naar hun equivalenten zonder accenten. Voorbeeld: de Rhônedreef in Utrecht kan worden gevonden wanneer er wordt gezocht op "rhonedreef".
• Voor titels en een aantal andere afkortingen kunnen synoniemen worden opgegeven. Dus de Burgemeester Fockema Andreaelaan kan worden gevonden worden wanneer er wordt gezocht op "burg fockema andreaelaan". Hetzelfde geldt voor "1e" versus "eerste", etc.
• Ook kunnen straatnamen worden ingekort. Dit is met name handig om adressen te zoeken vanuit een ander systeem, waar afgekorte straatnamen zijn gebruikt (de zogeheten PTT-afkortingen). Bijv. "straat" kan worden ingekort tot "str", "weg" tot "wg", "singel" tot "sngl", etc.
• Alle leestekens in straat- en plaatsnamen worden genegeerd. Zo is het bij titels of voorletters niet nodig om een punt op te geven. Dit geldt ook voor de apostrof en het koppelteken in "’s-Gravenhage". De officiële BAG-schrijfwijze is hier niet eenduidig in.

Let op dat deze regels niet in het algemeen gelden. Het omzetten naar kleine letters wordt bij veel velden toegepast, maar niet overal.

Bij het matchen zijn er enkele beperkingen. Bij gebruik van de q-parameter hoeven niet alle delen van een straat- of plaatsnaam te worden opgegeven. Dit is handig wanneer bijv. niet alle titels en voorletters bekend zijn (bijv. Plompstraat i.p.v. Wethouder D.M. Plompstraat), maar niet handig indien dit tot meerdere resultaten leidt. De zoekterm "Bolstraat" levert ook Ferdinand Bolstraat op, maar de Bolstraat heeft een hogere score.

Een andere beperking is dat voorletters en -namen niet uitwisselbaar zijn, dus de "Maarten Trompstraat" kan niet worden gevonden wanneer er op de "M. Trompstraat" wordt gezocht. Dit zou een heel lange synoniemenlijst opleveren. Het risico op valse matches zou daardoor heel groot worden, wat niet wenselijk is.

Bij de vrije geocoder mogen delen van straatnamen worden weggelaten. Als er wordt gezocht op "weth plompstraat", zal ook de Wethouder D.M. Plompstraat gevonden worden. Bij de unieke adressen-service is dit niet mogelijk, zoals hierboven vermeld is.

Postcodes kunnen zowel met als zonder spatie worden opgegeven tussen de cijfers en letters. Ook mogen de letters met kleine letters worden opgegeven.

Enkele woonplaatsen zijn in de synoniemenlijst opgenomen. Dit zijn "Den Bosch" voor ’s-Hertogenbosch en "Den Haag" voor ’s-Gravenhage.

Voor provincies geldt dat zowel de namen als de afkortingen (Gr, Fr, etc.) opgegeven kunnen worden.

Naast de inhoudelijke zoekvelden, zijn er ook zoekvelden die metadata bevatten. Dit betreft het objecttype / entiteit (veld: type) en de bron (veld: bron).

Geldige waarden voor type zijn:

• provincie;
• gemeente;
• woonplaats;
• weg;
• postcode;
• adres;
• perceel;
• hectometerpaal;
• wijk;
• buurt;
• waterschapsgrens;
• appartementsrecht.

Geldige waarden voor bron zijn:

• BAG: Basisregistratie Adressen en Gebouwen;
• NWB: Nationaal Wegen Bestand;
• BAG/NWB: BAG openbareruimtes die gekoppeld zijn met NWB wegen;
• DKK: Digitale Kadastrale Kaart;
• Bestuurlijke Grenzen;
• CBS: Centraal Bureau voor de Statistiek;
• HWH: Het Waterschapshuis.

Als je bron:BAG of bron:NWB invult krijg je ook alle BAG danwel NWB resultaten. Als je bron:BAG/NWB invult krijg je ook alle bron:BAG en bron:NWB resultaten. Dit wordt namelijk omgezet naar bron:BAG of bron:NWB. Als je bron:BAG/NWB invult krijg je alleen de bron:BAG/NWB resultaten.

Met Solr wordt in principe de q-parameter gebruikt om de zoekvraag te stellen. Het is mogelijk om complexe queries samen te stellen. De meest relevante mogelijkheden zijn:

• Gebruik logische operatoren. D.m.v. het toevoegen van "and" of "or" kunnen zoektermen worden gecombineerd. Met "and" moeten alle zoektermen worden gebruikt voor een match en met "or" is het voldoende dat één zoekterm een match oplevert. De default logische operator is "or". Het mixen van logische operatoren (bijv: (a and b) or c) wordt afgeraden. Dit lijkt niet helemaal lekker te werken in Solr.
  • De "not"-operator kan worden toegepast door een minteken voor de zoekterm te zetten. Het is verstandig om dan de zoekterm binnen quotes te zetten, indien er geen veldnaam aan vooraf gaat, zodat de zoekterm als één term wordt beschouwd.
• Gebruik dubbele quotes voor zoektermen die uit meerdere woorden bestaan. D.m.v. het toevoegen van dubbele quotes, bijv. "De Bilt" wordt afgedwongen dat er pas een match is als de woorden "de" en "bilt" achtereenvolgens voorkomen. Als de quotes worden weggelaten, wordt dit in principe door Solr geïnterpreteerd als de or bilt.
• Gebruik veldnamen (contextgevoelig zoeken). D.m.v. het toevoegen van veldnamen voor de daadwerkelijke zoektermen kan het default zoekveld worden aangepast. Bijv. bij q=Utrecht wordt gezocht in het default zoekveld (tekst bij de vrije geocoder), maar bij q=woonplaatsnaam:Utrecht wordt gezocht in het veld woonplaatsnaam.
  • Als bij een veldnaam een asterisk wordt opgegeven, bijv. huisletter:*, dan worden alle waarden geaccepteerd, mits de waarde niet null is (dus gevuld).
  • In combinatie met het minteken (not-operator) kan worden afgedwongen dat een veld een null-waarde bevat (dus leeg is), bijv. -huisletter:*.
• In plaats van de q-parameter, kan ook de fq-parameter (filter query) worden gebruikt om een filtering toe te passen. De voordelen hiervan zijn dat deze filtering door Solr gecached kan worden en deze geen invloed heeft op de berekening van de score.

Deze service is bedoeld voor het vinden van suggesties voor verschillende geo-referentieobjecten o.b.v. een opgegeven zoekterm. Deze service is specifiek bedoeld om te implementeren in combinatie met de lookup service in een zoekveld voor geo-referentieobjecten in een applicatie. In het zoekveld zullen dan steeds op basis van het al ingetypte deel van de zoekterm enkele suggesties worden gegeven voor mogelijk gezochte objecten (wegen, adressen, plaatsen, gebieden e.d.). De lijst wordt verkort of meer exact naarmate een groter deel van het gezochte object wordt ingetypt. Vervolgens kan het gezochte object worden gekozen, waarna met behulp van de lookup service de details van het object worden opgehaald.

De URL van het request voor de suggest-service wordt als volgt opgebouwd: https://api.pdok.nl/bzk/locatieserver/search/v3_1/suggest

Let op dat voor parameterwaarden de normale URL-encodingregels in acht genomen moeten worden, dus een spatie dient onder water vervangen te worden door het plus-teken.

De volgende parameters zijn in de suggest-service gefixeerd. Deze kunnen niet worden gewijzigd.

• df (default field): waarde = "suggest". Er wordt alleen in het suggest-veld in de index gezocht.

De sortering is niet gefixeerd. De teruggegeven objecten worden nu allereerst op de match-score, vervolgens op een eventueel sorteerveld (bijv. huisnummers + huisletters, zodat de nummers 1 t/m 9 voor 10 en verder komen) en tenslotte op de weergavenaam. De sortering kan worden aangepast door de sort-parameter mee te geven, zie onder.

In de suggest-service kunnen standaard alleen de objecten worden bevraagd waarover in de klankbordgroep van Locatieserver consensus over bestaat. Dit betreft momenteel alleen de gemeenten, woonplaatsen, wegen, postcodes, en adressen. Om ook de andere types op te vragen, zoals percelen of hectometerpalen, dient de parameter fq=*:* te worden toegevoegd aan de query string. Hetzelfde geldt voor de free-service.

Verplicht: q=<zoektermen> Hiermee worden de zoektermen opgegeven. De Solr-syntax voor zoektermen kan hier worden toegepast, bijv. combineren met "and", en het gebruik van dubbele quotes voor opeenvolgende zoektermen. Zoektermen mogen incompleet zijn. Ook wordt er gebruik gemaakt van synoniemen.

Voorbeelden: q=Utrecht: geeft resultaten terug met de zoekterm Utrecht, bijv. adressen in de stad Utrecht, woonplaatsen en gemeenten in de provincie Utrecht.

q="De Bilt": geeft resultaten terug met de zoekterm De Bilt, bijv. de woonplaats en gemeente De Bilt, of adressen in deze woonplaats. Let op dat bij het daadwerkelijk verzenden van het request onder water de URL-encodingregels toegepast worden, dus een spatie wordt verzonden als een plusteken.

q="Sint Jacob" Utre: geeft o.a. adressen terug waarvan er delen achtereenvolgens beginnen met "Sint" en "Jacob", of met "St" (synoniem) en "Jacob", en waar ook een deel met "Utre" begint. Een voorbeeld is het adres St.-Jacobsstraat 200 (officiële schrijfwijze) in Utrecht.

Optioneel: fl=<velden> Hiermee worden de velden opgegeven die teruggegeven dienen te worden. De default-waarde is "id,weergavenaam,type,score".

Optioneel: sort=<sortering> Hiermee kan worden opgegeven hoe de sortering plaatsvindt. De defaultwaarde is score desc, sortering asc, weergavenaam asc. Door voor deze string typesortering asc toe te voegen, kan de oude sortering worden gebruikt.

De betekenis van de velden is als volgt:

• score: de door Solr berekende score. Zie paragraaf 6.1 voor meer informatie.
• sortering: aanvullende sortering voor adressen o.b.v. huisnummers + huisletters, alsmede voor percelen o.b.v. secties en perceelnummers.
• weergavenaam: een leesbare naam die wordt gebruikt om het geo-referentieobject op een eenduidige manier mee te beschrijven.
• typesortering: een door PDOK toegekende "standaard" volgorde voor objecttypen. Bij de op de BAG gebaseerde gegevens gaat dit van groot naar klein (gemeente, woonplaats, weg, postcode, adres).

Optioneel: qf=<query fields> Met behulp van deze parameter kan aan bepaalde velden een extra boost worden meegegeven. Hiermee kan de scoreberekening worden aangepast. De defaultwaarde is exacte_match^1 suggest^0.5 huisnummer^0.5 huisletter^0.5 huisnummertoevoeging^0.5. Om alleen van het suggest-veld gebruik te maken, kan qf=suggest worden meegegeven.

Optioneel: bq=<boost query> Met behulp van deze parameter kan aan bepaalde veldwaarden een extra boost worden meegegeven. Ook hiermee kan de scoreberekening worden aangepast. Dit gebeurt alleen o.b.v. de inhoud van het veld "type". De defaultwaarde is 'type:provincie^1.5 type:gemeente^1.5 type:woonplaats^1.5 type:weg^1.5 type:postcode^0.6 type:adres^1. De overige typen (nog niet aanwezig) hebben geen boost. Voor elke boost query moet een aparte bq=<boost> worden gebruikt. Bijvoorbeeld: bq=type:gemeente^1.5&bq=type:woonplaats^1.5.

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": [
      {
        "id":"<id>",
        "weergavenaam":"<weergavenaam>",
        "type":"<objecttype>"
      },
      ...
    ]
  },
  "highlighting": {
    "<id>": {
      "suggest": ["<spellingssuggestie>"]
    },
    ...
  },
  "spellcheck": {
    "suggestions": []
  }
}

Het docs-attribuut bevat de zoekresultaten. Per zoekresultaat worden de attributen id, weergavenaam en type weergegeven. Het highlighting-attribuut bevat een lijst met de volledige zoektermen, waarbij de matches aangegeven zijn d.m.v. HTML b-tags (bold). Het spellcheck-attribuut is leeg wanneer er resultaten gevonden zijn.

Wanneer de opgegeven zoekterm geen resultaten oplevert, wordt het volgende JSON-bericht teruggestuurd met HTTP statuscode 200. Hierbij zijn suggesties opgegeven in het spellcheck attribuut.

{
  "response":{
    "numFound": 0,
    "start": 0,
    "maxScore": <maxScore>,
    "numFoundExact": true,
    "docs": [],
  },
  "highlighting": {},
  "spellcheck": {
    "suggestions": [
      "<zoekterm>", 
      {
        "numFound": <aantal>,
        "startOffset":0,
        "endOffset": <aantal>,
        "suggestion":
          [
            "<suggestie 1>",
            "<suggestie 2>",
            ...
          ]
      },
    ],
    "collations": [
      "collation",
      {
        "collationQuery": "<zoekterm>",
        "hits": <aantal>,
        "misspellingsAndCorrections": [
            "<suggestie 1>",
            "<suggestie 2>",
            ...
        ]
      }
      ...
    ]
  }
}

https://api.pdok.nl/bzk/locatieserver/search/v3_1/suggest?q="Sint Jac" Utre

Resultaat:

{
  "response": {
    "numFound": 112,
    "start": 0,
    "maxScore": 8.606185,
    "numFoundExact": true,
    "docs": [
      {
        "type": "weg",
        "weergavenaam": "St.-Jacobsstraat, Utrecht",
        "id": "weg-77747d78cd19a6105be25b3e96443feb",
        "score": 8.606185
      },
      ...
    ]
  },
  "highlighting": {
    "weg-77747d78cd19a6105be25b3e96443feb": {
      "suggest": ["<b>St.-Jacobsstraat</b>, <b>Utrecht</b>"]
    },
    ...
  },
  "spellcheck": {
    "suggestions": [],
    "collations": []
  }
}

Er zijn 112 zoekresultaten gevonden. Bij de highlighting is te zien voor welke zoektermen er een match is. In de browser wordt dit als volgt weergegeven: St.-Jacobsstraat, Utrecht (zonder extra formattering).

https://api.pdok.nl/bzk/locatieserver/search/v3_1/suggest?q=Utreg

Resultaat:

{
   "response":{
      "numFound":0,
      "start":0,
      "maxScore":0,
      "numFoundExact":true,
      "docs":[
         
      ]
   },
   "highlighting":{
      
   },
   "spellcheck":{
      "suggestions":[
         "utreg",
         {
            "numFound":5,
            "startOffset":0,
            "endOffset":5,
            "suggestion":[
               "utrec",
               "uterg",
               "utre",
               "utrech",
               "uitweg"
            ]
         }
      ],
      "collations":[
         "collation",
         {
            "collationQuery":"utrec",
            "hits":188634,
            "misspellingsAndCorrections":[
               "utreg",
               "utrec"
            ]
         },
         "collation",
         {
            "collationQuery":"uterg",
            "hits":28,
            "misspellingsAndCorrections":[
               "utreg",
               "uterg"
            ]
         },
         "collation",
         {
            "collationQuery":"utre",
            "hits":188634,
            "misspellingsAndCorrections":[
               "utreg",
               "utre"
            ]
         }
      ]
   }
}

Er zijn nu geen zoekresultaten gevonden. Wanneer de zoekterm "Utreg" wordt gebruikt, is te zien dat de zoekterm "utrec" veruit de meeste resultaten op zal leveren. Een applicatie zou deze suggesties kunnen gebruiken om verbeteringen voor te stellen.

Deze service is bedoeld voor het opvragen van informatie over één geo-referentieobject dat eerder was gevonden met behulp van de suggest-service. Deze service is specifiek bedoeld om te implementeren in combinatie met de suggest-service in een zoekveld voor geo-referentieobjecten in een applicatie. In het zoekveld zullen dan steeds op basis van het al ingetypte deel van de zoekterm enkele suggesties worden gegeven voor mogelijk gezochte objecten (wegen, adressen, plaatsen, gebieden e.d.). De lijst wordt verkort of meer exact naarmate een groter deel van het gezochte object wordt ingetypt. Vervolgens kan het gezochte object worden gekozen, waarna met behulp van de lookup-service de details van het object worden opgehaald.

De URL van het request voor de lookup-service wordt als volgt opgebouwd: https://api.pdok.nl/bzk/locatieserver/search/v3_1/lookup?id=<object-id>

Bij de lookup-service moet de id-parameter worden gebruikt om het ID op te geven van het object waar naar gezocht dient te worden. De waarde van het ID kan worden bepaald door gebruik te maken van de suggest-service, of deze kan uit een extern systeem komen waar dit ID eerder in is opgeslagen.

Let op: het ID dat gebruikt wordt, is het ID dat in Solr opgeslagen is. Het is altijd een 128-bit hexadecimale waarde, ofwel een string met 32 karakters. Deze wordt voorafgegaan door een prefix, zodat het objecttype gemakkelijk hieraan te herkennen is. BAG-ID's worden sinds versie 3 hier niet meer rechtstreeks voor gebruikt. Je kunt nog wel blijven zoeken op BAG ID's. Om dit te doen, dien je gebruik maken van het betreffende ID veld bij de vrije geocodeerservice (bijv. https://api.pdok.nl/bzk/locatieserver/search/v3_1/free?q=nummeraanduiding_id:x , zie ook paragraaf 2.2).

Verplicht: id=<object-id> Hiermee wordt het object-ID opgegeven.

Voorbeelden: id=adr-bf54db721969487ed33ba84d9973c702: geeft het bijbehorende object terug. Dit is een adres-object (type = adres) uit de BAG van het adres Europalaan 93 te Utrecht.

id=weg-fd3b1f1837e947429bd051ff16b1aa73: geeft het bijbehorende object terug. Dit is een openbare ruimte-object (type = weg) uit de BAG die gekoppeld is aan een weg uit het NWB van de Europalaan te Utrecht.

Optioneel: fl=<velden> Hiermee worden de velden opgegeven die teruggegeven dienen te worden. De default-waarde is "id identificatie weergavenaam bron type subtype openbareruimte id nwb_id openbareruimtetype straatnaam straatnaam_verkort adresseerbaarobject_id nummeraanduiding_id huisnummer huisletter huisnummertoevoeging huis_nlt postcode buurtnaam buurtcode wijknaam wijkcode woonplaatscode woonplaatsnaam gemeentecode gemeentenaam provinciecode provincienaam provincieafkorting kadastraal_object_id kadastrale_gemeentecode kadastrale_gemeentenaam kadastrale_sectie perceelnummer kadastrale_grootte gekoppeld_perceel volgnummer gekoppeld_appartement kadastrale_aanduiding wegnummer hectometernummer zijde hectometerletter waterschapsnaam waterschapscode rdf_seealso centroide_ll centroide_rd boundingbox_ll boundingbox_rd". In versie 2 van het lookup-endpoint worden de attributen die met de kadastrale kaart, wijken en buurten, of waterschappen te maken hebben niet teruggegeven.

Let op dat alleen de velden worden teruggegeven die ook daadwerkelijk een waarde bevatten. Null-waarden worden niet teruggegeven. Merk op dat de velden geometrie_ll en geometrie_rd niet standaard worden teruggegeven. Dit komt omdat de geometrie in veel gevallen niet nodig zijn, laat staan dat deze in zowel lat/lon als RD nodig is. De geometrieën van gemeenten en woonplaatsen worden door zeer lange strings weergegeven, wat de response body veel groter maakt. De geometrievelden kunnen worden opgevraagd door de parameter fl=id,geometrie_ll/rd,... of fl=* mee te geven.

Wanneer er een document met het opgegeven ID gevonden wordt, wordt het volgende bericht teruggestuurd met HTTP statuscode 200. Standaard is de output in JSON-formaat.

{
   "response":{
      "numFound":1,
      "start":0,
      "maxScore":7.2028637,
      "numFoundExact":true,
      "docs":[
         {
            "bron":"BAG",
            "woonplaatscode":"3295",
            "type":"adres",
            "woonplaatsnaam":"Utrecht",
            "wijkcode":"WK034408",
            "huis_nlt":"93",
            "openbareruimtetype":"Weg",
            "buurtnaam":"Bedrijvengebied Kanaleneiland",
            "gemeentecode":"0344",
            "rdf_seealso":"http://bag.basisregistraties.overheid.nl/bag/id/nummeraanduiding/0344200000128086",
            "weergavenaam":"Europalaan 93, 3526KP Utrecht",
            "straatnaam_verkort":"Europaln",
            "id":"adr-bf54db721969487ed33ba84d9973c702",
            "gekoppeld_perceel":[
               "UTT00-R-364",
               "UTT00-R-365"
            ],
            "gemeentenaam":"Utrecht",
            "buurtcode":"BU03440821",
            "wijknaam":"Wijk 08 Zuidwest",
            "identificatie":"0344010000006589-0344200000128086",
            "openbareruimte_id":"0344300000000177",
            "waterschapsnaam":"Hoogheemraadschap De Stichtse Rijnlanden",
            "provinciecode":"PV26",
            "postcode":"3526KP",
            "provincienaam":"Utrecht",
            "centroide_ll":"POINT(5.10696041 52.06415055)",
            "nummeraanduiding_id":"0344200000128086",
            "waterschapscode":"14",
            "adresseerbaarobject_id":"0344010000006589",
            "huisnummer":93,
            "provincieafkorting":"UT",
            "centroide_rd":"POINT(135782.745 452910.011)",
            "straatnaam":"Europalaan"
         }
      ]
   }
}

Het docs-attribuut bevat de zoekresultaten. De teruggegeven velden zijn de standaard velden zoals hierboven genoemd. De velden met null-waarden worden weggelaten door Solr.

Let op: de volgorde van de velden is random. Bij het opnieuw indexeren van de data of wanneer het request door een andere server wordt beantwoord, kan de volgorde wijzigen.

Wanneer het opgegeven ID geen resultaten oplevert, wordt het volgende JSON-bericht teruggestuurd met HTTP statuscode 200.

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

Wanneer het ID wordt weggelaten, wordt het volgende bericht teruggestuurd met HTTP status code 400.

parameter "id" in query has an error: value is required but missing

https://api.pdok.nl/bzk/locatieserver/search/v3_1/lookup?id=adr-bf54db721969487ed33ba84d9973c702

Resultaat:

{
   "response":{
      "numFound":1,
      "start":0,
      "maxScore":7.2028704,
      "numFoundExact":true,
      "docs":[
         {
            "bron":"BAG",
            "woonplaatscode":"3295",
            "type":"adres",
            "woonplaatsnaam":"Utrecht",
            "wijkcode":"WK034408",
            "huis_nlt":"93",
            "openbareruimtetype":"Weg",
            "buurtnaam":"Bedrijvengebied Kanaleneiland",
            "gemeentecode":"0344",
            "rdf_seealso":"http://bag.basisregistraties.overheid.nl/bag/id/nummeraanduiding/0344200000128086",
            "weergavenaam":"Europalaan 93, 3526KP Utrecht",
            "straatnaam_verkort":"Europaln",
            "id":"adr-bf54db721969487ed33ba84d9973c702",
            "gekoppeld_perceel":[
               "UTT00-R-364",
               "UTT00-R-365"
            ],
            "gemeentenaam":"Utrecht",
            "buurtcode":"BU03440821",
            "wijknaam":"Wijk 08 Zuidwest",
            "identificatie":"0344010000006589-0344200000128086",
            "openbareruimte_id":"0344300000000177",
            "waterschapsnaam":"Hoogheemraadschap De Stichtse Rijnlanden",
            "provinciecode":"PV26",
            "postcode":"3526KP",
            "provincienaam":"Utrecht",
            "centroide_ll":"POINT(5.10696041 52.06415055)",
            "nummeraanduiding_id":"0344200000128086",
            "waterschapscode":"14",
            "adresseerbaarobject_id":"0344010000006589",
            "huisnummer":93,
            "provincieafkorting":"UT",
            "centroide_rd":"POINT(135782.745 452910.011)",
            "straatnaam":"Europalaan"
         }
      ]
   }
}

Dit is hetzelfde voorbeeld dat bij de success response getoond wordt.

Deze service is bedoeld voor het vinden van zo goed mogelijke matches voor alle typen geo-referentieobjecten die in de voorziening beschikbaar zijn op basis van een opgegeven zoekterm, eventueel in combinatie met een XY-coördinaat van een locatie.

De URL van het request voor de vrije geocoder-service wordt als volgt opgebouwd: https://api.pdok.nl/bzk/locatieserver/search/v3_1/free?q=<zoektermen>

Let op dat voor parameterwaarden de normale URL-encodingregels in acht genomen moeten worden, dus een spatie dient onder water vervangen te worden door het plus-teken, enz.

Het default field (df) is, i.t.t. de suggest-service, niet gefixeerd.

In de free-service kunnen standaard alleen de objecten worden bevraagd waarover in de klankbordgroep van Locatieserver consensus over bestaat. Dit betreft momenteel alleen de gemeenten, woonplaatsen, wegen, postcodes, en adressen. Om ook de andere types op te vragen, zoals percelen of hectometerpalen, dient de parameter fq=*:* te worden toegevoegd aan de query string. Hetzelfde geldt voor de suggest-service.

Verplicht: q=<zoektermen> Hiermee worden de zoektermen opgegeven. De Solr-syntax voor zoektermen kan hier worden toegepast, bijv. combineren met "and", en het gebruik van dubbele quotes voor opeenvolgende zoektermen. Zoektermen mogen incompleet zijn. Ook wordt er gebruik gemaakt van synoniemen.

Voorbeelden: q=Utrecht: geeft resultaten terug met de zoekterm Utrecht, bijv. adressen in de stad Utrecht, woonplaatsen en gemeenten in de provincie Utrecht.

q="De Bilt": geeft resultaten terug met de zoekterm De Bilt, bijv. de woonplaats en gemeente De Bilt, of adressen in deze woonplaats.

q="Bolstraat" and Utrecht: geeft objecten (straten en adressen) terug die zowel de string "Bolstraat" als "Utrecht" bevatten. Dit zijn de straten Bolstraat en Ferdinand Bolstraat in Utrecht en alle bijbehorende adressen.

Optioneel: fl=<velden> Hiermee worden de velden opgegeven die teruggegeven dienen te worden. De default-waarde is "id identificatie weergavenaam bron type subtype openbareruimte_id nwb_id openbareruimtetype straatnaam straatnaam_verkort adresseerbaarobject_id nummeraanduiding_id huisnummer huisletter huisnummertoevoeging huis_nlt postcode buurtnaam buurtcode wijknaam wijkcode woonplaatscode woonplaatsnaam gemeentecode gemeentenaam provinciecode provincienaam provincieafkorting kadastraal_object_id kadastrale_gemeentecode kadastrale_gemeentenaam kadastrale_sectie perceelnummer kadastrale_grootte gekoppeld_perceel kadastrale_aanduiding volgnummer gekoppeld_appartement wegnummer hectometernummer zijde hectometerletter waterschapsnaam waterschapscode rdf_seealso centroide_ll centroide_rd boundingbox_ll boundingbox_rd score".

Let op dat alleen de velden worden teruggegeven die ook daadwerkelijk een waarde bevatten. Null-waarden worden niet teruggegeven. Merk op dat de velden geometrie_ll en geometrie_rd niet standaard worden teruggegeven. Dit komt omdat de geometrie in veel gevallen niet nodig zijn, laat staan dat deze in zowel latlon als RD nodig is. De geometrieën van gemeenten en woonplaatsen worden door zeer lange strings weergegeven, wat de response body veel groter maakt. De geometrievelden kunnen worden opgevraagd door de parameter fl=id,geometrie_ll/rd,... of fl=* mee te geven.

Wanneer je d.m.v. fl=* alle velden opvraagt, wordt de score standaard niet teruggegeven. Dit komt omdat dit een berekend veld is en niet als zodanig in de index zelf opgeslagen zit. Je kunt de score erbij opvragen door fl=*,score te specificeren.

Optioneel: df=<zoekveld> Hiermee wordt het default zoekveld opgegeven. Dit is het veld waar standaard in gezocht wordt, wanneer de veldnaam niet wordt meegegeven. De default-waarde is "tekst".

Optioneel: sort=<sortering> Hiermee kan worden opgegeven hoe de sortering plaatsvindt. De defaultwaarde is score desc, sortering asc, weergavenaam asc. Door voor deze string typesortering asc toe te voegen, kan de oude sortering worden gebruikt.

De betekenis van de velden is als volgt:

• score: de door Solr berekende score. Zie paragraaf 6.1 voor meer informatie.
• sortering: aanvullende sortering voor adressen o.b.v. huisnummers + huisletters, alsmede voor percelen o.b.v. secties en perceelnummers.
• weergavenaam: een leesbare naam die wordt gebruikt om het geo-referentieobject op een eenduidige manier mee te beschrijven.
• typesortering: een door PDOK toegekende "standaard" volgorde voor objecttypen. Bij de op de BAG gebaseerde gegevens gaat dit van groot naar klein (gemeente, woonplaats, weg, postcode, adres).

Optioneel: bq=<boost query> Met behulp van deze parameter kan aan bepaalde veldwaarden een extra boost worden meegegeven. Ook hiermee kan de scoreberekening worden aangepast. Dit gebeurt alleen o.b.v. de inhoud van het veld "type". De defaultwaarde is 'type:provincie^1.5 type:gemeente^1.5 type:woonplaats^1.5 type:weg^1.5 type:postcode^0.6 type:adres^1. De overige typen (nog niet aanwezig) hebben geen boost. Voor elke boost query moet een aparte bq=<boost> worden gebruikt. Bijvoorbeeld: bq=type:gemeente^1.5&bq=type:woonplaats^1.5.

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

{
  "response":{
    "numFound":165,
    "start":0,
    "maxScore":27.59121,
    "numFoundExact":true,
    "docs":[
      {
        "bron":"BAG",
        "woonplaatscode":"3295",
        "type":"adres",
        "woonplaatsnaam":"Utrecht",
        "huis_nlt":"1",
        "openbareruimtetype":"Weg",
        "gemeentecode":"0344",
        "weergavenaam":"Bolstraat 1, 3581WS Utrecht",
        "straatnaam_verkort":"Bolstr",
        "id":"adr-01e5f757daeb1616e02fdcd0e6193e4b",
        "gemeentenaam":"Utrecht",
        "identificatie":"0344010000158578-0344200000159102",
        "openbareruimte_id":"0344300000002883",
        "provinciecode":"PV26",
        "postcode":"3581WS",
        "provincienaam":"Utrecht",
        "centroide_ll":"POINT(5.13287587 52.08884161)",
        "nummeraanduiding_id":"0344200000159102",
        "adresseerbaarobject_id":"0344010000158578",
        "huisnummer":1,
        "provincieafkorting":"UT",
        "centroide_rd":"POINT(137569.474 455650.561)",
        "straatnaam":"Bolstraat",
        "gekoppeld_perceel":[
          "ASD40-C-7285",
          "ASD40-C-8930"
        ],
        "score":27.59121
      },
      ...
    ]
  }
}

Het docs-attribuut bevat de zoekresultaten. De teruggegeven velden zijn de standaard velden zoals hierboven genoemd. De velden met null-waarden worden weggelaten door Solr.

Let op: de volgorde van de velden is random. Bij het opnieuw indexeren van de data of wanneer het request door een andere server wordt beantwoord, kan de volgorde wijzigen.

Wanneer de opgegeven zoekterm geen resultaten oplevert, wordt het volgende JSON-bericht teruggestuurd met HTTP statuscode 200.

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

https://api.pdok.nl/bzk/locatieserver/search/v3_1/free?q=Bolstraat and Utrecht and type:adres

Resultaat:

{
   "response":{
      "numFound":165,
      "start":0,
      "maxScore":10.233262,
      "numFoundExact":true,
      "docs":[
         {
            "bron":"BAG",
            "woonplaatscode":"3295",
            "type":"adres",
            "woonplaatsnaam":"Utrecht",
            "wijkcode":"WK034405",
            "huis_nlt":"10A-BS",
            "openbareruimtetype":"Weg",
            "buurtnaam":"Oudwijk",
            "gemeentecode":"0344",
            "rdf_seealso":"http://bag.basisregistraties.overheid.nl/bag/id/nummeraanduiding/0344200000057673",
            "weergavenaam":"Bolstraat 10A-BS, 3581WX Utrecht",
            "huisnummertoevoeging":"BS",
            "straatnaam_verkort":"Bolstr",
            "id":"adr-1fe019897308ba8cc442f665b431a81d",
            "gekoppeld_perceel":[
               "ASD40-C-5923"
            ],
            "gemeentenaam":"Utrecht",
            "buurtcode":"BU03440512",
            "wijknaam":"Wijk 05 Oost",
            "identificatie":"0344010000051091-0344200000057673",
            "openbareruimte_id":"0344300000002883",
            "waterschapsnaam":"Hoogheemraadschap De Stichtse Rijnlanden",
            "provinciecode":"PV26",
            "huisletter":"A",
            "postcode":"3581WX",
            "provincienaam":"Utrecht",
            "centroide_ll":"POINT(5.13338475 52.08876986)",
            "nummeraanduiding_id":"0344200000057673",
            "waterschapscode":"14",
            "adresseerbaarobject_id":"0344010000051091",
            "huisnummer":10,
            "provincieafkorting":"UT",
            "centroide_rd":"POINT(137604.323 455642.456)",
            "straatnaam":"Bolstraat",
            "score":10.233262
         },
         ...
      ]
   }
}

Er zijn 165 zoekresultaten gevonden. Dit zijn allemaal adressen (vanwege het type-veld) in de Bolstraat of de Ferdinand Bolstraat in Utrecht. De wegen worden hier niet teruggegeven, omdat er is gezocht op type=adres.

https://api.pdok.nl/bzk/locatieserver/search/v3_1/free?q=Bolstraat Utrecht

Resultaat:

{
   "response":{
      "numFound":206820,
      "start":0,
      "maxScore":12.042421,
      "numFoundExact":true,
      "docs":[
         {
            "bron":"BAG/NWB",
            "woonplaatscode":"3295",
            "type":"weg",
            "woonplaatsnaam":"Utrecht",
            "nwb_id":"147175",
            "openbareruimtetype":"Weg",
            "gemeentecode":"0344",
            "rdf_seealso":"http://bag.basisregistraties.overheid.nl/bag/id/openbare-ruimte/0344300000002883",
            "weergavenaam":"Bolstraat, Utrecht",
            "straatnaam_verkort":"Bolstr",
            "id":"weg-05f9c50f40f4f764dc4761e8ae2c0064",
            "gemeentenaam":"Utrecht",
            "identificatie":"0344300000002883",
            "openbareruimte_id":"0344300000002883",
            "provinciecode":"PV26",
            "provincienaam":"Utrecht",
            "centroide_ll":"POINT(5.13439295 52.08817123)",
            "provincieafkorting":"UT",
            "centroide_rd":"POINT(137673.188 455575.612)",
            "straatnaam":"Bolstraat",
            "score":12.042421
         },
         ...
      ]
   }
}

Nu is het duidelijk wat er gebeurt als tussen de zoektermen geen "and" wordt opgegeven. Dan wordt de default logical operator "or" toegepast. Alle objecten die Bolstraat of Utrecht bevatten worden teruggegeven. Combinaties hebben uiteraard wel een hogere score, dus de straat Bolstraat in Utrecht zal de weg met de hoogste score zijn in het zoekresultaat, na de gemeente en woonplaatsen. Maar ook andere adressen in Utrecht, of de woonplaats Utrecht, of zelfs de adressen aan de Ferdinand Bolstraat in Amsterdam worden teruggegeven, omdat ze met de zoektermen matchen.

De scoreberekening van Solr is een wiskundige berekening, welke van meerdere factoren afhangt:

• De mate waarin de zoektermen overeenkomen met de zoekresultaten;
  • Hierbij wordt de voorkeur gegeven aan korte namen, omdat dan een groter deel overeenkomt;
  • Wanneer er meerdere zoektermen opgegeven zijn (gescheiden door spaties), wordt de score hoger naarmate er meer matches zijn. De woonplaats De Bilt zal dus hoger scoren dan Bilthoven of De Lier;
  • Tevens wordt er rekening gehouden met boosting parameters.
• Bij het meegeven van lat/lon wordt ook de afstand meegenomen.

De geometrie objecten in de response zijn geëncodeerd in het WKT formaat.