Overzicht

De Avallo REST API biedt geautoriseerde afnemers programmatische toegang tot grondwatergegevens die door Avallo worden beheerd.

De huidige versie biedt twee publieke resources: een overzicht van beschikbare grondwatermonitoringputten met peilbuizen en meetreeksen voor een afzonderlijke peilbuis.

Basis-URL

Versie 1 is beschikbaar via:

https://api.avallo.nl/v1

De hoofdversie is onderdeel van de URL. De volledige API-versie wordt daarnaast in iedere door de API gegenereerde response vermeld via de header API-Version.

Beschikbare resources

De huidige API bevat de volgende endpoints:

GET /v1/groundwater-monitoring-wells

GET /v1/groundwater-monitoring-tubes/{tubeIdentifier}/measurements?from={from}&to={to}

GET /groundwater-monitoring-wells is het discovery-endpoint. Het retourneert uitsluitend monitoringputten met ten minste één peilbuis waartoe de gebruikte API-sleutel toegang heeft. Binnen een put worden alleen de toegankelijke peilbuizen opgenomen.

Een peilbuis heeft een stabiele identifier. Deze identifier wordt vervolgens gebruikt als tubeIdentifier voor het ophalen van metingen.

Autorisatiemodel

Toegang wordt op peilbuisniveau toegekend.

Een monitoringput kan bijvoorbeeld vier peilbuizen bevatten terwijl een afnemer slechts toegang heeft tot één daarvan. In dat geval wordt de put wel door het discovery-endpoint geretourneerd, maar bevat de response alleen de toegankelijke peilbuis.

Niet-toegankelijke peilbuizen worden niet in de response opgenomen. Daardoor kan een afnemer uit de API niet afleiden hoeveel andere peilbuizen binnen dezelfde put bestaan.

Representatie

Succesvolle responses gebruiken:

application/json

Een meetreeks bevat de peilbuisidentifier, het geretourneerde tijdsinterval, de meeteenheid, het verticale referentiestelsel en chronologisch gesorteerde metingen.

Foutresponses gebruiken waar mogelijk:

application/problem+json

Zie Error handling voor de beschikbare foutstatuscodes en responsemodellen.

Datum en tijd

Datum- en tijdwaarden volgen de door de API vereiste ISO-notatie en worden in OpenAPI beschreven met het formaat date-time.

Een request mag een geldige tijdzone-offset gebruiken:

2026-09-10T10:30:00+02:00

De API normaliseert tijdstippen naar UTC en retourneert bijvoorbeeld:

2026-09-10T08:30:00Z

Voor meetreeksen is from inclusief en to exclusief. Het maximale interval per request is 366 dagen.

Authenticatie

Iedere request naar een beveiligd endpoint bevat een door Avallo verstrekte API-key:

X-API-Key: {apiKey}

De API-key bepaalt welke peilbuizen voor de afnemer beschikbaar zijn. Zie Authenticatie voor het gebruik en beheer van de API-key.

OpenAPI

Het technische API-contract is publiek beschikbaar via:

https://api.avallo.nl/v1/openapi.json

De gegenereerde API-referentie is gebaseerd op dit OpenAPI-contract.