Zakelijk

Vertrektijden API aanvullende documentatie

Inleiding 9292 Vertrektijden API

Met de Vertrektijden API kan je in heel Nederland haltes en daaraan verbonden openbaar vervoerdiensten vinden. Niet alleen regulier openbaar vervoer, maar ook (indien aangegeven in het request) flexibel openbaar vervoer. De API is bedoeld om gebruikt te doen voor het leveren van informatie aan Apps, websites of content providers die op een flexibele manier deze informatie willen aanbieden aan gebruikers.

Bij een typisch gebruik wordt eerst op basis van een geografische positie of een aantal zoektermen een of meer haltes bepaald. Na een eventuele selectie van een of meerdere haltes wordt daarna vertrekinformatie opgevraagd in een apart request dat meerdere keren herhaald wordt als de sessie met de gebruiker voortduurt en de vertrekinformatie inmiddels gewijzigd kan zijn. Een typisch gebruik is om dit bijv. elke minuut te verversen omdat voertuigen aangekomen en vertrokken kunnen zijn in die tijd.

Zowel bij het zoeken naar haltes als bij het opvragen van vertrekinformatie kan een groot aantal parameters meegegeven worden waarmee de resultaten specifieker gemaakt kunnen worden of de gegevens in het gewenste formaat worden geleverd. Hieronder volgt een globale beschrijving van de parameters. Voor de meest exacte definitie wordt verwezen naar de Swaggerdocumentatie die te vinden is op https://vertrektijden-api.9292.nl.

De Swagger documentatie bestaat uit 3 gedeeltes:

  1. Voorbeelden (Examples). Dit zijn werkende voorbeelden van requests die direct informatie leveren zonder kennis van de parameterisering. Er zijn beperkte mogelijkheden om de parameters aan te passen om het effect er van te kunnen onderzoeken. De voorbeelden geven niet alle mogelijkheden van requests weer en zijn bedoeld om de werking van de API te doorgronden, niet om gebruikt te worden in een echte toepassing.
  2. Haltes (StopPlaces). Hiermee kunnen haltes worden opgezocht (de eerste 3 opties) of van eerder gevonden haltes opnieuw de gegevens worden opgehaald (de laatste optie).
  3. Passages (StopVisits). Met behulp van een lijst van halte-identificaties kan vertrekinformatie opgevraagd worden. Dit is normaliter het meest gebruikte request waarbij bijv. iedere minuut opnieuw de actuele vertrekinformatie opgehaald wordt zo lang die getoond wordt aan een gebruiker.

 

In het algemeen zullen objecten en attributen alleen voorkomen in de response als ze een waarde hebben. Als er bijv. geen meldingen zijn bij een halte of vertrektijd, dan zijn deze objecten afwezig en is de lijststructuur waarin ze kunnen voorkomen ook afwezig. Hetzelfde geldt voor attributen. Zo kan er bij een vertrektijd een gewijzigd vertrekplatform zijn, maar in veel gevallen is dat niet zo en wordt het attribuut weggelaten uit de response.

Parameters bij het zoeken naar haltes

Parameter

Betekenis

Projection

Specificeert de projectie van de coordinaten die in het request zijn opgenomen en ook die in de response. Mogelijke waardes: WGS84 en RD. Default is WGS84.

...Latitude

Bij WGS84-projecties: de latitude coordinaat. Bij RD-projectie: de Y-coordinaat.

...Longitude

Bij WGS84-projecties: de longitude coordinaat. Bij RD-projectie: de X-coordinaat.

Radius

Bij opvragen van haltes in een cirkel: de straal van de cirkel in meters

Query

Bij opvragen van haltes met zoektermen: een lijst van trefwoorden gescheiden door spaties

Language

Bepaalt de taal van een aantal vertaalbare woorden in de response. Mogelijke waardes: NL of EN. Default is NL.

FlexOV

Bepaalt of naast haltes voor het reguliere OV ook haltes voor flexibel OV worden meegeleverd. Default is false.

StopType

Het soort halte dat geleverd moet worden. Mogelijke waardes: Cluster, Physical, Quay en StopPlace. Default is Cluster.

IncludeParentStop

Levert bij fysieke haltes ook de bijbehorende clusterhalte op en bij quay-haltes de bijbehorende StopPlace-halte. Default is false.

IncludePhysicalStops

Levert de identificaties van gerelateerde fysieke haltes op. Bij fysieke haltes worden de identificaties van quay-haltes geleverd en bij quay-haltes de identificaties van fysieke haltes. Default is false.

Details

Als de halte-informatie alleen bedoeld is om een kaart met haltes te kunnen weergeven, kan met de waarde false een minimale hoeveelheid gegevens per halte worden opgevraagd. Dit maakt het mogelijk om meer haltes op te vragen met minder details per halte. Default is true oftewel: alle details

Resultaten na zoeken naar haltes

De response bevat een aantal objecten die hier kort worden toegelicht. Voor meer details wordt verwezen naar de Swaggerdocumentatie (href="https://vertrektijden-api.9292.nl" target="_blank">https://vertrektijden-api.9292.nl).

Object

Inhoud en betekenis

Stop

Bevat de identificerende gegevens en een indicatie of er gedurende de huidige dag vervoerdiensten zijn op deze halte. Alle andere halte-objecten hieronder zijn onderdeel van dit object.

Coordinates

De geografische coordinaten van de halte. De parameter in het request bepaalt welke projectie gebruikt wordt: WGS84 of RD. Alleen de coordinaten van de gevraagde projectie worden geleverd.

StopAttribute

Deze attributen geven de toegankelijkheid van de halte aan voor minder validen.

Line

Algemene en identificerende gegevens over een lijn indien de dienst op de huidige dag minimaal 1 keer wordt uitgevoerd.

Disruption

Dit kunnen zowel geplande als ongeplande verstoringen van de normale dienstregeling op een halte zijn. Een vervoerder kan in principe op ieder moment een ongeplande verstoring melden.

Parameters bij het opvragen van vertrekinformatie

Parameter

Betekenis

StartTime

Begin van de periode waarvoor vertrekinformatie wordt gevraagd. In plaats van een datum/tijd kan ook de waarde NOW gekozen worden. Het waardebereik is vanaf het begin van de huidige dag tot enkele dagen in de toekomst. Default is NOW. Indien het datum/tijd formaat niet wordt herkend, dan wordt de waarde NOW aangenomen.

PreviewInterval

De duur van de periode waarvoor vertrekinformatie wordt gevraagd. De waarde is in minuten; de maximale waarde is 1440 (24 uur). Default is 60.

MaximumStopVisits

Het maximum aantal vertrektijden dat in de response teruggeleverd mag worden. Als het maximum bereikt is en er zijn meer vertrektijden in de gespecificeerde periode, dan wordt dit aangegeven in de response (zie ErrorMessage).

StopCodes

Een lijst van identificaties van de haltes. De codes zijn verschillend voor verschillende types haltes, ook al duiden ze dezelfde fysieke halte aan.

StopType

Het soort halte waarvan de identificaties worden gespecificeerd. Mogelijke waardes: Cluster, Physical, Quay en StopPlace. Default is Cluster.

LinePlanningNumber

Het lijnplanningsnummer is de identificatie van een lijn zoals die wordt gehanteerd in de planning van een dienstregeling. Dit nummer wordt geleverd bij haltes en vertrektijden en kan gebruikt worden om de vertrekinformatie te beperken tot specifieke lijnen. Meerdere lijnplanningsnummers kunnen worden gebruikt voor het filter.

OperatorName

Deze parameter beperkt vertrekinformatie tot de genoemde vervoerder(s). Meerdere namen zijn mogelijk.

TransportType

Deze parameter beperkt de lijst tot de genoemde typen vervoer. Meerdere typen zijn mogelijk.

Projection

Specificeert de projectie van de coordinaten die in het request zijn opgenomen en ook die in de response. Mogelijke waardes: WGS84 en RD. Default is WGS84.

Language

Bepaalt de taal van een aantal vertaalbare woorden in de response. Mogelijke waardes: NL of EN. Default is NL.

FlexOV

Bepaalt of naast vertrekinformatie voor het reguliere OV ook vertrekinformatie voor flexibel OV worden meegeleverd. Default is false.

PassageType

Specificeert of vertrek- of aankomstinformatie is gewenst of allebei. Default is vertrekinformatie.

Resultaten na het opvragen van vertrekinformatie

De response bevat naast de onderstaande objecten een paar gegevens van het request en het aantal vertrektijden. Voor meer details wordt verwezen naar de Swaggerdocumentatie (href="https://vertrektijden-api.9292.nl" target="_blank">https://vertrektijden-api.9292.nl).

Object

Inhoud en betekenis

VisitStop

Bevat identificerende gegevens van de halte.

Coordinates

De halte-coordinaten. Zie hierboven.

StopAttribute

De toegankelijkheid van de halte.

Visit

Dit object representeert het bezoek van vervoerdersdienst aan een halte en bevat gegevens van de vervoersdienst die voor de hele rit relevant zijn.

DepartureGroup

Dit object bevat gegevens die specifiek voor het vertrek van een vervoersdienst relevant zijn, zoals vertrektijd, vertrekplatform of -spoor, drukte-indicatie en wijzigingen t.o.v. van de geplande dienstregeling. De drukte-indicatie is een cijfer van 0 tot 5 met de betekenis:
0 - Onbekend
1 - Leeg
2 - Rustig
3 - Gemiddeld
4 - Druk
5 - Vol

ArrivalGroup

Analoog aan de DepartureGroup bevat dit object de gegevens die relevant zijn voor de aankomst van een vervoersdienst bij een halte. Bij een ArrivalGroup wordt geen drukte-indicatie geleverd.

Notice

Dit zijn meldingen van vervoerders die in de dienstregeling zijn opgenomen, bijv. contactgegevens voor het reserveren van diensten of wijzigingen die voor een langere periode gelden.

JourneyAttribute

Dit geeft de toegankelijkheid van het voertuig voor minder validen aan. Dit kan afwijken van de toegankelijkheid van de halte.

Disruption

Dit zijn meldingen van vervoerders over wijzigingen of verstoringen die buiten de dienstregeling optreden. Vaak gaat het om grootschalige of ingrijpende verstoringen met adviezen hoe verder te reizen.

Errors en waarschuwingen

Indien er errors of waarschuwingen optreden tijdens de verwerking van een request, dan kunnen er een of meerdere ErrorMessages zijn opgenomen in de response. ErrorMessages kunnen naast andere resultaten geleverd worden, bijv. als er meerdere halte-identificaties in het request worden gespecificeerd en slechts een daarvan niet gevonden kan worden. In dat geval wordt voor deze onbekende identificatie een foutmelding gegeven, maar worden de resultaten van de andere haltes gewoon geleverd. Omdat er in principe ook bij fouten in de verwerking resultaten geleverd kunnen worden, is de HTTP-status van de response in het algemeen OK (200), ook bij optredende fouten, bijv. als er geen resultaten gevonden worden of een identificatie niet bekend is. Alleen bij meer technische fouten kunnen andere HTTP-statussen bij een response worden opgeleverd, bijv. bij verkeerde parameter waardes.

Object

Inhoud en betekenis

ErrorMessage

Dit object wordt alleen geleverd indien er fouten tijdens de verwerking worden geconstateerd, bijv. een identificatie van een halte die niet (meer) bestaat of waarschuwingen, bijv. als er de resultaten zijn begrensd door het maximum aantal haltes.

Gebruiksvoorwaarden

Gebruik van de 9292 Vertrektijden API is alleen toegestaan met uitdrukkelijke toestemming van 9292.

 

9292 Logo

Het is verplicht het 9292 Logo te tonen bij gebruik van detailinformatie. 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 link is het 9292 Logo op te halen:

 

Release notes

Software versie

Opmerking

21-06-2021 v1.2.0

  • Eerste publieke release van de 9292 Vertrektijden API

23-08-2021 v1.3.0

  • Uitbreiding met overstap-informatie
  • Links tussen Quays en Fysieke haltes kunnen worden opgevraagd

23-11-2021 v1.4.0

  • Verdere uitbreiding voor overstap-services
  • Verbetering van de Swaggerdocumentatie

21-12-2021 v1.5.0

  • Integratie van Vertrekwijzer in de Vertrektijden API
  • Redirecties van HTTP naar HTTPS voor Vertrekwijzer-requests

21-01-2022 v1.6.0

  • Verdere uitbreiding van overstap-services
  • Nieuwe layout voor webversie van de Vertrekwijzer

03-03-2022 v1.7.0

  • Uitbreiding van Vertrekwijzer met drukte-indicatie
  • Data-versie van de Vertrekwijzer kan nu JSON leveren

29-08-2022 v1.8.0

  • Uitbreiding van vertrektijden met meerdere datum/tijd formaten

05-09-2022 v1.8.1

  • Verbetering van de logging; bij problemen kunnen alle request-parameters tijdelijk vastgelegd worden

07-11-2022 v1.8.2

  • Deny-list voor tokens i.p.v. allow-list voor snellere aansluiting van nieuwe afnemers

09-01-2023 v1.8.3

  • Verbeterde health-check monitoring voor het eerder en automatisch constateren van problemen, bijv. van ongebruikelijk grote aantallen verworpen berichten

06-03-2023 v1.8.4

  • Vertrektijden van treinen uit DVS worden direct in de API voor een snellere en preciezere matching met de ritnummers van treinen

03-04-2023 v1.8.5

  • Aankomsttijden van treinen uit DAS worden direct in de API voor een snellere en preciezere matching met de ritnummers van treinen

08-08-2023 v1.8.6

  • Uitbreiding t.b.v. nieuwe vertrekwijzers om externe IP-adressen automatisch vast te leggen gedurende een aanloopperiode

06-12-2023 v1.8.7

  • Div. technische changes i.v.m. verandering van host

10-01-2024 v1.8.8

  • Diverse bugfixes, waaronder: vertrektijden na middernacht worden weer volledig getoond

v1.9.0 - 13-05-2024

  • Diverse interne changes en verbeteringen

v1.9.1 - 01-10-2024

  • Nieuwe versie van de overstapinformatie service (v2)
  • Verbetering matching van DVS berichten
  • Uitbreiding voertuigposities response
  • Diverse bugfixes

API Beveiliging

De API kan alleen via HTTPS benaderd worden en bij ieder request moet er een token meegestuurd worden dat van 9292 is ontvangen voor het gebruik van deze API. Ditzelfde token kan ook gebruikt worden in de Swagger-pagina voor het interactief gebruik van de Vertrektijden API. Aan belangstellenden kan een tijdelijk token verstrekt worden om te experimenteren met de werking van de Vertrektijden API.

Header Key

Waarde

Authorization

...het geleverde token...

Accept

Application/JSON

Content-Type

charset=utf-8