Endpoint

Bulk

Meerdere adressen in één verzoek. Bedoeld voor het opschonen van een bestaand adresbestand, niet voor verkeer uit een checkout.

Het verzoek

POST /v1/bulk/lookup

Maximaal 1.000 combinaties in één verzoek. Elke regel telt als één call.

Parameter Type Verplicht Omschrijving
addresses array ja Lijst van objecten met postcode en number.

De response

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

200 application/json
{
  "data": [
    {
      "postcode": "1021JT",
      "number": 19,
      "status": 200,
      "address": {
        "street": "Hamerstraat",
        "city": "Amsterdam",
        "municipality": "Amsterdam",
        "province": "Noord-Holland",
        "location": { "type": "Point", "coordinates": [4.92204151, 52.38488658] }
      }
    },
    {
      "postcode": "6545CA",
      "number": 299,
      "status": 404,
      "address": null
    }
  ]
}

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 '{
    "addresses": [
        {
            "postcode": "1021JT",
            "number": 19
        },
        {
            "postcode": "5038EA",
            "number": 17
        },
        {
            "postcode": "6545CA",
            "number": 299
        }
    ]
}' \
  "https://api.locatieapi.nl/v1/bulk/lookup"

Elke regel krijgt zijn eigen status

Een bulkverzoek geeft altijd 200, ook als er regels niet gevonden zijn. Kijk per regel naar het veld status. Zo hoef je niet je hele batch opnieuw te sturen als er één adres niet bestaat.

Limieten per plan

Maximaal aantal regels per bulkverzoek
Plan Regels per verzoek
Starter 25
Klein 100
Standaard 250
Plus 500
Pro 1.000
Enterprise 1.000

Het gratis plan heeft geen bulk. Stuur je meer regels dan je plan toestaat, dan krijg je een 400 met de reden erbij; er wordt dan niets verwerkt en er gaat niets van je bundel af.

Verbruik

Een bulkverzoek telt per regel, niet per verzoek. Honderd adressen in één aanroep kost dus honderd calls uit je bundel. Wat je bespaart is netwerktijd en de rate limit per seconde: één bulkverzoek telt als één aanroep voor X-RateLimit-Limit.

Ga je een groot bestand opschonen, spreid dat dan over meerdere verzoeken van een paar honderd regels en kijk tussendoor naar X-Quota-Remaining. Meer daarover op limieten en headers.