Migratie
Overstappen van postcodeapi.nu
De v3-endpoints zijn response-compatibel. In de praktijk wijzig je de basis-URL en je sleutel, en verder niets.
# LocatieAPI, overstappen van postcodeapi.nu
Bron: https://locatieapi.nl/documentatie/overstappen-van-postcodeapi-nu
## 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 postcodeapi.nu.
| 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/addresses/{bagId}
Eén adres op het BAG-nummeraanduidingsnummer.
| Parameter | Type | Verplicht | Omschrijving |
|---|---|---|---|
| `bagId` | string | ja | BAG-nummeraanduiding, zestien cijfers. |
### 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 in de BAG. | `{"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 |
Wat er wijzigt
| Onderdeel | postcodeapi.nu | LocatieAPI |
|---|---|---|
| Basis-URL | https://api.postcodeapi.nu/v3 | https://api.locatieapi.nl/v3 |
| Header | X-Api-Key | X-Api-Key |
| Sleutel | hun sleutel | lat_live_… |
| Pad | /lookup/{postcode}/{number} | /lookup/{postcode}/{number} |
| Response | JSON met postcode, number, street, city, municipality, province, location | identiek, veld voor veld |
De wijziging in code
Dit is de hele migratie. Eén regel, in de taal die je toevallig gebruikt.
- curl -H "X-Api-Key: $KEY" \
- https://api.postcodeapi.nu/v3/lookup/1021JT/19
+ curl -H "X-Api-Key: $KEY" \
+ https://api.locatieapi.nl/v3/lookup/1021JT/19Wat exact gelijk blijft
- ✓De veldnamen en de volgorde in de JSON.
- ✓
locationals GeoJSON-punt met[longitude, latitude], in die volgorde. - ✓
location: nullbij een postbus, metstreet: "Postbus". - ✓
numberals integer, en een toevoeging in het pad die een400geeft in plaats van een404. - ✓Foutresponses met
Content-Type: application/problem+jsonen het veldtitle. - ✓De Engelse foutteksten, letterlijk:
Request validation failed,Invalid API key,Resource not found. - ✓De sandboxgevallen, inclusief
6545CA/29dat ook bij onsWaldeck Pyrmontsingelgeeft. Je bestaande tests blijven dus slagen.
Wat er anders is
- •Er komen headers bij:
X-Quota-Limit,X-Quota-Remaining,X-Quota-ResetenX-Request-Id. Bestaande code die die headers niet leest merkt daar niets van. - •Er is een
429met een problem+json-body. Die kende de v3 van de concurrent niet als zodanig; vang hem af met een korte terugval. - •Er zijn zeven extra endpoints onder
/v1: adressen met toevoegingen, postcodes, autocomplete, bulk, validatie en reverse geocoding. Je hoeft er niets mee, maar ze zitten in elk betaald plan. - •Je kunt de API rechtstreeks vanuit de browser aanroepen als je de toegestane origins op de sleutel zet.
Stappenplan
- 1Maak een gratis account en pak je sandboxsleutel.
- 2Draai je bestaande testsuite tegen
https://sandbox.locatieapi.nl/v3. Als je tests op de sandbox van de concurrent groen waren, zijn ze dat hier ook. - 3Zet de basis-URL in je configuratie om en zet je livesleutel in de omgevingsvariabelen. Rol dat eerst uit naar je acceptatieomgeving.
- 4Draai een week met beide abonnementen naast elkaar en vergelijk je verbruik. Zeg daarna je oude abonnement op.
Loop je ergens tegenaan?
Mail naar support@locatieapi.nl met jeX-Request-Id. We denken graag mee bij een migratie,
ook als je nog geen betaald abonnement hebt.