Migratie
Overstappen vanaf een bestaande postcode-API
Onze v3-endpoints volgen het contract dat de meeste Nederlandse postcode-API's gebruiken. Je wijzigt de basis-URL en de sleutel.
# LocatieAPI, overstappen vanaf een bestaande postcode-API
Bron: https://locatieapi.nl/documentatie/overstappen-van-een-bestaande-api
## 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"
}
],
"meta": { "count": 1 }
}
```
### 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
{
"data": {
"postcode": "1021JT",
"street": "Hamerstraat",
"city": "Amsterdam",
"municipality": "Amsterdam",
"province": "Noord-Holland",
"location": { "type": "Point", "coordinates": [4.92204151, 52.38488658] },
"addressCount": 64,
"numberRange": { "min": 1, "max": 121 },
"isPoBox": false
}
}
```
### 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 | `all`, `address`, `street` of `city`. Standaard `all`. |
| `limit` | integer | nee | Aantal suggesties. Wordt afgekapt op het maximum van de API. |
Voorbeeldresponse:
```json
{
"data": [
{
"type": "address",
"label": "1021 JT 19, Hamerstraat, Amsterdam",
"value": "1021 JT 19",
"postcode": "1021JT",
"street": "Hamerstraat",
"city": "Amsterdam",
"id": "0363200012101386"
}
],
"meta": { "count": 1, "query": "hamerstr", "type": "all", "limit": 10 }
}
```
### POST /v1/bulk/lookup
Meerdere combinaties in één verzoek. Elke regel telt als één call.
| Parameter | Type | Verplicht | Omschrijving |
|---|---|---|---|
| `addresses` | array | ja | Lijst van objecten met `postcode` en `number`, eventueel `letter` en `addition`. |
Voorbeeldresponse:
```json
{
"data": [
{
"index": 0,
"postcode": "1021JT",
"number": 19,
"found": true,
"error": null,
"address": {
"id": "0363200012101386",
"postcode": "1021JT",
"number": 19,
"street": "Hamerstraat",
"city": "Amsterdam",
"municipality": "Amsterdam",
"province": "Noord-Holland",
"location": { "type": "Point", "coordinates": [4.92204151, 52.38488658] }
}
},
{
"index": 1,
"postcode": "6545CA",
"number": 299,
"found": false,
"error": "not_found",
"address": null
}
],
"meta": { "requested": 2, "found": 1, "billableCalls": 2 }
}
```
### 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` | integer | ja | Huisnummer als geheel getal. |
| `letter` | string | nee | Huisletter zoals ingevoerd. |
| `addition` | string | nee | Toevoeging zoals ingevoerd. |
| `street` | string | nee | Straatnaam zoals ingevoerd, voor de vergelijking. |
| `city` | string | nee | Plaats zoals ingevoerd, voor de vergelijking. |
Voorbeeldresponse:
```json
{
"data": {
"valid": false,
"reason": "field_mismatch",
"address": {
"id": "0363200012101386",
"postcode": "1021JT",
"number": 19,
"street": "Hamerstraat",
"city": "Amsterdam",
"municipality": "Amsterdam",
"province": "Noord-Holland",
"location": { "type": "Point", "coordinates": [4.92204151, 52.38488658] }
},
"corrections": { "city": "Amsterdam" },
"suggestion": {
"postcode": "1021JT",
"number": 19,
"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, tussen -90 en 90. |
| `lon` | number | ja | Lengtegraad in WGS84, tussen -180 en 180. |
| `radius` | integer | nee | Zoekstraal in meters. Wordt afgekapt op het maximum van de API. |
| `limit` | integer | nee | Aantal treffers. Standaard 10. |
Voorbeeldresponse:
```json
{
"data": [
{
"id": "0363200012101386",
"postcode": "1021JT",
"number": 19,
"street": "Hamerstraat",
"city": "Amsterdam",
"municipality": "Amsterdam",
"province": "Noord-Holland",
"location": { "type": "Point", "coordinates": [4.92204151, 52.38488658] },
"distance": 12
}
],
"meta": { "count": 1, "lat": 52.38488658, "lon": 4.92204151, "radius": 100, "unit": "meters" }
}
```
## Foutcodes
### v3, application/problem+json
| 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"}` |
### v1, application/json
Vorm: `{"error":{"code":"...","message":"..."}}`. Controleer op `error.code`, niet op de melding.
| Code | Status | Waar | Voorbeeldmelding |
|---|---|---|---|
| `invalid_postcode` | 400 | /v1/addresses, /v1/postcodes, /v1/bulk/lookup | Geef een geldige postcode op, bijvoorbeeld 6545CA. |
| `invalid_number` | 400 | /v1/addresses, /v1/validate, /v1/bulk/lookup | Het huisnummer moet een geheel getal zijn. |
| `invalid_query` | 400 | /v1/autocomplete | Geef minimaal twee tekens op in q. |
| `invalid_type` | 400 | /v1/autocomplete | type moet een van deze waarden zijn: all, address, street, city. |
| `invalid_coordinates` | 400 | /v1/reverse | Geef lat en lon op als decimale graden. |
| `invalid_payload` | 400 | /v1/bulk/lookup | Stuur een lijst addresses met paren van postcode en number. |
| `invalid_api_key` | 401 | alle endpoints | Invalid API key |
| `plan_upgrade_required` | 403 | /v1/bulk/lookup en andere endpoints buiten je plan | Bulk zit niet in dit plan. |
| `not_found` | 404 | /v1/postcodes, onbekende paden, en per regel in /v1/bulk/lookup | Deze postcode is niet bekend. |
| `too_many_items` | 422 | /v1/bulk/lookup | Een bulkverzoek bevat maximaal 250 regels, dit verzoek heeft er 400. |
| `rate_limit_exceeded` | 429 | alle endpoints | Je gaat over je calls per seconde. |
| `quota_exceeded` | 429 | alle endpoints | Je maandbundel is op. |
## 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`.
- **v1 zit in een envelope** De v1-endpoints geven `{"data": ...}` terug, met daarnaast een `meta`-object. v3 geeft het adres kaal terug, zonder envelope.
- **Twee foutvormen** v3 geeft `application/problem+json` met een veld `title`. v1 geeft gewone JSON met `{"error":{"code","message"}}`; controleer daar op `error.code`, niet op de melding.
## 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 | Bij LocatieAPI |
|---|---|
| Basis-URL | https://api.locatieapi.nl/v3 |
| Header | X-Api-Key |
| Sleutel | lat_live_… |
| Pad | /lookup/{postcode}/{number} |
| Response | postcode, number, street, city, municipality, province, location |
De wijziging in code
- curl -H "X-Api-Key: $KEY" \
- https://api.jouw-huidige-api.nl/v3/lookup/1021JT/19
+ curl -H "X-Api-Key: $KEY" \
+ https://api.locatieapi.nl/v3/lookup/1021JT/19Wat 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. Een toevoeging in het pad geeft400, geen404. - ✓Foutresponses met
Content-Type: application/problem+jsonen het veldtitle. - ✓De Engelse foutteksten:
Request validation failed,Invalid API key,Resource not found. - ✓De sandboxgevallen, inclusief
6545CA/29dat ook bij onsWaldeck Pyrmontsingelgeeft in plaats van de naam uit de registratie.
Wat erbij komt
- •Vier extra headers:
X-Quota-Limit,X-Quota-Remaining,X-Quota-ResetenX-Request-Id. Code die die headers niet leest merkt er niets van. - •Een
429met een problem+json-body. Vang die af met een korte terugval. - •Zes endpoints onder
/v1: adressen met toevoegingen, postcodes, autocomplete, bulk, validatie en reverse geocoding. Die zitten in elk betaald plan. - •Aanroepen vanuit de browser, 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. - 3Zet de basis-URL in je configuratie om en zet je livesleutel in de omgevingsvariabelen. Rol dat eerst uit naar acceptatie.
- 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. Migratiehulp is ook zonder betaald
abonnement beschikbaar.