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.
- /nearby?lat=52.09&lng=5.12 — waar je in de buurt kunt schaatsen: eerst natuurijs, en kunstijsbanen als er geen bruikbaar natuurijs is. Optioneel: radius_km (standaard 50), limit (standaard 10) en preference (natural, artificial of all).
- /locations — alle natuurijslocaties met hun actuele status, in één keer. Genoeg om een hele kaart te tekenen.
- /locations/{slug} — één locatie, met het aantal meldingen van de laatste 24 uur en 7 dagen.
- /rinks — alle kunstijsbanen met openingstijden, seizoen en voorzieningen.
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:
- Bronvermelding is verplicht. Toon je de gegevens op een webpagina of in een app, dan staat daar zichtbaar "Bron: Natuurijs.nl" met een link naar natuurijs.nl of naar de pagina van de locatie (het veld url). Is er geen plek voor een link, zoals bij spraak of een display, dan noem je Natuurijs.nl. Hoe je de link opmaakt, bepaal je zelf.
- Toon je een natuurijsstatus, dan toon je de veiligheidstekst uit safety_note erbij. Een status is een schatting of een melding, nooit een veiligheidsoordeel, en zo presenteer je hem ook.
- Laat zien hoe oud de gegevens zijn (checked_at), of ververs ze minstens één keer per dag.
- De gegevens zelf doorverkopen mag niet.
- De API is gratis en komt zonder garantie: hij kan uitvallen of veranderen. We kunnen een sleutel intrekken of limieten aanpassen, bijvoorbeeld bij misbruik.
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.