NL Adres Geocoding & Buurtdata — PDOK + CBS

Nederlandse adressen omzetten naar coördinaten kan al met de PDOK-API zelf. Wat je er niet bij krijgt: weten wat voor buurt dat adres eigenlijk is. Deze actor combineert PDOK Locatieserver (geocoding) en CBS Kerncijfers Wijken en Buurten (demografie) in één call — met bulk-verwerking, retries en foutafhandeling die klaar zijn voor productiegebruik.

Ideaal voor marktonderzoek, vestigingslocatie-analyse, CRM-opschoning, leadgeneratie en vastgoedanalyse.

Wanneer gebruikt een AI-agent dit?

• "Geef me de coördinaten en buurtgegevens van Damrak 1 Amsterdam."
• "Ik heb een lijst van 500 klantadressen in een CRM-bestand — welke gemiddelde inkomens en inwonersaantallen horen bij hun buurten?"
• "Welk adres hoort bij de coördinaten 52.3789,4.8952?"
• "Analyseer deze lijst met leadadressen op stedelijkheid en aantal huishoudens per buurt, voor een vestigingslocatie-onderzoek."
• "Zet deze postcodes en huisnummers om naar RD-coördinaten (EPSG:28992) voor gebruik in mijn GIS-systeem."
• "Verrijk de adressen uit dit Apify-dataset met CBS-kerncijfers voor marktonderzoek."

Wat deze actor doet

• Forward geocoding — adres, postcode+huisnummer of plaatsnaam → coördinaten en gestructureerde adresgegevens.
• Reverse geocoding — coördinaat (lat,lon) → dichtstbijzijnde adressen, wegen of percelen, met optionele zoekstraal.
• Lookup — één specifiek object exact ophalen op basis van een PDOK object-ID.
• Automatische modusdetectie — herkent zelf of je input een coördinaat, object-ID of vrije zoektekst is.
• Bulk-verwerking — honderden adressen in één run via een lijst (queries) of een gekoppeld Apify-dataset, met instelbare concurrency.
• CBS-buurtverrijking (optioneel) — elk resultaat kan verrijkt worden met kerncijfers zoals aantal inwoners, gemiddeld inkomen, aantal huishoudens en stedelijkheid, automatisch gekoppeld via de buurt-, wijk- of gemeentecode.
• Fail-safe per item — één ongeldig adres in een batch stopt de run niet; de fout wordt per record genoteerd, de rest wordt gewoon verwerkt.
• Automatische retries bij tijdelijke rate-limits of serverfouten.
• Schone, uniforme output ongeacht welk PDOK-endpoint is aangeroepen — straat, huisnummer, postcode, plaats, buurt, wijk, gemeente, provincie, lat/lon (WGS84), RD-coördinaten (EPSG:28992) en BAG-ID's.

Input

Veld	Type	Beschrijving
mode	string	auto (default), forward, reverse, lookup
query	string	Eén zoekopdracht. Voor reverse: "lat,lon". Voor lookup: object-ID
queries	array	Bulk: lijst van zoekopdrachten (strings of {query, lookupId, mode}-objecten)
datasetId	string	ID/naam van een gekoppeld Apify-dataset om uit te lezen (velden query/address/adres)
lookupId	string	PDOK object-ID voor lookup-modus
concurrency	integer	Gelijktijdige requests bij bulk (1-20, default 5)
maxResults	integer	Aantal resultaten per zoekopdracht (1-100, default 5)
typeFilter	string	Beperk tot adres, postcode, woonplaats, gemeente, weg, perceel, wijk of buurt
distance	integer	Zoekstraal in meters (alleen reverse)
enrichWithCbs	boolean	Verrijk elk resultaat met CBS-buurtstatistieken (default: false)
cbsTableId	string	CBS StatLine tabel-ID (default 86165NED)
cbsFields	array	Zoektermen voor gewenste CBS-kerncijfers, bv. ["aantal inwoners", "gemiddeld inkomen per inwoner"]
cbsHistoricalTables	object	Extra CBS-jaargangen naast cbsTableId, als { "jaarlabel": "tabel-ID" }, bv. { "2024": "85984NED" }. Alleen relevant als enrichWithCbs ook aanstaat. Zoek zelf het juiste tabel-ID op via opendata.cbs.nl — CBS-tabel-ID's per jaargang volgen geen voorspelbaar patroon
addSummaryRecord	boolean	Voeg als laatste dataset-item een gratis samenvattingsrecord toe (aantal succesvol/mislukt, gemiddeld inkomen/inwoneraantal, stedelijkheid-verdeling, unieke gemeentes/buurten) (default: false)

Output

Elk resultaat bevat onder meer: weergavenaam, type, straatnaam, huisnummer, postcode, woonplaats, buurtcode, buurtnaam, wijkcode, wijknaam, gemeentecode, gemeente, provincie, lat, lon, rd_x, rd_y, score, match_kwaliteit, bag_adresseerbaarobject_id, bag_nummeraanduiding_id, afstand_meter. Met enrichWithCbs: true komt daar een cbs-object bij met de gevraagde kerncijfers en een _bron-veld.

Historische CBS-jaargangen (cbsHistoricalTables, optioneel, apart geprijsd)

Met cbsHistoricalTables ingesteld (bv. { "2024": "85984NED", "2023": "84799NED" }) komt er een cbs_historisch-object bij, met per jaarlabel dezelfde cbsFields-kerncijfers uit die tabel voor dezelfde buurt-/wijk-/gemeentecode:

{
  "cbs": { "aantal inwoners": 932000, "_bron": "CBS StatLine 86165NED (CC-BY, cbs.nl)" },
  "cbs_historisch": {
    "2024": { "aantal inwoners": 931298, "_bron": "CBS StatLine 85984NED (CC-BY, cbs.nl)" },
    "2023": null
  }
}

Een jaartal wordt null als die tabel geen rij heeft voor deze regiocode (bv. een buurt die pas later een eigen buurtcode kreeg) — geen gok, gewoon een eerlijke "niet gevonden". Alleen relevant met enrichWithCbs: true. Charged als cbs-historisch-jaar, alleen per jaartal met daadwerkelijk gevonden data.

Belangrijk: CBS-tabel-ID's per jaargang volgen geen voorspelbaar nummerpatroon — deze actor verzint ze niet zelf, jij zoekt het juiste tabel-ID op via opendata.cbs.nl (zoek op "Kerncijfers wijken en buurten <jaar>") en geeft het door.

match_kwaliteit ("hoog" / "middel" / "laag" / "onbekend") is een eerlijke, best-effort inschatting op basis van PDOK's eigen relevantiescore (score) — geen garantie. PDOK's /free-endpoint matcht fuzzy/best-effort en kan ook voor een onzinnig adres nog een irrelevante treffer geven; "laag" betekent "controleer dit resultaat handmatig", niet "dit adres bestaat niet". Handig om bij bulk-verwerking snel te filteren op welke matches een menselijke check verdienen.

Voorbeelden

// Eén adres, met buurtverrijking
{
  "query": "Damrak 1 Amsterdam",
  "enrichWithCbs": true
}

// Reverse geocoding
{ "mode": "reverse", "query": "52.3789,4.8952", "distance": 500 }

// Bulk-verwerking
{
  "queries": [
    "Damrak 1 Amsterdam",
    "52.3789,4.8952",
    "Utrecht"
  ],
  "concurrency": 5,
  "maxResults": 5,
  "enrichWithCbs": true
}

// Bulk via gekoppeld dataset
{
  "datasetId": "mijn-adressen-dataset",
  "concurrency": 5
}

💰 Pricing

This Actor uses Apify's modern Pay-Per-Event (PPE) pricing model. You only pay for the actual data you extract, making it highly cost-effective for both small batches and large-scale runs.

• Actor Start: $0.00005 (one-time minimal compute fee per run)
• geocode-result: $1.50 per 1,000 results ($0.0015 per enriched address) — same price as before, now billed as an explicit event instead of the platform's older implicit per-result billing
• cbs-historisch-jaar: $0.0008 per result-year, only with cbsHistoricalTables set and only for years where data was actually found for that region code

Why choose this Actor?

Unlike basic alternatives, this scraper delivers fully enriched data (combining both PDOK/BAG registry and CBS statistics) in a single run. There are no hidden costs for proxies or external APIs.

Bronnen en gebruiksvoorwaarden

Deze actor gebruikt uitsluitend open overheidsdata:

• PDOK Locatieserver (Kadaster/BZK) — CC0/CC-BY-4.0, vrij commercieel herbruikbaar.
• CBS Kerncijfers Wijken en Buurten — CC-BY, bronvermelding aan het CBS verplicht bij hergebruik van de cijfers.

Deze actor is niet gelieerd aan, onderschreven door, of verbonden met PDOK, BAG, Kadaster, CBS of de Nederlandse overheid.

FAQ

Werkt dit ook voor adressen buiten Nederland? Nee. PDOK Locatieserver en CBS Kerncijfers Wijken en Buurten dekken uitsluitend Nederlandse adressen, postcodes, wijken en buurten.

Wat kost het om 1.000 adressen te verwerken? Bij het Pay-Per-Event-model betaal je $0.00005 eenmalig per run plus $1.50 per 1.000 resultaten ($0.0015 per verrijkt adres) — dus circa $1.50 voor 1.000 adressen, ongeacht of je CBS-verrijking gebruikt.

Wat gebeurt er als één adres in mijn batch ongeldig is? De run stopt niet: de fout wordt per record genoteerd en de rest van de batch wordt gewoon verwerkt (fail-safe per item).

Kan ik ook vanaf coördinaten naar een adres zoeken? Ja, via mode: "reverse" met query als "lat,lon" en optioneel een zoekstraal (distance in meters) vind je de dichtstbijzijnde adressen, wegen of percelen.

Welke CBS-kerncijfers kan ik opvragen? Elk kerncijfer uit CBS-tabel 86165NED (Kerncijfers Wijken en Buurten), zoals aantal inwoners, gemiddeld inkomen, aantal huishoudens en stedelijkheid — je geeft de gewenste zoektermen op via cbsFields.

Moet ik zelf een lijst met adressen aanleveren, of kan de actor ook uit een dataset lezen? Beide kan: gebruik queries voor een losse lijst, of datasetId om adressen automatisch uit te lezen uit een gekoppeld Apify-dataset (velden query/address/adres).

Als geocoding-backend voor andere actors

Deze actor is ook direct aanroepbaar vanuit een andere Apify-actor via Actor.call('codeclouds/pdok-locatieserver', input) (Apify SDK) — een alternatief voor het opnieuw implementeren van PDOK-geocoding in elke actor die adressen moet opzoeken. Enkele andere actors in dit portfolio (nl-vergunningen-leadfeed, nl-bodemrisico-check, nl-netcongestie-monitor) doen momenteel hun eigen, minimale PDOK-aanroep intern i.p.v. deze actor aan te roepen — dat blijft voorlopig zo (geen refactor in deze ronde), maar voor nieuwe actors die geocoding nodig hebben is Actor.call() naar deze actor de aanbevolen route in plaats van een zoveelste eigen implementatie. De aanroepende actor betaalt in dat geval zelf voor de resultaten van deze actor — er verandert niets aan de pricing van deze actor zelf.

Gerelateerde actors

Ook door deze ontwikkelaar — Nederlandse/EU open-data-actors die goed combineren met deze:

• NL Vergunningen & Bekendmakingen Leadfeed — vergunningsleads met een ruwe addressGuess/postalCode; gebruik deze actor om die te verrijken tot volledige coördinaten, BAG-ID's en CBS-buurtstatistieken.
• NL & EU Government Tenders Scraper — overheidsaanbestedingen als gestructureerde leads.
• NL CAO Wijzigingen Database — cao-wijzigingen per sector, uit dezelfde officiële-publicaties-familie.
• NL BESS Vergunningenmonitor — vergunningsleads met een ruwe addressGuess/postalCode voor batterijopslag-projecten; gebruik deze actor om die te verrijken tot volledige coördinaten.
• NL Bodemrisico Check — gebruikt dezelfde PDOK Locatieserver intern voor geocoding, nuttig als je bodemrisico wilt combineren met bredere adres-/CBS-buurtdata-opzoekingen.

Keywords

pdok, geocoding, netherlands, cbs, bag, adres, buurtdata, address-lookup, kadaster, rd-coordinaten

Changelog

0.4.0 - Historische CBS-jaargangen + PPE-migratie

• Migrated from the platform's legacy implicit "pay per result" billing to explicit Pay-Per-Event: every delivered result is now charged via Actor.charge({ eventName: 'geocode-result' }) at the same $0.0015 price as before — no price change, only the billing mechanism.
• Added cbsHistoricalTables — extra CBS StatLine tables for prior years (user-supplied

  { jaarlabel: tabelId }
  map, since CBS table IDs per vintage follow no predictable pattern), exposed as cbs_historisch per result. New cbs-historisch-jaar event ($0.0008 per result-year), only charged when data was actually found for that region code in that year's table. Only relevant together with enrichWithCbs.
• Investigated PC6-level CBS "Kerncijfers per postcode" enrichment (the other open point from this round): CBS only distributes this as downloadable GeoPackage/Excel files, not via the StatLine OData API this actor uses elsewhere — building it would require a materially different architecture (bulk file download + local indexing instead of a live per-item API call). Deferred, not built this round.

2026-07-16 - Bugfix + verbeteringen

• Fixed typeFilter in .actor/input_schema.json missing wijk/buurt — the README and code already supported these values, but the Apify Console UI didn't expose them. Same bug class as the CBS-fields fix below.
• Added addSummaryRecord: an optional, free extra dataset item at the end of a batch run (success/failure counts, average income/population, urbanization spread, unique municipalities/neighborhoods). No pricing change — pure aggregation of data already fetched.
• The CBS column-matching (cbsFieldMap) is now cached in a named key-value store (3-day TTL) instead of being re-fetched every run — cuts one CBS DataProperties call per scheduled run with the same cbsTableId/cbsFields. No pricing change.
• Documented this actor as a callable geocoding backend for other actors via Actor.call().

2026-07-14

• Added match_kwaliteit (hoog/middel/laag/onbekend), an honest geocoding-confidence classification based on PDOK's own relevance score. No pricing change — enrichment of the existing per-result output.

2026-07-12 - Documentatie-update

• Pricing-tekst gecorrigeerd naar "$1.50 per 1,000 results" (was zelf-tegensprekend geformuleerd als "$0.0015 per 1,000 results" naast "$0.0015 per enriched address" — geen prijswijziging, alleen tekstcorrectie).
• "Gerelateerde actors"-sectie toegevoegd met kruisverwijzingen naar andere actors van deze ontwikkelaar.

0.4 - zie .actor/actor.json versie

• Huidige versie zoals vastgelegd in .actor/actor.json (forward/reverse/lookup-geocoding, bulk-verwerking, optionele CBS-buurtverrijking).