Fijnstof API

Van meting tot data

Hoe het werkt

Caireboxen meten de luchtkwaliteit, met name fijnstof, en sturen hun metingen naar TNO. De API levert die metingen als JSON via HTTPS. Je kunt alleen gegevens opvragen (HTTP GET), en elk antwoord beschrijft zichzelf: tijdstempel, meetlocatie, grootheid en eenheid.

v2 Aanbevolen

OGC SensorThings API

Onder https://api.dustmonitoring.nl/v2 staan dezelfde gegevens volgens de open standaard OGC SensorThings API 1.1 (Sensing, alleen lezen). Bestaande clients en bibliotheken voor SensorThings werken er direct mee.

Thing

Een meetlocatie, met het project in properties.

Location, FeatureOfInterest

De geografische positie van de meetlocatie.

Datastream

De reeks van één grootheid op één meetlocatie, bijv. PM10 op I02.

ObservedProperty, Sensor

De gemeten grootheid (PM1, PM2.5, PM10, NO2, ...).

Observation

Eén meetwaarde (result) met tijdstempel (phenomenonTime, UTC).

Ondersteund: $filter (inclusief tekst-, datum-, reken- en geofuncties), $orderby, $top, $skip, $count, $select, $expand (ook genest), $ref en $value. Per aanroep worden standaard 100 records teruggegeven (maximaal 10000); @iot.nextLink geeft de volgende set. Zonder $orderby staan Observations nieuwste eerst.

Filter Observations bij voorkeur op phenomenonTime: een aanroep over de hele historie kan te lang duren en geeft dan HTTP 503. Een $count die te lang duurt, wordt weggelaten.

Alle endpoints, parameters en antwoorden staan in de interactieve referentie (Engels), waar je ze ook direct kunt uitproberen.

Kiezen

v1 of v2?

Beide versies gebruiken dezelfde querytaal ($filter, $expand, $select, $top, $orderby), want SensorThings is op OData gebaseerd. Het verschil zit in het datamodel. Gebruik v2 voor nieuwe koppelingen; bestaande koppelingen op v1 blijven werken.

v1

OData

De v1-API is gebaseerd op de OData-standaard. Toegang via https://api.dustmonitoring.nl/v1. Een project is een verzameling meetlocaties; een locatie is de vaste positie van een cairebox. Voor nieuwe koppelingen raden we v2 aan.

/projects

Overzicht van alle projecten die toegankelijk zijn via de API.

/locations

Lijst van meetlocaties onder een geselecteerd project.

/observations

De actuele gemeten waarden van een geselecteerd project.

/stream

De gemeten waarden binnen een project en per locatie in een vereenvoudigd formaat.

Projects

De aanroep /projects geeft per project de volgende informatie:

• ID: identificatienummer van het project;
• Name: projectnaam;
• Description: korte omschrijving van het project.

De lijst van projecten kan gefilterd worden door de ID van een project mee te geven, bijv. /projects?$filter=id eq 30.

Locations

De aanroep /project(..)/locations geeft per locatie de volgende informatie:

• ID: identificatienummer van de locatie;
• Name: locatienaam;
• Description: korte omschrijving van de locatie;
• Observables: lijst van gemeten entiteiten, bijv. PM1, PM2.5, PM10.

De lijst van locaties kan gefilterd worden door de ID van een locatie mee te geven, bijv. /project(30)/locations?$filter=id eq 521.

Observations

De aanroep /project(..)/observations?$expand=data geeft voor het geselecteerde project de actuele data van alle locaties:

• gegroepeerd per locatie: ID van de locatie;
  • gegroepeerd per tijdseenheid: tijdstempel (UTC) van de meting;
    • Name: naam van de gemeten entiteit;
    • Value: gemeten waarde;
    • Unit: de eenheid van de meetwaarde.

De lijst van locaties kan gefilterd worden door de ID van een locatie mee te geven, bijv. /project(30)/observations?$expand=data&$filter=location eq 521.

Ook kan er een selectie gemaakt worden op weer te geven items, bijv. /project(30)/observations?$filter=location eq 521&$expand=data($select=timestamp,entities/name,entities/value).

Stream

De aanroep /project(..)/location(..)/stream geeft de gemeten waarden van een locatie:

• Timestamp: tijdstempel (UTC) van het tijdstip van meting;
• Entity: ID van de entiteit;
• Name: naam van de gemeten entiteit;
• Value: meetwaarde;
• Unit: de eenheid van de meetwaarde.

De lijst van entiteiten kan gefilterd worden door de ID van de entiteit mee te geven, bijv. alleen de PM1-waarden: /project(30)/location(521)/stream?$filter=entity eq 128, of op naam: ?$filter=name eq 'PM1'.

Een andere mogelijkheid is om op tijd te filteren, bijv. /project(30)/location(521)/stream?$filter=timestamp gt 2026-10-01T00:00:00Z and entity eq 128.

Ook kan een selectie gemaakt worden op weer te geven items, bijv. /project(30)/location(521)/stream?$filter=timestamp gt 2026-10-01T00:00:00Z and entity eq 128&$select=timestamp,entity,value.

Per aanroep worden maximaal 144 records teruggegeven, standaard de oudste eerst; een @odata.nextLink in de uitvoer geeft de volgende set. Met $orderby=timestamp desc krijg je de nieuwste eerst.

Voor een beschrijving van de filtermogelijkheden zie de OData-specificatie.