Migration Guide Zoeken V1 to V2
The Zoeken API has been upgraded. Below you can read what has changed compared to version V1.
Endpoint
The new endpoint is:
https://api.kvk.nl/api/v2/zoeken
Domestic and foreign addresses
Zoeken V2 distinguishes between domestic and foreign addresses.
You can recognize a foreign address by these attributes:
- straatHuisnummer (streetHousenumber)
- postcodeWoonplaats (zipcode city)
- land (country)
Domestic address - V1
"adresType": "string", "straatnaam": "string", "huisnummer": 0, "huisnummerToevoeging": "string", "postcode": "string", "plaats": "string",
Domestic address - V2
"adres": {
"binnenlandsAdres": {
"type": "bezoekadres/postadres",
"straatnaam": "string",
"huisnummer": 0,
"huisletter": "string",
"postbusnummer": 0,
"postcode": "string",
"plaats": "string",
}
}
Foreign address - V1
"adresType": "string",
"straatnaam": "string",
"plaats": "string",
Foreign address - V2
"adres": {
"buitenlandsAdres": {
"type": "bezoekadres/postadres",
"straatHuisnummer": "string",
"postcodeWoonplaats": "string",
"land": "string",
}
}
“_links” object
The result contains a “_links” object in V2. The property "self" therein contains the URL of the call made.
{
"pagina": 1,
"resultatenPerPagina": 10,
"totaal": 10,
"resultaten": [...],
"_links": {
"self": {
"href": "https://api.kvk.nl/test/api/v2/zoeken"
}
}
}
Differences output
| V1 (old) | V2 (new) | Description |
|---|---|---|
| aantal | resultatenPerPagina | The attribute 'aantal' (number of) has been clarified and adjusted to 'resultatenPerPagina' (results per page). |
| handelsnaam | naam | The attribute 'handelsnaam' (trade name) has been changed to 'naam' (name) to make it clear that not only the trade name is shown. The name can be a 'statutory name', 'trade name' or 'name' (non-commercial). |
| <seperate address data> | adres | Address data are no longer displayed separately, but in an object 'address' in which a ‘binnenlandsAdres’(domestic address) or 'buitenlandsAdres' (foreign address) is displayed. See above under domestic and foreign addresses. |
Differences input
| V1 (old) | V2 (new) | Description |
|---|---|---|
| aantal | resultatenPerPagina | The attribute 'aantal' (number of) has been clarified and adjusted to 'resultatenPerPagina' (results per page). |
| handelsnaam | naam | The attribute 'handelsnaam' (trade name) has been changed to 'naam' (name) to make it clear that not only the trade name is shown. The name can be a 'statutory name', 'trade name' or 'name' (non-commercial). |
| huisnummer | huisnummer | It is no longer possible to look up a PO box number using the 'huisnummer' (house number) parameter. Use the new parameter 'postbusnummer' (PO box number ) for this. |
| <n/a> | postbusnummer | It is no longer possible to look up a PO box number using the 'huisnummer' (house number) parameter. Use the new parameter 'postbusnummer' (PO box number ) for this. |
| huisnummerToevoeging | huisletter | The parameter 'huisnummerToevoeging' (house number addition) has been clarified and adjusted to 'huisletter' (house letter). |
| type | type | The 'type' parameter has remained the same, but the method of calling has changed. Previously you used a comma to separate, in V2 you use '&'. Example V1: type=nevenvestiging,hoofdvestiging,rechtspersoon |