Adresvalidatie met correctievoorstel

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`	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.

De response

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

200 application/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"
    }
  }
}

Velden in de response

Veld	Type	Omschrijving
`valid`	boolean	Of het adres bestaat en overeenkomt met wat je meestuurde.
`reason`	string\|null	Waarom het niet klopt. `null` als het klopt.
`address`	object\|null	Het gevonden adres, of `null` als er niets gevonden is.
`corrections`	object	Per afwijkend veld de juiste waarde, bijvoorbeeld `{"city": "Amsterdam"}`. Leeg als er niets af te wijken valt.
`suggestion`	object\|null	Het adres dat je waarschijnlijk bedoelde. `null` als er geen voorstel is.

Mogelijke waarden van reason

reason	Type	Omschrijving
`null`	null	Het adres bestaat en komt overeen met wat je meestuurde. `valid` is dan `true`.
`invalid_postcode`	string	De postcode voldoet niet aan het patroon. Er is geen correctievoorstel.
`field_mismatch`	string	Het adres bestaat, maar een meegestuurde straatnaam of plaats wijkt af. `corrections` bevat per veld de juiste waarde.
`number_not_found`	string	De postcode bestaat, dit huisnummer niet. Het voorstel bevat een bestaand nummer in dezelfde straat.
`postcode_not_found`	string	De postcode zelf bestaat niet, maar lijkt op een bestaande. Het voorstel bevat het adres bij die postcode.
`not_found`	string	Geen adres en geen bruikbaar voorstel gevonden.

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 registratie 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 werkt ook voor het opschonen van een bestaande klantendatabase. Combineer hem dan met bulk om een heel bestand in één ronde te controleren.