Gegevens gebruiken

API-documentatie

Gebruik geregistreerde bestrijdingsgegevens van RattenMonitor Nederland op uw website, in een analyse of in een dashboard.

Een API laat een toepassing gegevens opvragen. RMN biedt openbare statistieken en persoonlijke statistieken. Beide leveren JSON: gegevens in een vaste, machineleesbare structuur.

De cijfers gaan over geregistreerde bestrijdingen. Ze vormen geen volledig overzicht van alle rattenbestrijding in Nederland en zeggen op zichzelf niets over de effectiviteit van een methode.

Openbare statistieken

Geen account nodig en geen API-token nodig. Alleen geaggregeerde gegevens: opgetelde cijfers zonder persoonsgegevens of individuele registraties.

Persoonlijke statistieken

Een actief RMN-account en een persoonlijk API-token zijn nodig. U ontvangt alleen uw eigen gekoppelde productieregistraties; anonieme en testregistraties worden niet meegenomen.

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.

Beschikbare filters voor de openbare API
Parameter	Gebruik
`jaar`	Een jaar vanaf 2026 tot en met het huidige Nederlandse kalenderjaar. Selecteert het volledige kalenderjaar.
`maand`	1 tot en met 12, alleen samen met `jaar`. Selecteert de volledige kalendermaand.
`van`, `tot`	Beide verplicht bij een datumbereik, in strikt `YYYY-MM-DD`. Beide grensdatums tellen mee; de begindatum mag niet na de einddatum liggen. Niet combineren met `jaar` of `maand`. Een expliciet bereik mag ook oudere jaren omvatten.
`provincie`	Een provinciecode uit het overzicht hieronder.
`methode`	Een code voor de bestrijdingsmethode.
`soort`	Een rattensoortcode.

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 — honden
FRETTEN — fretten
RODENTICIDE — rodenticide
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 productieregistraties terug. Anonieme registraties, testregistraties en registraties van andere bestrijders zijn uitgesloten. Anonieme registraties kunnen later niet persoonlijk teruggekoppeld worden.

De totalen gelden voor 1 januari van het huidige jaar tot en met vandaag, volgens de applicatietijdzone. De effectieve selectie staat in periode. Deze versie biedt geen persoonlijke filters.

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. laatste_registratie bevat de datum, het aantal ratten en de provinciecode van de meest recente eigen productieregistratie tot vandaag.

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 productieregistratie is laatste_registratie null. Er worden geen persoonsgegevens, exacte locaties, exacte tijden of interne identificatienummers teruggegeven.

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 ontving een ongeldige parameter of filtercombinatie.
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 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/.