Dit document beschrijft een API voor het ophalen van fiets data voor een gegeven periode en locatie(s). De metingen zijn per uur berekend.
De API bestaat uit twee soorten endpoints:
Authenticatie verloopt via OAuth. Bij aanroep van de API moet een “OAuth token” worden meegestuurd. Via de Keycloak server (keycloak.ndwcloud.nu) kan een dergelijk OAuth token verkregen worden. Hiervoor is een Dexter gebruikersnaam en wachtwoord nodig. Mocht de aanvrager nog geen Dexter gebruikersnaam/wachtwoord hebben dan zal hij/zij deze moeten aanvragen via de NDW servicedesk.
Voorbeeld
Op de volgende wijze kan een OAuth token worden verkregen (via curl):
curl -d "username=
Hierop volgt onderstaand response:
{
"access_token": "
"expires_in": 1800,
"refresh_expires_in": 3600,
"refresh_token": "
"token_type": "Bearer",
"not-before-policy": 0,
"session_state": "81ae1763-9c99-4c54-99b8-5e0629f8a2d6",
"scope": "profile email"
}
Het response bevat een access_token. De inhoud van dit access_token moet bij aanroep van de API worden meegestuurd. Dit kan middels een HTTP header:
Authorization: Bearer
HTTP Methode
POST
URL
https://dexter.ndwcloud.nu/api/explore/bicycle-data
Request
Header
Er moet een Authorization header worden meegestuurd met daarin een OAuth token. Zie
paragraaf authenticatie voor details.
Body
De body dient een start/eind tijd te bevatten en een lijst met locaties.
Let op dat de start- en eind tijd in Zulu tijd zijn. Dat heeft met de interne opslag in de database te maken. Binnen Dexter vertaalt de frontend de Nederlandse tijd die de gebruiker
opgeeft naar de Zulu tijd en terug, maar bij gebruik van de API moet de aanvrager deze actie zelf uitvoeren.
Veldnaam | Beschrijving |
---|---|
startTime | Startdatum van de geselecteerde periode. De datum dient in de format ‘YYYY-MM-DDTHH:mm:ssZ’ te worden gestuurd. |
endTime | Eind datum van de geselecteerde periode. De datum dient in de format ‘YYYY-MM-DDTHH:mm:ssZ’ te worden gestuurd. |
locations | Hiermee worden de geselecteerde locaties gespecificeerd. De API verwacht hier een lijst met locatie IDs. |
HTTP Methode
POST
URL
https://dexter.ndwcloud.nu/api/explore/bicycle-data/prefix
Request
Header
Er moet een Authorization header worden meegestuurd met daarin een OAuth token. Zie paragraaf authenticatie voor details.
Body
De body dient een start/eind tijd te bevatten en een lijst met een of meerdere prefixen. Een prefix is een deel van een locatie ID. Zo zal de prefix “GAL” resultaten geven voor de
meetlocaties met locatie ID’s “GAL01” en “GAL02” etc .
Let op dat de start- en eind tijd in Zulu tijd zijn. Dat heeft met de interne opslag in de database te maken. Binnen Dexter vertaalt de frontend de Nederlandse tijd die de gebruiker
opgeeft naar de Zulu tijd en terug, maar bij gebruik van de API moet de aanvrager deze actie zelf uitvoeren.
Veldnaam | Beschrijving |
---|---|
startTime | Startdatum van de geselecteerde periode. De datum dient in de format ‘YYYY-MM-DDTHH:mm:ssZ’ te worden gestuurd. |
endTime | Eind datum van de geselecteerde periode. De datum dient in de format ‘YYYY-MM-DDTHH:mm:ssZ’ te worden gestuurd. |
prefixes | Hiermee worden de geselecteerde locaties gespecificeerd. De API verwacht hier een lijst met een of meerdere prefixes (deel van locatie ID). Een prefix moet minimaal; 3 karakters lang zijn. |
HTTP Methode
POST
URL
https://dexter.ndwcloud.nu/api/explore/bicycle-data/geo
Request
Header
Er moet een Authorization header worden meegestuurd met daarin een OAuth token. Zie paragraaf authenticatie voor details.
Body
De body dient een start/eind tijd te bevatten en een geografische selectie van locaties. Dit laatste kan door een gebied te specificeren in de vorm van een polygoon in GeoJSON
formaat. Het is middels diverse tools mogelijk om een GeoJSON polygoon te tekenen. Zie bijvoorbeeld: https://geojson.io.
Let op dat de start- en eind tijd in Zulu tijd zijn. Dat heeft met de interne opslag in de database te maken. Binnen Dexter vertaalt de frontend de Nederlandse tijd die de gebruiker
opgeeft naar de Zulu tijd en terug, maar bij gebruik van de API moet de aanvrager deze actie zelf uitvoeren.
Veldnaam | Beschrijving |
---|---|
startTime | Startdatum van de geselecteerde periode. De datum dient in de format ‘YYYY-MM-DDTHH:mm:ssZ’ te worden gestuurd. |
endTime | Eind datum van de geselecteerde periode. De datum dient in de format ‘YYYY-MM-DDTHH:mm:ssZ’ te worden gestuurd. |
locationPolygoon | Hiermee wordt een gebied opgegeven met fiets meetlocaties in de vorm van een GeoJSON polygon. |
Na uitvoer van een request op een van de fiets data endpoints volgt onderstaande response.
Response
400 Response – Bad Request
De client heeft een verzoek verzonden dat niet aan de specificatie voldoet. De body van de response bevat informatie over de aard van de fout. Dit kan een syntactische fout aan de
kant van de client zijn maar het kan ook voorkomen dat de server het verzoekt weigert omdat het niet aan meer inhoudelijke validaties voldoet. Bijvoorbeeld: er worden te veel
locaties opgevraagd of er is een ongeldige prefix/polygoon opgegeven waarvoor geen locaties bestaan.
500 Response – Internal Server Error
Het verzoek is niet succesvol verwerkt vanwege een technisch probleem of beperking.
De body van de response kan informatie bevatten over de aard van de fout.
Als u vragen heeft over deze API en het gebruik ervan, dan kunt u contact opnemen met de servicedesk van NDW (mail@servicedeskndw.nu)
200 Response - OK
Een 200 response code als antwoord geeft aan dat de request succesvol is en dat de metingen van fiets data met succes zijn opgehaald. Als er een leeg antwoord volgt zijn er
geen meetgegevens gevonden. De body heeft standaard het content-type application/json.
De response is een lijst met objecten met metingen per locatie en uur. Zie onderstaande tabel voor specificatie van deze objecten.
Veldnaam | Beschrijving |
---|---|
locationId | ID van de opgevraagde locatie. |
measurementHour | Het uur van de meting. De measurementHour wordt in de format ‘YYYY-MM-DDTHH:mm:ssZ’ geleverd. De minuten en secondes hier zullen altijd 00:00 zijn gezien het uuraggregaten betreft. |
measuredValuesFull | Object waarin de metingen worden geleverd verdeeld in 4 categorieën met de daarbij behorende subcategorieën. |
HTTP Methode
GET
URL
https://dexter.ndwcloud.nu/api/gis/bicycle-data/complete
Request
Header
Er moet een Authorization header worden meegestuurd met daarin een OAuth token. Zie paragraaf authenticatie voor details.
Body
n.v.t
Response
500 Response – Internal Server Error
Het verzoek is niet succesvol verwerkt vanwege een technisch probleem of beperking.
De body van de response kan informatie bevatten over de aard van de fout.
Als u vragen heeft over deze API en het gebruik ervan, dan kunt u contact opnemen met de servicedesk van NDW (mail@servicedeskndw.nu)
200 Response - OK
Een 200 response code als antwoord geeft aan dat de request succesvol is en dat de geografische gegevens met succes zijn opgehaald. De body heeft standaard het contenttype application/json.
Het response bevat GeoJSON met daarin de coördinaten van de fiets meetlocaties. De coördinaten zijn in WGS84 formaat.
Onderstaand een voorbeeld van (een deel van) de response body:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"contractor": "ARS",
"authorityId": "PLB03",
"aliases": [],
"licenseCategory": "pddl",
"bearing": 180,
"authority": "Provincie Limburg",
"name": "N276 van Allee naar Doctor Nolenslaan (2 Ri.)",
"validUntil": null,
"locationType": "PERMANENT",
id": "PLB03_158_P",
"validFrom": "2020-11-30T00:00:00Z",
"equipmentType": "lus"
},
"geometry": {
"type": "Point",
"coordinates": [
5.8548012,
51.0205956
]
},
"id": "2751"
},
{
"type": "Feature",
"properties": {
"contractor": "Telwerk",
"authorityId": "PGL04",
"aliases": [],
"licenseCategory": "PDDL",
"bearing": 96,
"authority": "Provincie Gelderland",
"name": "Zuider Parallelweg (Velp), gemengd verkeer",
"validUntil": null,
"locationType": "PERIODIC",
"id": "PGL04_4_en_4a",
"validFrom": "2017-09-01T22:00:00Z",
"equipmentType": "multiplePneumatic"
},
"geometry": {
"type": "Point",
"coordinates": [
5.96909,
51.99375
]
},
"id": "1110"
},
{
"type": "Feature",
……………
}
]
}