Aan de slag

In deze handleiding haal je eerst de voor jouw API-key beschikbare monitoringputten en peilbuizen op. Daarna gebruik je de identifier van een peilbuis om een grondwatermeetreeks op te vragen.

Je hebt hiervoor een door Avallo verstrekte API-key nodig.

Basis-URL

Versie 1 van de API is beschikbaar via:

https://api.avallo.nl/v1

Beschikbare peilbuizen ophalen

Gebruik eerst het discovery-endpoint:

curl --request GET \
  --url "https://api.avallo.nl/v1/groundwater-monitoring-wells" \
  --header "Accept: application/json" \
  --header "X-API-Key: {apiKey}"

Een succesvolle request retourneert 200 OK:

[
  {
    "name": "B00A0000",
    "tubes": [
      {
        "identifier": "ada37574-9e0e-462e-85a1-97a2c7b53fdf",
        "number": "1"
      }
    ]
  }
]

De response bevat alleen monitoringputten en peilbuizen waartoe de gebruikte API-key toegang heeft. name is de herkenbare naam van de put. Gebruik voor vervolgrequests altijd identifier van de gewenste peilbuis.

Grondwatermetingen ophalen

Gebruik de peilbuisidentifier als tubeIdentifier en geef het gewenste tijdsinterval op met from en to:

curl --request GET \
   --url "https://api.avallo.nl/v1/groundwater-monitoring-tubes/ada37574-9e0e-462e-85a1-97a2c7b53fdf/measurements?from=2026-09-01T00%3A00%3A00Z&to=2026-09-08T00%3A00%3A00Z" \
   --header "Accept: application/json" \
   --header "X-API-Key: {apiKey}"

from is inclusief en to is exclusief. Het voorbeeld vraagt dus metingen op vanaf 1 september 2026 om 00:00 UTC tot, maar niet inclusief, 8 september 2026 om 00:00 UTC.

Het maximale tijdsinterval per request is 366 dagen.

Requests mogen een geldige tijdzone-offset bevatten:

2026-09-01T02:00:00+02:00

De API converteert het tijdstip naar UTC:

2026-09-01T00:00:00Z

Response

Een succesvolle request retourneert een GroundwaterLevelSeries:

{
  "tubeIdentifier": "ada37574-9e0e-462e-85a1-97a2c7b53fdf",
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-09-08T00:00:00Z",
  "unit": "m",
  "verticalDatum": "NAP",
  "measurements": [
    {
      "observedAt": "2026-09-01T00:00:00Z",
      "value": 31.6799
    },
    {
      "observedAt": "2026-09-01T01:00:00Z",
      "value": 31.6812
    }
  ]
}

De waarden in measurements zijn chronologisch gesorteerd. unit bevat de meeteenheid en verticalDatum het verticale referentiestelsel van de reeks.

De identificaties en meetwaarden in de voorbeelden zijn illustratief.

Niet-toegankelijke peilbuis

Wanneer tubeIdentifier onbekend is of niet beschikbaar is voor de gebruikte API-sleutel, retourneert de API:

404 Not Found

De API maakt daarbij geen onderscheid tussen een niet-bestaande en een niet-toegankelijke peilbuis.

Fouten

Foutresponses gebruiken waar mogelijk:

application/problem+json

Veelvoorkomende statuscodes zijn 400 voor ongeldige invoer, 401 voor ontbrekende of ongeldige authenticatie, 404 voor een onbekende of niet-toegankelijke peilbuis en 429 wanneer de verzoeklimiet is bereikt.

Zie Error handling voor de volledige uitleg en Rate Limiting voor de gepubliceerde verzoeklimieten.