Plannen met de fiets of scooter is standaard beschikbaar in de 9292 Reisadvies API. Door gebruik te maken van het invoerveld ‘FirstMile of LastMile’ met de waarde ‘PrivateBicycle’ of ‘PrivateElectricBicycle’ geeft u de reiziger een passend OV-reisadvies met eigen fiets of elektrische fiets naar een trein-, bus-, tram- of veer-fietsoverstappunt. Met de waarde ‘PrivateMoped’ kunt u de reiziger een OV-reisadvies met de scooter i.p.v. de fiets geven.
De 9292 Reisadvies API ondersteunt ook het gebruik van huurfietsen en huurscooters. Dit wordt aangegeven door het invoerveld ‘LastMile’ in te vullen met de waarde ‘PublicBicycle’, ‘PublicElectricBicycle’ of ‘PublicMoped’. Hiermee wordt een OV-reisadvies gegeven met een loop-leg naar een passende verhuurlocatie.
De planner kijkt voor het reisadvies niet naar openingstijden van fietslocaties of hoeveel fietsen er zijn, de planner geeft puur de meest optimale reis naar een cluster waarvan we hebben gezegd dat dit een goede overstaplocatie voor fietsen is (omdat er een leverancier van fietsen binnen bereik van het cluster een locatie heeft bijvoorbeeld).
Informatie over de actuele hoeveelheid beschikbare fietsen is realtime (maximaal een paar minuten oud ten opzichte van de aanleverende bron) beschikbaar in de 9292 Locaties API. Deze API biedt onder andere informatie over verhuurlocaties per aankomst- of vertreklocatie en de details van een verhuurlocatie (o.a. het aantal beschikbare voertuigen en openingstijden).
Deze korte handleiding beschrijft hoe u de interface van de 9292 Locaties API kunt gebruiken om de OV-routeplanner data aan te vullen met verhuurlocaties op uw website of andere toepassing. Dit is een aanvulling op de online open api (Swagger) documentatie van deze API die te vinden is op https://locaties-api.9292.nl, waar ook verzoeken kunnen worden uitgeprobeerd (als u beschikt over een 9292 Reisadvies API token).
Als basis voor de 9292 Locaties API wordt JSON gebruikt. Kennis van WebAPI en JSON als ontwikkelaar is dan ook noodzakelijk om deze API te kunnen gebruiken.
Gebruik van de 9292 Locaties API is alleen toegestaan met uitdrukkelijke toestemming van 9292.
Het is verplicht het 9292 Logo te tonen bij gebruik van detailinformatie op een andere pagina dan het reisadvies. Het gaat hier om alleen het logo en geen tekst.
9292 geeft akkoord op plaatsing voor live gang binnen de productieomgeving. Dit om de uniformiteit te waarborgen.
Via de volgende URL is het 9292 Logo op te halen:
|
Software versie |
Opmerking |
|
22-09-2021 v2.1.3 |
|
|
24-01-2022 v2.1.5 |
|
|
03-03-2022 v2.1.7 |
|
| 07-09-2022 v3.0 |
Grote uitbreiding van de functionaliteit van de 9292 Locaties API:
|
|
02-01-2023 |
|
|
20-03-2023 v3.0.0.9 |
|
|
24-04-2023 |
|
De 9292 Locaties API is beveiligd en kan alleen aangeroepen worden als men in het bezit is van een door 9292 verstrekt ‘Token’ of wel APIKey. Dit ‘Token’ bestaat uit een serie tekens en letters die per Licentieovereenkomst wordt afgegeven en die de klant het recht geeft om requests aan de server van 9292 te doen.
Dit ‘Token’ is even geheim als uw gebruikersnaam en wachtwoord. Deel het met niemand.
9292 kan bij misbruik het ‘Token’ deactiveren.
Het toegangstoken ontvangt u per e-mail van de 9292 Servicedesk. Dit is uw identificatiecode. Met dit token kunt u gebruik maken van de aansluittestomgeving van de 9292 Locaties API. Wanneer u de implementatie heeft voltooid en 9292 uw dienst heeft getest, kunt u overgaan naar de productieomgeving. Hiervoor ontvangt u van de 9292 Servicedesk een nieuw token.
De aansluiting op de aansluittestomgeving blijft na overgang op de productieomgeving nog twee weken bestaan.
Het token moet in de header bij iedere aanroep worden meegestuurd. Hierbij een voorbeeld van de request header:
|
Header Key |
Value |
|
Authorization |
Token <MY_TOKEN> |
|
Accept |
Application/JSON |
|
Content-Type |
charset=utf-8 |
Let op:
De 9292 Locaties API ondersteunt alleen HTTPS verzoeken.
Er worden tokens meegestuurd die een betreffende afnemer kan identificeren. Daardoor kan er bij het aftappen van een HTTP stroom misbruik van het token worden gemaakt.
De Locatie API 2.0 heeft 2 endpoints, Facilities en Facility. Met beide kan informatie over verhuurlocaties en deelvoertuigen worden opgehaald, met het verschil dat ‘Facilities’ wordt gebruikt om meerdere verhuurlocaties op te halen die in de buurt liggen van een specifiek station/specifieke halte en ‘Facility’ wordt gebruikt om een specifieke locatie (opnieuw) op te halen op basis van de ‘FacilityId’ die beschikbaar is bij elke facility als de lijst van facilities is opgevraagd.
Facilities kunnen worden opgevraagd op basis van de Location Id behorend bij de leg die gaat over PublicBicycle/PublicMoped/PublicElectricBicycle in het reisadvies. Bijvoorbeeld ‘station-den-haag-centraal’ voor Den Haag Centraal in onderstaand stukje uit een 9292 Reisadvies Api verzoek.
|
Formaat |
Voorbeeld |
|
JSON |
{
...
"Location": {
"QuayCode": "",
"VisuallyAccessible": "Unknown",
"DisabledAccessible": "Unknown",
"Id": "station-den-haag-centraal",
"StationAbbreviation": "gvc"
"DisplayName": "Den Haag Centraal"
"Place": {
etc...
|
Het JSON verzoek dat in de body moet worden verstuurd om faciliteiten op te vragen via het /Facilies/ endpoint ziet er als volgt uit:
|
Formaat |
Voorbeeld |
|
JSON |
{
"clusterId": "station-den-haag-centraal",
"getAssets": false,
"modality": [
"PublicBicycle"
],
"modalityClass": [
"Rental"
],
"getServiceArea": false,
"date": "2021-08-30T08:48:00",
"language": "Dutch"
}
|
De veldnamen hebben de volgende betekenis:
|
Veldnaam |
Vulling |
Omschrijving |
|
ClusterId |
String |
Id van een locatie in een leg van de Reisadvies Api. |
|
GetAssets |
True/false |
Geef ook de individuele deelvoertuiglocaties mee (geldt alleen bij zogenaamde ‘free floating’ deelvoertuig systemen). |
|
Modality |
Array van modaliteiten |
Geef een specifiek type deelvoertuig zoals PublicBicycle, PublicMoped, PublicElectricBicycle. Meerdere opties kunnen worden opgevraagd of alle mogelijkheden worden teruggegeven indien het modality veld leeg is. |
|
ModalityClass |
Array van modaliteitstypen |
Geef huurlocaties terug (alleen ‘Rental’ is beschikbaar). |
|
GetServiceArea |
True/false |
Geef servicegebieden terug behorend bij de locatie. Dit is een lijst van coördinaten die zo’n gebied vormen. |
|
Date |
Datum |
Datum van het reisadvies, hiermee wordt rekening gehouden om te tonen of een locatie open of dicht is. |
|
Language |
Dutch/English |
Inhoudelijke informatie kan Engels of Nederlands worden getoond (voor zover aanwezig). |
Het antwoord ziet er als volgt uit (zie de verdere technische documentatie op https://locaties-api.9292.nl voor het volledige object met alle velden):
|
Formaat |
Voorbeeld |
|
JSON |
{
"facilityId": "HTM-Fiets-24fa4849-2a83-40e1-8a6b-6852f937aeaa",
"externalFacilityId": "24fa4849-2a83-40e1-8a6b-6852f937aeaa",
"name": "Fietsenstalling CS (Nieuw)",
"typeOfFacility": "Virtualstation",
"region": null,
"staffed": false,
"openingHourSummary": "Nu open: 00:00 - 23:59",
"openNow": true,
"Provider" {
"brand": "HTM Fiets",
"operator": null,
"url": "https://www.htm.nl/klantenservice",
"phoneNumber": "0900-4862453",
"email": "deelfiets@htm.nl",
"conditions": "Lees de informatie op htm.nl/htm-fiets",
"conditionsUrl": "https://www.htm.nl/htm-fiets",
etc...
|
Op basis van bovenstaand antwoord kan de faciliteit direct worden opgehaald via het /Facility/ endpoint door in het verzoek daarvoor de FacilityId "HTM-Fiets-24fa4849-2a83-40e1-8a6b-6852f937aeaa" op te nemen.
De bij 'NumberOfAssets' en 'NumberOfAssetsAvailable' getoonde aantallen worden rond de 1 á 2 minuten bijgewerkt met realtime informatie. Hetzelfde geldt voor de actuele locatie van voertuigen indien een verzoek wordt gestuurd met 'GetAssets' op true.
De locaties worden in een specifieke volgorde teruggegeven:
Of er Nederlandse of Engelse informatie kan worden teruggegeven is afhankelijk van de beschikbare data bij leveranciers. In sommige omstandigheden zal (Dutch only) voor de tekst worden geplaatst indien alleen een Nederlandse tekst beschikbaar is en Engels wordt gevraagd.