Fiets data API

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:

Data endpoints: om de metingen voor fiets (geaggregeerd naar uren) op te halen voor een selectie van locaties. Selectie kan op basis van locatie ID’s, prefixen of geografisch middels een polygoon. Hiervoor zijn separate endpoints beschikbaar.
GIS endpoint: om geografische informatie over alle fiets meetlocaties op te halen

Authenticatie

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=" -d "password=" -d "client_id=dexter" -d "grant_type=password" https://keycloak.ndwcloud.nu/auth/realms/ndw/protocol/openid-connect/token

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

Fiets data endpoint – locatie ID’s

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.

Voorbeeld body:
{
  "startTime": "2021-05-26T22:00:00.000Z",
  "endTime": "2021-06-03T21:59:59.000Z",
  "locations": [
    "GAP01_ARN_501",
    “GAL01_001”
  ]
}
Response
Zie paragraaf “fiets data response”.

Fiets data endpoint – prefixen

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.

Voorbeeld body:
{
  "startTime": "2021-05-26T22:00:00.000Z",
  "endTime": "2021-06-03T21:59:59.000Z",
  "prefixes": [
    "GAP",
    “GAL”
  ]
}

Response
Zie paragraaf “fiets data response”.

Fiets data endpoint – polygoon

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.

Voorbeeld body:
{
  "startTime": "2021-05-26T22:00:00.000Z",
  "endTime": "2021-06-03T21:59:59.000Z",
  "locationPolygon": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          5.2727508544921875,
          51.640819959168475
        ],
        [
          5.3565216064453125,
          51.640819959168475
        ],
        [
          5.3565216064453125,
          51.677664778834455
        ],
        [
          5.2727508544921875,
          51.677664778834455
        ],
        [
          5.2727508544921875,
          51.640819959168475
        ]
      ]
    ]
  }
}

Response
Zie paragraaf “fiets data response”.

Fiets data response

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.

Onderstaand een voorbeeld van (een deel van) de response body:
[
  {
    "locationId": "GAP01_ARN_501",
    "measurementHour": "2021-04-14T00:00:00Z",
    "measuredValuesFull": {
      "SpeedRange": {
        "count_to": [
        {
          "ALL_SPEEDS": 0
        }
      ],
      "count_from": [
        {
          "ALL_SPEEDS": 1
        }
      ],
      "both_directions": [
        {
          "ALL_SPEEDS": 1
        }
      ]
    },
    "LegalVehicleClassification": {
      "count_to": [
        {
          "ALL_LEGAL_VEHICLES": 0
        }
      ],
      "count_from": [
        {
          "ALL_LEGAL_VEHICLES": 1
        }
      ],
      "both_directions": [
        {
          "ALL_LEGAL_VEHICLES": 1
        }
      ]
    },
    "BicycleWidthRange": {
      "count_to": [
        {
          "ALL_WIDTHS": 0
        }
      ],
      "count_from": [
        {
          "ALL_WIDTHS": 1
        }
      ],
      "both_directions": [
        {
          "ALL_WIDTHS": 1
        }
      ]
    },
    "BicyclePropulsionType": {
      "count_to": [
        {
          "ALL_PROPULSIONS": 0
        }
      ],
      "count_from": [
        {
          "ALL_PROPULSIONS": 1
        }
      ],
      "both_directions": [
        {
          "ALL_PROPULSIONS": 1
        }
      ]
    }
  }
},
{
  "locationId": "GAP01_ARN_501",
    "measurementHour": "2021-04-14T01:00:00Z",
    ……………
  {
  "locationId": "GAP01_ARN_501",
    "measurementHour": "2021-04-14T02:00:00Z",
    ……………
  },
]

Fiets GIS endpoint

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",
    ……………
    }
  ]
}