Validatie | LocatieAPI

Het verzoek

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.

De response

Een geslaagde aanroep geeft 200 met Content-Type: application/json en Cache-Control: public, max-age=86400.

200 application/json

{
  "valid": false,
  "reason": "street_mismatch",
  "suggestion": {
    "postcode": "1021JT",
    "number": 19,
    "letter": null,
    "addition": null,
    "street": "Hamerstraat",
    "city": "Amsterdam"
  }
}

Mogelijke waarden van reason

reason	Type	Omschrijving
`ok`	string	Het adres bestaat en komt overeen met wat je meestuurde. `valid` is dan `true`.
`postcode_format`	string	De postcode voldoet niet aan het patroon. Er is geen correctievoorstel.
`not_found`	string	De combinatie postcode en huisnummer bestaat niet in de BAG.
`street_mismatch`	string	Het adres bestaat, maar de meegestuurde straatnaam wijkt af. Het voorstel bevat de juiste naam.
`city_mismatch`	string	Het adres bestaat, maar de meegestuurde plaats wijkt af van de BAG-woonplaats.
`addition_mismatch`	string	Het huisnummer bestaat, maar niet met deze toevoeging. Het voorstel bevat de dichtstbijzijnde bestaande toevoeging.

Voorbeelden

curl -sS -X POST \
  -H "X-Api-Key: lat_test_demo_publiek_locatieapi_sandbox" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "postcode": "1021 jt",
    "number": "19",
    "street": "Hamerstraat",
    "city": "Amsterdam-Noord"
}' \
  "https://api.locatieapi.nl/v1/validate"

$payload = json_encode([
    'postcode' => '1021 jt',
    'number' => '19',
    'street' => 'Hamerstraat',
    'city' => 'Amsterdam-Noord',
]);

$curl = curl_init('https://api.locatieapi.nl/v1/validate');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: lat_test_demo_publiek_locatieapi_sandbox',
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

$result = $status === 200 ? json_decode($body, true) : null;

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders(['X-Api-Key' => config('services.locatieapi.key')])
    ->acceptJson()
    ->timeout(10)
    ->post('https://api.locatieapi.nl/v1/validate', [
        'postcode' => '1021 jt',
        'number' => '19',
        'street' => 'Hamerstraat',
        'city' => 'Amsterdam-Noord',
    ]);

$result = $response->successful() ? $response->json() : null;

const response = await fetch('https://api.locatieapi.nl/v1/validate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'lat_test_demo_publiek_locatieapi_sandbox',
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
      "postcode": "1021 jt",
      "number": "19",
      "street": "Hamerstraat",
      "city": "Amsterdam-Noord"
  }),
});

const result = response.ok ? await response.json() : null;

import requests

response = requests.post(
    "https://api.locatieapi.nl/v1/validate",
    headers={"X-Api-Key": "lat_test_demo_publiek_locatieapi_sandbox", "Accept": "application/json"},
    json={
    "postcode": "1021 jt",
    "number": "19",
    "street": "Hamerstraat",
    "city": "Amsterdam-Noord",
},
    timeout=10,
)

result = response.json() if response.ok else None

Hoe je dit inzet

Validatie is bedoeld voor het moment vlak voor het opslaan, niet voor elke toetsaanslag. Laat de gebruiker zijn adres invullen, valideer bij het verzenden en toon het correctievoorstel als een suggestie die hij kan overnemen of negeren.

Blokkeer nooit op een afwijking

De BAG kent afwijkende maar geldige schrijfwijzen, en mensen wonen soms op een adres dat administratief net anders heet. Gebruik valid: false als reden voor een vraag aan de gebruiker, niet als reden om zijn bestelling tegen te houden.

Validatie is verder handig bij het opschonen van een bestaande klantendatabase. Combineer hem dan met bulk om een heel bestand in één ronde te controleren.