API-referentie

# LocatieAPI, API-referentie Bron: https://locatieapi.nl/api-reference ## Basis - Live: `https://api.locatieapi.nl` - Sandbox: `https://sandbox.locatieapi.nl`, gratis, vaste testset, telt niet mee voor de bundel - Altijd werkende terugval op hetzelfde pad: `https://locatieapi.nl/api` - Authenticatie: stuur de header `X-Api-Key: lat_test_demo_publiek_locatieapi_sandbox`. Er is geen andere methode, geen OAuth en geen sleutel in de querystring. - Alle responses zijn JSON. Foutresponses van v3 hebben `Content-Type: application/problem+json`. ## Endpoints ### GET /v3/lookup/{postcode}/{number} Eén adres op postcode en huisnummer. Response-compatibel met een bestaande postcode-API, zodat alleen de basis-URL wijzigt. | Parameter | Type | Verplicht | Omschrijving | |---|---|---|---| | `postcode` | string | ja | P6 zonder spatie, hoofdletters of kleine letters. Patroon `^[0-9]{4}[a-zA-Z]{2}$`. | | `number` | integer | ja | Huisnummer als geheel getal. Een toevoeging in het pad geeft `400`, geen `404`. | Voorbeeldresponse: ```json { "postcode": "1021JT", "number": 19, "street": "Hamerstraat", "city": "Amsterdam", "municipality": "Amsterdam", "province": "Noord-Holland", "location": { "type": "Point", "coordinates": [4.92204151, 52.38488658] } } ``` ### GET /v1/addresses Alle treffers op een postcode en huisnummer, inclusief letters en toevoegingen. | Parameter | Type | Verplicht | Omschrijving | |---|---|---|---| | `postcode` | string | ja | P6 zonder spatie. | | `number` | integer | nee | Huisnummer. Zonder nummer krijg je de hele postcode terug. | | `letter` | string | nee | Huisletter, één teken. | | `addition` | string | nee | Huisnummertoevoeging. | Voorbeeldresponse: ```json { "data": [ { "id": "0363200012101386", "postcode": "1021JT", "number": 19, "letter": null, "addition": null, "street": "Hamerstraat", "city": "Amsterdam", "municipality": "Amsterdam", "province": "Noord-Holland", "location": { "type": "Point", "coordinates": [4.92204151, 52.38488658] }, "purposes": ["woonfunctie"], "surface": 98, "constructionYear": 1930, "type": "verblijfsobject" } ] } ``` ### GET /v1/postcodes/{postcode} Samenvatting per P6: straat, plaats, gemeente, provincie, zwaartepunt en aantal adressen. | Parameter | Type | Verplicht | Omschrijving | |---|---|---|---| | `postcode` | string | ja | P6 zonder spatie. | Voorbeeldresponse: ```json { "postcode": "1021JT", "street": "Hamerstraat", "city": "Amsterdam", "municipality": "Amsterdam", "province": "Noord-Holland", "location": { "type": "Point", "coordinates": [4.92204151, 52.38488658] }, "addressCount": 64, "numberMin": 1, "numberMax": 121 } ``` ### GET /v1/autocomplete Type-ahead op adres, straat of plaats. Bedoeld voor een checkout of zoekveld. | Parameter | Type | Verplicht | Omschrijving | |---|---|---|---| | `q` | string | ja | Zoekterm, minimaal twee tekens. | | `type` | string | nee | `address`, `street` of `city`. Standaard `address`. | | `limit` | integer | nee | Aantal suggesties, 1 tot 25. Standaard 10. | Voorbeeldresponse: ```json { "data": [ { "label": "Hamerstraat 19, 1021 JT Amsterdam", "type": "address", "postcode": "1021JT", "number": 19, "street": "Hamerstraat", "city": "Amsterdam" } ] } ``` ### POST /v1/bulk/lookup Maximaal 1.000 combinaties in één verzoek. Elke regel telt als één call. | Parameter | Type | Verplicht | Omschrijving | |---|---|---|---| | `addresses` | array | ja | Lijst van objecten met `postcode` en `number`. | Voorbeeldresponse: ```json { "data": [ { "postcode": "1021JT", "number": 19, "status": 200, "address": { "street": "Hamerstraat", "city": "Amsterdam", "municipality": "Amsterdam", "province": "Noord-Holland", "location": { "type": "Point", "coordinates": [4.92204151, 52.38488658] } } }, { "postcode": "6545CA", "number": 299, "status": 404, "address": null } ] } ``` ### POST /v1/validate Controleert een ingevoerd adres en geeft een correctievoorstel terug. | Parameter | Type | Verplicht | Omschrijving | |---|---|---|---| | `postcode` | string | ja | Postcode zoals ingevoerd, met of zonder spatie. | | `number` | string | ja | Huisnummer zoals ingevoerd, toevoeging mag erin staan. | | `street` | string | nee | Straatnaam zoals ingevoerd, voor de vergelijking. | | `city` | string | nee | Plaats zoals ingevoerd, voor de vergelijking. | Voorbeeldresponse: ```json { "valid": false, "reason": "street_mismatch", "suggestion": { "postcode": "1021JT", "number": 19, "letter": null, "addition": null, "street": "Hamerstraat", "city": "Amsterdam" } } ``` ### GET /v1/reverse De dichtstbijzijnde adressen bij een coördinaat, met afstand in meters. | Parameter | Type | Verplicht | Omschrijving | |---|---|---|---| | `lat` | number | ja | Breedtegraad in WGS84. | | `lon` | number | ja | Lengtegraad in WGS84. | | `radius` | integer | nee | Zoekstraal in meters, 1 tot 1.000. Standaard 100. | Voorbeeldresponse: ```json { "data": [ { "distance": 12, "postcode": "1021JT", "number": 19, "street": "Hamerstraat", "city": "Amsterdam", "location": { "type": "Point", "coordinates": [4.92204151, 52.38488658] } } ] } ``` ## Foutcodes | Status | Titel | Wanneer | Body | |---|---|---|---| | 400 | Request validation failed | De postcode voldoet niet aan het patroon, of het huisnummer is geen geheel getal. | `{"title":"Request validation failed","invalidParams":[{"name":"number","reason":"should be integer"}]}` | | 401 | Invalid API key | De header X-Api-Key ontbreekt, is onbekend of is ingetrokken. | `{"title":"Invalid API key"}` | | 404 | Resource not found | De combinatie bestaat niet. | `{"title":"Resource not found"}` | | 429 | Rate limit exceeded | Je zit boven je calls per seconde of boven je maandbundel. | `{"title":"Rate limit exceeded"}` | ## Responseheaders op elke call - `X-RateLimit-Limit`: Het aantal calls per seconde dat bij je plan hoort. - `X-RateLimit-Remaining`: Wat er in het huidige venster van dat aantal over is. - `X-RateLimit-Reset`: Aantal seconden tot het venster opnieuw begint. - `X-Quota-Limit`: De maandbundel van je plan in aantal calls. - `X-Quota-Remaining`: Wat er van die bundel over is in de lopende factuurperiode. - `X-Quota-Reset`: Unix-tijdstip waarop de volgende factuurperiode begint. - `X-Request-Id`: Uniek nummer per verzoek. Noem dit bij een supportvraag. - `Cache-Control`: Bij een 200: `public, max-age=86400`. Adressen veranderen zelden. ## Valkuilen - **Postcode zonder spatie** De API accepteert `1021JT`, niet `1021 JT`. Haal de spatie er in je eigen code uit voordat je de URL bouwt. - **Huisnummer als geheel getal** In `/v3/lookup` hoort alleen het cijferdeel. `29a` geeft een `400` en geen `404`. - **Toevoegingen horen bij /v1/addresses** Wil je huisletters en toevoegingen, gebruik dan `/v1/addresses` met `letter` en `addition`. - **location is [longitude, latitude]** GeoJSON zet de lengtegraad eerst. Dat is de omgekeerde volgorde van wat de meeste kaartbibliotheken als "lat, lng" tonen. - **location kan null zijn** Bij een postbus is er geen coördinaat en is `street` letterlijk `Postbus`. - **Fouten zijn problem+json** Foutresponses van v3 hebben `Content-Type: application/problem+json` en een veld `title`, geen `message`. ## Sandbox De sandbox draait op `https://sandbox.locatieapi.nl` en kent precies deze gevallen: | Postcode | Huisnummer | Status | Resultaat | |---|---|---|---| | 6545CA | 29 | 200 | Waldeck Pyrmontsingel, Nijmegen, Gelderland | | 1021JT | 19 | 200 | Hamerstraat, Amsterdam, Noord-Holland | | 5038EA | 17 | 200 | Stationsstraat, Tilburg, Noord-Brabant | | 3030AC | 100 | 200 | Postbus, Leusden, Utrecht. location is null | | 6545CA | 29a | 400 | number should be integer | | 6545C | 29 | 400 | postcode voldoet niet aan het patroon | | 6545CA | 299 | 404 | Resource not found |