Fijnstof API

TNO EMSA meet op diverse locaties de luchtkwaliteit. Met deze API worden de meetgegevens van een aantal locaties ontsloten. Voor meer informatie over TNO activiteiten op het gebied van het meten van luchtkwaliteit zie: https://www.tno.nl/nl/aandachtsgebieden/circulaire-economiemilieu/expertisegroepen/environmental-modelling-sensing-analysis/

Algemeen

• De API is gebaseerd op de ODATA standaard;
• De API wordt aangeboden als een JSON/REST koppeling;
• De API ondersteund alleen opvragen van gegevens (HTTP GET);
• De communicatie is versleuteld (HTTPS);
• Het teruggegeven JSON object is zelf beschrijvend (tijdstempel, stationsnaam, sensornamen, eenheden).

Begrippen

• Project: verzameling van onderling gerelateerd meetlocaties;
• Locatie: vaste geografische positie van een fijnstof meetapparaat, een zogenaamde ‘cairebox’;
• Cairebox: een apparaat om luchtkwaliteit te meten, met name fijnstof.

Toegang

https://api.dustmonitoring.nl/v1

Interface

• /projects: Geeft een overzicht van alle projecten die toegankelijk zijn via de API;
• /locations Geeft een lijst van meetlokaties onder een geselecteerd project;
• /observations Geeft de actuele gemeten waarden van een geselecteerd project;
• /stream Geeft de gemeten waarden binnen een project en per lokatie in een vereenvoudigde formaat.

Details

Projects

De aanroep /projects geeft per project de volgende informatie:

• ID: Identificatienummer van het project;
• Name: project naam;
• 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

Voorbeeld:

Aanroep:
https://api.dustmonitoring.nl/v1/projects?$filter=id eq 30

Resultaat:
ID, name en description van geselecteerd project.

Locations

De aanroep /projects(..)/locations geeft per lokatie de volgende informatie:

• ID: Identificatienummer van de lokatie;
• Name: lokatie naam;
• Description: Korte omschrijving van de lokatie;
• Observables: Lijst van gemeten entiteiten, bijv: PM1, PM2.5, PM10.

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

Voorbeeld:

Aanroep:
https://api.dustmonitoring.nl/v1/project(30)/locations?$filter=id eq 521

Resultaat:
ID, name, description, observables van geselecteerde lokatie.

Observations

De aanroep /projects(..)/observations?$expand=data geeft voor het geselecteerde project de actuele data van alle locaties, de volgende informatie wordt teruggegeven:

• Gegroepeerd per Location: ID van de lokatie;
• • Gegroepeerd per tijdseenheid: Tijdstempel (UTC) van de meting;
  • • Name: Naam van de gemeten entiteit;
    • Value: Gemeten waarde;
    • Unit:De eenheid ban de meetwaarde;

De lijst van lokaties kan gefilterd worden door de ID van een lokatie 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)

Voorbeeld:

Aanroep:
https://api.dustmonitoring.nl/v1/project(30)/observations?$filter=location eq 521&$expand=data($select=timestamp,entities/name,entities/value)

Resultaat:
location, Timestamp en meetdata van geselecteerde lokatie.

Stream

De aanroep /projects(..)/stream geeft voor het geselecteerde project de actuele data van alle locaties, de volgende informatie wordt teruggegeven:

• Timestamp: Tijdstempel (UTC) van het tijdstip van meting;
• Entity: ID van 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 geef alleen de PM1 waarden: /project(28)/location(12)/stream?$filter=entity eq 30

Een andere mogelijkheid is om op tijd te filteren, bijv: /project(28)/location(12)/stream?$filter=timestamp gt 2020-07-24T07:07:28Z and entity eq 30

Ook kan een selectie gemaakt worden op weer te geven items, bijv: /project(30)/location(521)/stream?$filter=timestamp gt 2020-10-19T06:07:28Z and entity eq 30&$select=timestamp,entity,value

Per aanroep wordt een vastgesteld aantal records teruggegeven, een ‘odata.nextLink’ in de uitvoer geeft de mogelijkheid de volgende set records op te halen.

Voorbeeld:

Aanroep:
https://api.dustmonitoring.nl/v1/project(30)/location(521)/stream?$filter=timestamp gt 2020-10-19T06:07:28Z and entity eq 30&$select=timestamp,entity,value

Resultaat:
location, Timestamp en meetdata van geselecteerde lokatie.

Voor een beschrijving van de filter mogelijkheden zie de ODATA specificatie: https://www.odata.org/