Adres-autocomplete voor een checkout

Het verzoek

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.

De response

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

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

Voorbeelden

curl -sS \
  -H "X-Api-Key: lat_test_demo_publiek_locatieapi_sandbox" \
  -H "Accept: application/json" \
  "https://api.locatieapi.nl/v1/autocomplete?q=hamerstr&type=address&limit=8"

$curl = curl_init('https://api.locatieapi.nl/v1/autocomplete?q=hamerstr&type=address&limit=8');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 5,
    CURLOPT_HTTPHEADER => ['X-Api-Key: lat_test_demo_publiek_locatieapi_sandbox', '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(5)
    ->get('https://api.locatieapi.nl/v1/autocomplete?q=hamerstr&type=address&limit=8');

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

const response = await fetch('https://api.locatieapi.nl/v1/autocomplete?q=hamerstr&type=address&limit=8', {
  headers: {
    'X-Api-Key': 'lat_test_demo_publiek_locatieapi_sandbox',
    Accept: 'application/json',
  },
});

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

import requests

response = requests.get(
    "https://api.locatieapi.nl/v1/autocomplete?q=hamerstr&type=address&limit=8",
    headers={"X-Api-Key": "lat_test_demo_publiek_locatieapi_sandbox", "Accept": "application/json"},
    timeout=5,
)

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

Rechtstreeks vanuit de browser

Autocomplete is het endpoint waarbij een tussenlaag het meest in de weg zit: elke toetsaanslag zou dan twee keer over het netwerk moeten. Daarom kun je bij ons een sleutel met alleen leesrechten maken en daar de toegestane origins op zetten. De API stuurt dan de bijbehorende Access-Control-Allow-Origin mee en de aanroep werkt rechtstreeks vanuit je pagina.

Wel met een aparte sleutel

Zet nooit je gewone livesleutel in de browser. Maak een tweede sleutel, geef die alleen leesrechten, zet de toegestane origins erop en gebruik alleen die in frontend-code. Een sleutel zonder ingestelde origin werkt bewust alleen server-side.

autocomplete.js

/**
 * Autocomplete rechtstreeks vanuit de browser. Dat mag met LocatieAPI,
 * mits je de origin op de sleutel zet en een sleutel met alleen
 * leesrechten gebruikt.
 */
const KEY = 'lat_test_demo_publiek_locatieapi_sandbox';

async function suggest(term) {
  if (term.length < 2) return [];

  const url = new URL('https://api.locatieapi.nl/v1/autocomplete');
  url.searchParams.set('q', term);
  url.searchParams.set('type', 'address');
  url.searchParams.set('limit', '8');

  const response = await fetch(url, { headers: { 'X-Api-Key': KEY } });

  if (!response.ok) return [];

  const { data } = await response.json();

  return data.map((row) => row.label);
}

const input = document.querySelector('#adres');
let timer;

input.addEventListener('input', () => {
  clearTimeout(timer);
  timer = setTimeout(async () => {
    const options = await suggest(input.value);
    document.querySelector('#suggesties').replaceChildren(
      ...options.map((label) => Object.assign(document.createElement('option'), { value: label })),
    );
  }, 150);
});

Tips

•Wacht 150 milliseconden na de laatste toetsaanslag voordat je aanroept. Dat voorkomt een aanroep per toetsaanslag.
•Begin pas vanaf twee tekens. Bij minder is de lijst toch niet bruikbaar en kost het alleen bundel.
•Breek een lopend verzoek af met een AbortController zodra de gebruiker verder typt.
•Gebruik type=city voor een plaatsveld en type=street voor een straatveld; dat geeft veel kortere en relevantere lijsten.
•Laat het adresveld altijd bewerkbaar. Een suggestielijst mag nooit de enige manier zijn om een adres in te vullen.