API-documentatie

Openbare API

GET /api/v1/statistieken/

Authenticatie: geen. Zonder datumfilters loopt de periode van 1 januari van het huidige kalenderjaar tot en met vandaag, volgens de Nederlandse tijdzone (Europe/Amsterdam).

Filters

Alle onderstaande filters zijn optioneel. Categoriefilters kunnen met de gekozen periode en met elkaar gecombineerd worden.

Codes in kleine letters worden geaccepteerd, bijvoorbeeld ut, pcp en bruine_rat. In de response staan hoofdletters. Provincienamen zoals utrecht zijn geen geldige codes. Onbekende, lege of herhaalde parameters en ongeldige combinaties geven HTTP 400.

Provinciecodes

DR

Drenthe

FL

Flevoland

FR

Friesland

GE

Gelderland

GR

Groningen

LI

Limburg

NB

Noord-Brabant

NH

Noord-Holland

OV

Overijssel

UT

Utrecht

ZE

Zeeland

ZH

Zuid-Holland

Methoden

• PCP — PCP / luchtdrukwapen
• KLEM — mechanische klem / slagval
• VANGKOOI — vangkooi
• HONDEN_FRETTEN — honden/fretten
• ANDERS — andere methode

Soorten

BRUINE_RAT (bruine rat), ZWARTE_RAT (zwarte rat) en ONBEKEND (onbekende soort).

Voorbeelden met filters

GET /api/v1/statistieken/?jaar=2026&methode=PCP
GET /api/v1/statistieken/?jaar=2026&provincie=UT&methode=PCP&soort=BRUINE_RAT

Hieronder staat fictieve voorbeelddata voor de tweede aanvraag, dus geen actuele cijfers.

{
  "api_version": "v1",
  "periode": {
    "van": "2026-01-01",
    "tot": "2026-12-31",
    "jaar": 2026,
    "maand": null
  },
  "filters": {
    "provincie": "UT",
    "methode": "PCP",
    "soort": "BRUINE_RAT"
  },
  "totalen": {"ratten": 37, "registratiemomenten": 8},
  "soorten": {"BRUINE_RAT": 37},
  "methoden": {"PCP": 37},
  "provincies": {"UT": 37},
  "registratievorm": {"gekoppeld": 30, "anoniem": 7},
  "deelnemende_bestrijders": {"aantal": 3, "minimum": true}
}

Wat betekenen de responsevelden?

api_version

De gebruikte API-versie: v1.

periode

De effectieve begin- en einddatum, het jaar en de eventuele maand. Bij een expliciet datumbereik zijn jaar en maand beide null.

filters

De geselecteerde categoriecodes. Een niet-gebruikte categoriefilter heeft de waarde null.

totalen

ratten telt ratten uit de geselecteerde soortregels. registratiemomenten telt unieke momenten. Eén registratie met drie bruine en twee zwarte ratten is vijf ratten en één registratiemoment; met filter BRUINE_RAT zijn dat drie ratten en één moment.

soorten, methoden, provincies

Aantallen ratten per code, steeds voor dezelfde selectie. Zonder filter op die categorie staan alle bijbehorende codes erin, ook bij nul ratten. Met een categoriefilter bevat die verdeling alleen de geselecteerde code.

registratievorm

Aantallen ratten uit gekoppelde en anonieme registraties. Anonieme productieregistraties tellen wel mee in de openbare totalen; testregistraties zijn uitgesloten.

deelnemende_bestrijders

aantal telt unieke registrerende identiteiten. minimum is true wanneer anonieme ratten in de selectie zitten: het aantal bestrijders is dan een minimum, omdat anonieme registraties niet aan een bestrijder gekoppeld zijn.

Persoonlijke API

GET /api/v1/mijn-statistieken/
Authorization: Bearer <persoonlijk-api-token>

Dit endpoint geeft alleen eigen gekoppelde registraties terug. Voor pilotaccounts tellen eigen testregistraties mee; voor productieaccounts blijven testregistraties uitgesloten. Anonieme registraties en registraties van andere bestrijders zijn uitgesloten. Anonieme registraties kunnen later niet persoonlijk teruggekoppeld worden.

Zonder uitgebreid=1 gelden de totalen voor 1 januari van het huidige jaar tot en met vandaag, volgens de applicatietijdzone. De effectieve selectie staat in periode. Het bestaande responsecontract blijft gelijk: queryparameters zonder opt-in worden genegeerd. Een expliciet opgegeven uitgebreid met een andere waarde dan 1 geeft 400.

Hieronder staat fictieve voorbeelddata, geen actuele cijfers.

{
  "api_version": "v1",
  "periode": {
    "van": "2026-01-01",
    "tot": "2026-09-08",
    "jaar": 2026
  },
  "totalen": {
    "ratten": 27,
    "registratiemomenten": 8
  },
  "laatste_registratie": {
    "datum": "2026-09-08",
    "aantal_ratten": 6,
    "provincie": "UT"
  }
}

totalen.ratten is de som van de ratten; totalen.registratiemomenten telt ieder moment één keer, ook bij meerdere rattensoorten. Alleen registraties met integriteitsstatus normaal of goedgekeurd tellen mee. laatste_registratie bevat de datum, het aantal ratten en de provinciecode van de meest recente eigen meetellende registratie tot vandaag, inclusief eigen testdata bij pilotaccounts.

De laatste registratie kan uit een eerder kalenderjaar komen. Dan kan het jaartotaal nul zijn terwijl er toch een laatste registratie staat. Zonder eerdere eigen meetellende registratie is laatste_registratie null. Er worden geen persoonsgegevens, exacte locaties, exacte tijden of interne identificatienummers teruggegeven.

Uitgebreide persoonlijke statistieken

Vraag de uitgebreide variant expliciet aan met uitgebreid=1. Gebruik dezelfde Bearer-header. Optionele filters jaar, maand en provincie combineren met AND: alleen registraties die aan alle opgegeven filters voldoen tellen mee.

• ?uitgebreid=1: huidig jaar tot vandaag, alle eigen provincies.
• ?uitgebreid=1&jaar=2026: eigen resultaten in het opgegeven jaar.
• ?uitgebreid=1&jaar=2026&maand=9: eigen resultaten in september.
• ?uitgebreid=1&provincie=UT: Utrecht, huidig jaar tot vandaag.
• ?uitgebreid=1&jaar=2026&provincie=UT: Utrecht in het opgegeven jaar.
• ?uitgebreid=1&jaar=2026&maand=9&provincie=UT: Utrecht in september van het opgegeven jaar.

jaar is een geheel getal vanaf 2026 tot en met het huidige jaar in Europe/Amsterdam. maand is een geheel getal van 1 tot en met 12 en vereist ook jaar. Gebruik bij provincie een provinciecode uit de codetabel; invoer is hoofdletterongevoelig, bijvoorbeeld ut wordt UT.

De persoonlijke allowlist bestaat uit uitgebreid, jaar, maand en provincie. Lege, dubbele of onbekende parameters geven 400 binnen de uitgebreide variant. van, tot, methode en soort worden hier niet ondersteund. Een registratie-identiteit uit een request wordt nooit gebruikt.

Zonder expliciet jaar loopt periode van 1 januari tot vandaag. Met jaar beschrijft deze het volledige kalenderjaar; met jaar en maand de volledige kalendermaand. peildatum is vandaag volgens de applicatietijdzone: registraties na deze datum zijn altijd uitgesloten, ook bij een volledige jaarperiode. Een toekomstige maand in het huidige jaar is geldig en geeft een lege selectie.

Alleen de uitgebreide response voegt peildatum, filters, per_maand en per_provincie toe, en voegt maand toe aan periode. Niet opgegeven filters zijn null; periode beschrijft het aangevraagde datumbereik en peildatum begrenst dit tot vandaag.

Beide uitsplitsingen zijn altijd aanwezig in de uitgebreide variant. Ze bevatten uitsluitend groepen met meetellende registratiemomenten. Maanden staan chronologisch, provincies op provinciecode. Ontbrekende groepen betekenen nul. De sommen van ratten en registratiemomenten in elke uitsplitsing komen overeen met totalen.

laatste_registratie blijft onafhankelijk van de filters. Dit blijft de laatste eigen meetellende registratie tot vandaag. Bij een filter op NH kan deze dus provincie UT hebben, en bij een maandfilter buiten de aangevraagde maand liggen.

Uitgebreid zonder filters, met fictieve voorbeelddata en peildatum 8 september 2026:

{
  "api_version": "v1",
  "periode": {"van": "2026-01-01", "tot": "2026-09-08", "jaar": 2026, "maand": null},
  "totalen": {"ratten": 19, "registratiemomenten": 4},
  "laatste_registratie": {"datum": "2026-09-08", "aantal_ratten": 3, "provincie": "UT"},
  "peildatum": "2026-09-08",
  "filters": {"jaar": null, "maand": null, "provincie": null},
  "per_maand": [
    {"jaar": 2026, "maand": 8, "ratten": 7, "registratiemomenten": 1},
    {"jaar": 2026, "maand": 9, "ratten": 12, "registratiemomenten": 3}
  ],
  "per_provincie": [
    {"provincie": "NH", "ratten": 4, "registratiemomenten": 1},
    {"provincie": "UT", "ratten": 15, "registratiemomenten": 3}
  ]
}

Dezelfde fictieve gegevens bij ?uitgebreid=1&jaar=2026&maand=9&provincie=NH:

{
  "api_version": "v1",
  "periode": {"van": "2026-09-01", "tot": "2026-09-30", "jaar": 2026, "maand": 9},
  "totalen": {"ratten": 4, "registratiemomenten": 1},
  "laatste_registratie": {"datum": "2026-09-08", "aantal_ratten": 3, "provincie": "UT"},
  "peildatum": "2026-09-08",
  "filters": {"jaar": 2026, "maand": 9, "provincie": "NH"},
  "per_maand": [{"jaar": 2026, "maand": 9, "ratten": 4, "registratiemomenten": 1}],
  "per_provincie": [{"provincie": "NH", "ratten": 4, "registratiemomenten": 1}]
}

Bij een geldige selectie zonder resultaten volgt 200 met nultotalen en lege arrays. De laatste registratie kan nog steeds aanwezig zijn. Bijvoorbeeld bij ?uitgebreid=1&jaar=2026&maand=12:

{
  "api_version": "v1",
  "periode": {"van": "2026-12-01", "tot": "2026-12-31", "jaar": 2026, "maand": 12},
  "totalen": {"ratten": 0, "registratiemomenten": 0},
  "laatste_registratie": {"datum": "2026-09-08", "aantal_ratten": 3, "provincie": "UT"},
  "peildatum": "2026-09-08",
  "filters": {"jaar": 2026, "maand": 12, "provincie": null},
  "per_maand": [],
  "per_provincie": []
}

Authenticatie en tokens

Voor persoonlijke API-toegang moet uw RMN-account actief zijn. Maak een token via Mijn account → API-toegang. U kunt meerdere tokens aanmaken. Geef elk token een herkenbare naam voor de website of toepassing waarvoor u het gebruikt.

Een token wordt slechts één keer volledig getoond, direct na aanmaken. Bewaar het veilig op de server van uw toepassing. Bij verlies trekt u het oude token in en maakt u een nieuw token aan.

Stuur het token in de Authorization-header met Bearer ervoor. Een browsersessie of een token in queryparameters geldt niet als API-authenticatie. Advies: vraag persoonlijke gegevens server-side op, zodat het token niet naar de browser gaat.

Voorbeeld in PowerShell

De host example.invalid en het token hieronder zijn fictief. Gebruik uw eigen serveradres en lees uw echte token uit een veilige serverconfiguratie.

$headers = @{
    Authorization = "Bearer rmon_voorbeeldtoken"
}

Invoke-RestMethod `
    -Uri "https://example.invalid/api/v1/mijn-statistieken/" `
    -Headers $headers

HTTP-statuscodes

200 OK

De aanvraag is geslaagd; de API geeft de statistieken terug als JSON.

400 Bad Request

De openbare API of uitgebreide persoonlijke API ontving een ongeldige parameter of filtercombinatie. Een andere expliciete waarde voor uitgebreid dan 1 geeft ook 400.

401 Unauthorized

Het persoonlijke token ontbreekt, is ongeldig of is ingetrokken, of het account heeft geen toegang. Details over token- of accountstatus worden bewust niet prijsgegeven.

405 Method Not Allowed

Beide endpoints accepteren uitsluitend GET. Andere methoden, ook HEAD en OPTIONS, geven 405 met de header Allow: GET.

Een voorbeeld van een openbare filterfout:

{"error": {"code": "ongeldige_parameter", "parameter": "methode", "message": "Onbekende waarde voor deze categorie."}}

Een persoonlijke filterfout bij ?uitgebreid=1&jaar=2026&maand=13:

{"error": {"code": "ongeldige_parameter", "parameter": "maand", "message": "Kies een maand van 1 tot en met 12."}}

De persoonlijke API controleert eerst de HTTP-methode, dan het Bearer-token en pas daarna de parameters. Een ongeldig token met ongeldige filters geeft dus 401.

Een persoonlijke aanvraag zonder geldige toegang geeft steeds dezelfde foutmelding en de header WWW-Authenticate: Bearer:

{"error": {"code": "niet_geautoriseerd", "message": "Een geldig Bearer-token is vereist."}}

Veilig gebruik

• Tokens zijn geheim. Deel ze nooit in publieke code of repositories.
• Plaats tokens nooit in frontend-JavaScript of publiek toegankelijke HTML. Gebruik ze alleen server-side.
• Gebruik HTTPS in productie en stuur het token via de Authorization: Bearer-header.
• Gebruik geen token in queryparameters van een URL.
• Trek een token direct in als het mogelijk is gelekt.
• Maak bij voorkeur per toepassing een apart token met een herkenbare naam.

Persoonlijke API-responses gebruiken Cache-Control: no-store. De openbare API vereist geen token. Er is geen cross-origin browsertoegang (CORS) vrijgegeven; ophalen vanaf uw eigen server is daarvoor niet afhankelijk van CORS.

Versiebeleid

De API-versie staat in de URL: /api/v1/. Binnen v1 proberen we bestaande clients niet te breken. Een incompatibele wijziging hoort in een volgende versie, bijvoorbeeld /api/v2/.