Quickstart en API-documentatie

1. 1. Vraag een sleutel aan

   Maak een account aan en dien de aanvraag in via API-sleutel. De sleutel komt per e-mail; hij begint met dp_ en is daarna niet meer op te vragen — bewaar hem zoals u een wachtwoord bewaart.

2. 2. Doe uw eerste call

   Vervang dp_uw_sleutel door uw eigen sleutel. Dit antwoord is 263 bytes — precies wat u wilt om te controleren of uw sleutel werkt.

   curl -H "X-Api-Key: dp_uw_sleutel" \
     "https://api.datafinitly.com/v1/verduurzaming/BU0363AA01"

   Kopieer

3. 3. Dit krijgt u terug

   {
     "peildatum": "2026-08-09",
     "buurt": {
       "buurtcode": "BU0363AA01",
       "buurtnaam": "Planciusbuurt-Noord",
       "wijkcode": "WK0363AA",
       "gemeentecode": "GM0363",
       "gemeentenaam": "Amsterdam",
       "woningen": 245,
       "gelabeld": 159,
       "efg_woningen": 23,
       "dekking_pct": 64.9,
       "efg_pct_van_gelabeld": 14.5
     }
   }

   Geen 200? Zoek de melding op in de foutentabel. Elke fout zegt in de body wat er mis is.

Elk endpoint hieronder vereist de header X-Api-Key. Er is geen tweede manier: geen sleutel in de querystring, geen Bearer-token, geen anonieme toegang. Stuur de sleutel over HTTPS en zet hem niet in een URL — een URL belandt in logs en in browsergeschiedenis, een header niet.

Basis-URL: https://api.datafinitly.com

• GET /v1/buurten

  Alle buurten met kerncijfers

  Alle CBS-buurten van de laatste peildatum, met inwoners, woningvoorraad, gemiddelde woningwaarde en de buurtgeometrie.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/buurten?geometry=false"

  Kopieer

  geometry

  — querystring. Neem de geometrie mee. Standaard true. Zet op false voor alleen de statistiek — dat scheelt driekwart van de respons.

  Respons

  { peildatum, total_count, features: [ { buurtcode, buurtnaam, wijkcode, gemeentecode, gemeentenaam, water, aantal_inwoners, gemiddeld_inkomen_per_inwoner, woningvoorraad, gemiddelde_woningwaarde, geometry_wkt } ] }

  Gemeten: 4.0 MB in 2,11 s · peildatum van buurten

  Let op — Met geometrie is deze respons 16,0 MB (14.668 buurten, gemeten 3,18 s). Het voorbeeld hiernaast staat daarom op geometry=false: 4,0 MB. Er is geen paginering — u haalt altijd alles op.

• GET /v1/buurten/geojson

  Buurten als GeoJSON

  Dezelfde buurten als een GeoJSON FeatureCollection, klaar voor een kaartlaag. De WKT-geometrie is serverzijdig omgezet.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/buurten/geojson"

  Kopieer

  Respons

  { features: [ { type, geometry: { type, coordinates }, properties: { … } } ] }

  Gemeten: 17.3 MB in 5,58 s · peildatum van buurten

  Let op — Het zwaarste endpoint: 17,3 MB en ruim vijf seconden. Buurten zonder geometrie (water) zitten erin met geometry null — laat uw kaartlaag daarop rekenen.

• GET /v1/buurten/:code

  Eén buurt

  De kerncijfers en de geometrie van één buurt.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/buurten/BU0363AA01"

  Kopieer

  code

  — padparameter. CBS-buurtcode. Vorm: BU + de viercijferige gemeentecode + vier tekens buurtvolgnummer.

  Respons

  { peildatum, feature: { … dezelfde velden als /v1/buurten } }

  Gemeten: 452 bytes in 0,19 s · peildatum van buurten

• GET /v1/gemeenten/:code/energielabels

  Energielabels van één gemeente

  De verdeling over de energielabelklassen voor één gemeente, met aantal en percentage per klasse.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/gemeenten/GM0363/energielabels"

  Kopieer

  code

  — padparameter. CBS-gemeentecode. Vorm: GM + vier cijfers.

  Respons

  { peildatum, gemeentecode, verdeling: [ { klasse, aantal, percentage } ] }

  Gemeten: 830 bytes in 0,13 s · peildatum van energielabels

  Let op — De verdeling telt twaalf klassen. Sorteer zelf op de klasse als u een vaste volgorde nodig hebt — ga niet uit van de volgorde in de respons.

• GET /v1/energielabels

  Energielabels van alle gemeenten

  Dezelfde verdeling, voor elke gemeente in één respons.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/energielabels"

  Kopieer

  Respons

  { gemeenten: [ { gemeentecode, peildatum, totaal, verdeling: [ { klasse, aantal, percentage } ] } ] }

  Gemeten: 367 KB in 0,19 s · peildatum van energielabels

  Let op — Deze respons draagt 463 gemeentecodes, terwijl Nederland 342 gemeenten telt: de labelregistratie kent codes die niet (meer) met een bestaande gemeente overeenkomen, waaronder GM0000. Filter op uw eigen gemeentelijst als u een sluitende telling nodig hebt.

• GET /v1/verduurzaming

  Verduurzamingsopgave per buurt

  Per buurt: woningvoorraad, hoeveel daarvan een geregistreerd energielabel heeft, hoeveel daarvan in de klassen E, F of G valt, en de labeldekking.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/verduurzaming"

  Kopieer

  Respons

  { peildatum, total_count, buurten: [ { buurtcode, buurtnaam, wijkcode, gemeentecode, gemeentenaam, woningen, gelabeld, efg_woningen, dekking_pct, efg_pct_van_gelabeld } ] }

  Gemeten: 3.2 MB in 1,62 s · peildatum van verduurzaming

  Let op — Deze respons telt 14.153 buurten tegen 14.668 in /v1/buurten: buurten zonder woningen staan er niet in. Een verschil van 515 is dus geen ontbrekende data maar een lege noemer — reken er geen nul voor.

• GET /v1/verduurzaming/:code

  Verduurzamingsopgave van één buurt

  Dezelfde cijfers, voor één buurt.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/verduurzaming/BU0363AA01"

  Kopieer

  code

  — padparameter. CBS-buurtcode, dezelfde vorm als bij /v1/buurten — géén gemeentecode.

  Respons

  { peildatum, buurt: { … dezelfde velden als /v1/verduurzaming } }

  Gemeten: 263 bytes in 0,21 s · peildatum van verduurzaming

  Let op — Een buurt die bestaat maar geen woningen heeft, geeft hier een 404 — dezelfde melding als een buurt die niet bestaat.

• GET /v1/natuur/buurten

  Natura 2000-overlap per buurt

  Per buurt hoeveel beschermd natuurgebied erin ligt: aantal gebieden, overlapoppervlak en overlappercentage, met de gebieden zelf erbij.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/natuur/buurten"

  Kopieer

  Respons

  { peildatum, total_count, buurten: [ { buurtcode, buurtnaam, wijkcode, gemeentecode, gemeentenaam, buurt_opp_km2, aantal_gebieden, overlap_km2, overlap_pct, gebieden: [ … ] } ] }

  Gemeten: 3.5 MB in 1,75 s · peildatum van natuur_buurt

  Let op — Een aantal_gebieden van 0 is een gemeten antwoord, geen ontbrekende data — 12.697 van de 14.668 buurten raken geen enkel gebied. En het nul-label is per veld: 107 buurten raken wél een gebied met een grensstrook die onder de afronding van overlap_pct valt.

• GET /v1/natuur/buurten/:code

  Natura 2000-overlap van één buurt

  Dezelfde cijfers, voor één buurt.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/natuur/buurten/BU0363AA01"

  Kopieer

  code

  — padparameter. CBS-buurtcode, dezelfde vorm als bij /v1/buurten.

  Respons

  { peildatum, buurt: { … dezelfde velden als /v1/natuur/buurten } }

  Gemeten: 260 bytes in 0,12 s · peildatum van natuur_buurt

  Let op — Bij nul overlap is gebieden een lege lijst — het antwoord blijft een 200.

• GET /v1/pbl/bebouwing

  Gebouwvoorraad per buurt (alle buurten)

  Woningen en utiliteit per buurt, uitgesplitst naar bouwjaarklasse, energielabel, woningtype en gebruiksfunctie.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/pbl/bebouwing"

  Kopieer

  Respons

  { peildatum, total_count, buurten: [ { buurtcode, buurtnaam, wijkcode, gemeentecode, gemeentenaam, provincienaam, energieregionaam, in_cbs_buurtkaart, woningen, utiliteit_objecten, utiliteit_m2_bvo, woningequivalenten, woning_bouwjaar, woning_label, woning_type, utiliteit_label, utiliteit_functie_m2_bvo } ] }

  Gemeten: 14.9 MB in 4,52 s · peildatum van pbl_bebouwing

  Let op — De volledige lijst is 14,9 MB zonder compressie en gemeten 4,5 s. Hebt u één of enkele buurten nodig, gebruik dan de detailroute hieronder — die is ruim een kilobyte.

• GET /v1/pbl/bebouwing/:code

  Gebouwvoorraad van één buurt

  Dezelfde uitsplitsing, voor één buurt.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/pbl/bebouwing/BU0363AA01"

  Kopieer

  code

  — padparameter. CBS-buurtcode, dezelfde vorm als bij /v1/buurten.

  Respons

  { peildatum, buurt: { … dezelfde velden als /v1/pbl/bebouwing } }

  Gemeten: 1 KB in 0,11 s · peildatum van pbl_bebouwing

  Let op — Let op de eenheid per veld: de gebruiksfuncties in utiliteit_functie_m2_bvo zijn m² bruto vloeroppervlak, de klassen in utiliteit_label zijn aantallen objecten. Wie ze verwisselt, overschat de utiliteitsvoorraad met een factor 484 — de eenheid staat daarom in de veldnaam.

• GET /v1/pbl/strategie

  Warmtestrategieën per buurt (alle buurten)

  Per buurt de doorgerekende warmtestrategieën: CO₂-referenties en de nationale meerkosten per scenario, per ton CO₂ en per woningequivalent.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/pbl/strategie"

  Kopieer

  Respons

  { peildatum, total_count, buurten: [ { buurtcode, buurtnaam, wijkcode, gemeentecode, gemeentenaam, provincienaam, energieregionaam, in_cbs_buurtkaart, woningen, utiliteit_objecten, woningequivalenten, co2_startjaar_ton, co2_referentie_2030_ton, variant, nat_meerkost_eur_jaar, nat_meerkost_eur_per_ton_co2, nat_meerkost_eur_per_weq_jaar } ] }

  Gemeten: 13.3 MB in 3,62 s · peildatum van pbl_strategie

  Let op — De volledige lijst is 13,3 MB zonder compressie — voor één buurt is de detailroute hieronder de weg. Een scenarioveld met null betekent "niet doorgerekend" voor die buurt × dat scenario (141 buurten hebben geen enkel doorgerekend scenario); null is nooit nul.

• GET /v1/pbl/strategie/:code

  Warmtestrategieën van één buurt

  Dezelfde scenariocijfers, voor één buurt.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/pbl/strategie/BU0363AA01"

  Kopieer

  code

  — padparameter. CBS-buurtcode, dezelfde vorm als bij /v1/buurten.

  Respons

  { peildatum, buurt: { … dezelfde velden als /v1/pbl/strategie } }

  Gemeten: 964 bytes in 0,10 s · peildatum van pbl_strategie

• GET /v1/kvk/sectoren

  Bedrijvigheid per sector

  Alle sectoren op de nieuwste peildatum: bedrijven, actieve bedrijven, starters over twaalf maanden en insolventies — per SBI-afdeling én per volledige code.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/kvk/sectoren"

  Kopieer

  Respons

  { peildatum, total_count, sectoren: [ { sbi, is_afdeling, jongste: { peildatum, bedrijven, actief, gestart_12m, faillissementen, surseances } } ] }

  Gemeten: 285 KB in 0,20 s · peildatum van kvk_sectoren

  Let op — De lijst draagt 88 afdelingen plus 1.776 volledige codes, elk met alleen het jongste punt — de volledige reeks staat op de detailroute. Het afdelingsniveau is de eerlijke default: een 4- of 6-cijferige code is in de bron grotendeels dode vocabulaire.

• GET /v1/kvk/sectoren/:sbi

  Eén sector met zijn volledige reeks

  De tijdreeks van één sector, plus de leeftijdsopbouw van de bedrijven erin.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/kvk/sectoren/64"

  Kopieer

  sbi

  — padparameter. Tweecijferige SBI-afdeling (bijv. 64) of een volledige SBI-code (bijv. 64210).

  Respons

  { peildatum, sector: { sbi, is_afdeling, reeks: [ { peildatum, bedrijven, actief, gestart_12m, faillissementen, surseances } ], leeftijd } }

  Gemeten: 2 KB in 0,08 s · peildatum van kvk_sectoren

  Let op — faillissementen en surseances met null zijn onderdrukt onder de kleine-celdrempel (1–9); een 0 is een echte nul. Dat onderscheid is bewust: een klein aantal insolventies in een kleine sector zou anders herleidbaar zijn.

• GET /v1/kvk/insolventie

  Insolventies per sector en postcoderegio

  Faillissementen en surseances per SBI-afdeling, landelijk en per tweecijferige postcoderegio.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/kvk/insolventie"

  Kopieer

  Respons

  { peildatum, total_count, afdelingen: [ { sbi_afdeling, faillissementen_landelijk, surseances_landelijk, regios: [ { postcode_regio, faillissementen } ] } ] }

  Gemeten: 141 KB in 0,14 s · peildatum van kvk_insolventie

  Let op — postcode_regio is twee cijfers — een gebied van tienduizenden adressen, geen postcodegebied. Een afwezige regio of afdeling is een echte nul; een aanwezige met null is onderdrukt onder de kleine-celdrempel (1–9).

• GET /v1/voertuigen/vloot

  Nationale vlootstatistiek

  Het Nederlandse wagenpark in één antwoord: per voertuigsoort, bouwjaar en merk, elk met de verdeling over zeven brandstofcategorieën, plus het emissieprofiel.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/voertuigen/vloot"

  Kopieer

  Respons

  { peildatum, voertuigen, geexporteerd_buiten_telling, per_voertuigsoort: [ { sleutel, voertuigen, verdeling } ], per_bouwjaar: [ … ], per_merk: [ … ], emissieprofiel: [ … ] }

  Gemeten: 41 KB in 0,14 s · peildatum van voertuigen_vloot

  Let op — De zeven brandstofcategorieën zijn wederzijds uitsluitend en tellen exact op tot het celtotaal. Wie zelf brandstofregels telt, telt hybrides dubbel en overschat elektrisch met een factor 2,4 — deze indeling bestaat om die fout te voorkomen.

• GET /v1/jaarrekeningen/benchmark

  Jaarrekeningen-benchmark: het sectoroverzicht

  Deponeringen per sector per boekjaar, plus de landelijke telling die zegt welk deel van de gedeponeerde economie de sectorcellen dekken.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/jaarrekeningen/benchmark"

  Kopieer

  Respons

  { peildatum, total_count, landelijk: [ { boekjaar, deponeringen, geconsolideerd, zonder_sbi } ], sectoren: [ { sbi, is_afdeling, boekjaren: [ { boekjaar, deponeringen } ] } ] }

  Gemeten: 244 KB in 0,17 s · peildatum van jaarrekeningen_benchmark

  Let op — 47,0% van de deponeringen draagt geen bruikbare SBI-code en is voor elke sectorcel onzichtbaar — het veld zonder_sbi zegt dat, in plaats van het de sectortotalen te laten verzwijgen. De benchmarkcijfers zelf staan op de detailroute, mét vullingsgraden.

• GET /v1/jaarrekeningen/benchmark/:sbi

  De benchmark van één sector

  Balans-, resultaat- en kasstroomvelden van één sector per boekjaar: kwartielen en mediaan, elk met het aantal waarnemingen en de vullingsgraad erbij.

  curl -H "X-Api-Key: dp_uw_sleutel" \
    "https://api.datafinitly.com/v1/jaarrekeningen/benchmark/64"

  Kopieer

  sbi

  — padparameter. Tweecijferige SBI-afdeling (bijv. 64) of een volledige SBI-code, dezelfde vorm als bij /v1/kvk/sectoren.

  Respons

  { peildatum, sector: { sbi, is_afdeling, boekjaren: [ { boekjaar, … per veld { n, vullingsgraad, p25, mediaan, p75 } } ] } }

  Gemeten: 7 KB in 0,09 s · peildatum van jaarrekeningen_benchmark

  Let op — Lees de vullingsgraad vóór u een mediaan gebruikt: een veld met weinig waarnemingen draagt null in plaats van een schijnzeker getal.

Elke respons draagt een peildatum: de datum van de stand die u terugkrijgt. Die datum is de eigenschap van de data en niet van uw verzoek — u krijgt altijd de laatste stand, en er is geen manier om een oudere op te vragen.

De datasets bewegen onafhankelijk van elkaar, dus twee endpoints kunnen op hetzelfde moment een verschillende peildatum geven. Dat is geen fout: het betekent dat de ene bron recenter is ververst dan de andere. Wilt u twee responsen combineren, lees dan bij beide de peildatum uit en bewaar hem bij uw uitkomst — anders weet u later niet meer welke stand u hebt gebruikt.

De actuele peildatum per dataset staat, zonder sleutel, op de catalogus.

Uw sleutel heeft een tegoed van 60 verzoeken dat met één verzoek per seconde weer aangroeit. U kunt dus 60 verzoeken achter elkaar doen en daarna ongeveer één per seconde volhouden. Boven dat tempo krijgt u een 429.

Twee dingen die u moet weten voordat u hierop bouwt. Het 429-antwoord bevat geen Retry-After-header, dus uw client moet zelf een wachttijd kiezen; één seconde per verzoek is het tempo waarop uw tegoed aangroeit. En het tegoed wordt bijgehouden per draaiend exemplaar van de dienst, die onder belasting meerdere exemplaren start — 60 per minuut is daarom de ondergrens waar u op mag rekenen, en geen exacte grens die de dienst als geheel bewaakt.

Hebt u structureel meer nodig, of wilt u de volledige dataset periodiek ophalen? Neem contact op — dat is een kwestie van afspraken, niet van terugproberen.

Elke fout is JSON met dezelfde twee velden: code (stabiel, bedoeld om op te programmeren) en message (voor een mens). Programmeer op de statuscode en op code, niet op de tekst.

De eerste zes vormen zijn uitgelokt op de draaiende dienst en letterlijk overgenomen. De 5xx-vorm niet: die uitlokken betekent de dienst laten falen. Die regel komt uit het foutcontract van de code zelf en is met een test vastgelegd, zodat deze pagina niet stil onwaar kan worden.

Zodat u er niet naar hoeft te zoeken:

• Een oudere peildatum opvragen. Elk endpoint levert de laatste stand; historie is niet ontsloten.
• Filteren, sorteren of pagineren op de server. De lijst-endpoints leveren alles; filter aan uw kant.
• Gegevens per adres of per pand. Het platform serveert op buurt- en gemeenteniveau.
• Een webhook of notificatie bij een nieuwe peildatum. Lees de peildatum uit de respons die u toch al ophaalt.