Voor ontwikkelaars: de Natuurijs API

De statussen van alle natuurijslocaties en de gegevens van de kunstijsbanen zijn op te vragen via een API. Die is gratis en bedoeld voor wie er zelf iets mee wil bouwen: een eigen kaart, een app, een schermpje in de kantine van de ijsclub of een koppeling met je huisautomatisering. Je hebt een sleutel nodig en je noemt Natuurijs.nl als bron.

Wat je kunt opvragen

Alle adressen beginnen met https://natuurijs.nl/api/v1 en geven JSON terug. Je roept ze aan met GET.

Wat er in een antwoord zit

Elk antwoord heeft dezelfde vorm: data met de gevraagde gegevens, checked_at met het tijdstip, attribution met de bronvermelding en de link die erbij hoort, en safety_note met de veiligheidstekst zodra het antwoord een natuurijsstatus bevat.

Bij een locatie staat de status (geen ijs, ijs groeit, bijna schaatsbaar, schaatsbaar gemeld of officieel open), waar die status vandaan komt (het model, meldingen of de ijsclub), wanneer hij is berekend en of er in de laatste 24 uur een wak is gemeld. Namen, notities en foto’s uit meldingen zitten er niet in, net als ijsdiktes: die geven we niet door.

Een sleutel aanvragen

Stuur een bericht via het contactformulier met je naam, wat je wilt bouwen en hoeveel verzoeken per dag je ongeveer verwacht. Je krijgt de sleutel per mail. We geven sleutels met de hand uit, dus reken op een paar dagen.

De sleutel stuur je mee als header: Authorization: Bearer gevolgd door je sleutel. Zet hem niet in de URL; een verzoek met een sleutel in de URL wordt geweigerd. Houd de sleutel voor jezelf en bouw hem niet in een webpagina of app in waar anderen hem kunnen uitlezen. Is hij toch uitgelekt, laat het weten en je krijgt een nieuwe.

Limieten

Een sleutel is goed voor 1.000 verzoeken per dag. De teller begint elke nacht om twaalf uur opnieuw. Hoeveel je over hebt, staat in elk antwoord in de headers X-RateLimit-Limit en X-RateLimit-Remaining. Ben je erdoorheen, dan krijg je code 429 met in Retry-After het aantal seconden tot middernacht.

Heb je meer nodig, vraag het aan; we verhogen de limiet per sleutel. Statussen worden een paar keer per dag herberekend, dus vaker dan eens per kwartier ophalen levert niets nieuws op. Er geldt ook een dagbudget voor alle gebruikers samen; als dat op is, krijgt iedereen tot middernacht code 429.

Voorwaarden

Door de API te gebruiken ga je akkoord met het volgende:

Waar de gegevens vandaan komen

De statussen berekent Natuurijs.nl zelf, uit weerdata van het KNMI (CC BY 4.0) en Open-Meteo, aangevuld met meldingen van schaatsers en ijsclubs. De locaties zijn samengesteld uit onder meer OpenStreetMap (© OpenStreetMap-bijdragers, ODbL), lijsten van de KNSB-gewesten en van gemeenten.

Voor AI-assistenten

Dezelfde gegevens zijn er ook als MCP-server, zodat een assistent als Claude ze rechtstreeks kan opvragen. Het adres is https://natuurijs.nl/api/mcp. In Claude voeg je dat toe als eigen connector; een sleutel is daarvoor niet nodig.

Zonder sleutel deel je één dagbudget met alle andere gebruikers zonder sleutel. Bouw je een eigen assistent en wil je daar niet van afhangen, stuur dan je sleutel mee als header Authorization: Bearer; de aanroepen tellen dan mee voor je eigen limiet. De server heeft vier hulpmiddelen, alle alleen-lezen: schaatsen in de buurt, de locaties in een provincie, de status van één locatie en de kunstijsbanen.