Zakelijk

Dienstregeling API aanvullende documentatie

Inleiding 9292 Dienstregeling API

Met de Dienstregeling API kunnen gegevens uit de dienstregeling van het openbaar vervoerder voor heel Nederland worden opgevraagd. Dit kan op een globaal niveau voor bijv. alle lijnen voor een enkele vervoerder, maar ook op detailniveau voor bijv. een rit die op een bepaald tijdstip een bepaalde halte passeert. De API is bedoeld om gebruikt te worden voor het leveren van informatie aan Apps, websites of content providers die deze informatie rechtstreeks of ter aanvulling van andere reisinformatie willen aanbieden aan gebruikers.

Hieronder volgt een beschrijving van de gegevens die opgevraagd kunnen worden. 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 lijn of halte, 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.

Dienstregelingsgegevens van een vervoerder

Van iedere openbaar vervoerder kan opgevraagd worden welke lijnen er gereden worden op enig moment in de gepubliceerde dienstregeling. Dat is dus onafhankelijk van welke dagen waarop die lijnen gereden worden. Per lijn worden de volgende gegevens geleverd:

  • DataOwnerCode - de standaard lettercode waarmee vervoerders worden afgekort of aangeduid.
  • OperatorID - (optioneel) de numerieke code waarmee vervoerders worden aangeduid.
  • Per lijn de volgende gegevens:
    • LijnPlanningsNummer (identificatie van de lijn in de dienstregeling)
    • Publieke lijnnummer (zoals getoond aan reizigers)
    • Mogelijke rij-richtingen
    • Mogelijke modaliteiten:
      • Transport type (bus, tram, trein, ...)
      • Productformule (Sprinter, Q-liner, Belbus, ...)

 

Dienstregelingsgegevens per lijn

In een request voor lijn-informatie wordt een lijn gespecificeerd door de combinatie van:

  • DataOwnerCode van de uitvoerende vervoerder.
  • LijnPlanningsNummer (systeemlijnnummer)
Per lijn worden de volgende gegevens geleverd:
  • DataOwnerCode
  • OperatorID
  • LijnPlanningsNummer (identificatie in de planning)
  • Publieke lijnnummer (zoals getoond aan reizigers)
  • De beschrijving van de lijn
  • Kleurcodes van de lijn bij weergave in vertrekstaten
  • Mogelijke rij-richtingen
  • Mogelijke modaliteiten:
    • Transport type (bus, tram, trein, ...)
    • Productformule (Sprinter, Q-liner, Belbus, ...)
  • De dagen waarop er diensten voor de lijn worden uitgevoerd
  • Alle mogelijke routes waarbij per route:
    • De rijrichting
    • De geografische route over de weg of het spoor
    • De reeks haltes die gepasseerd worden met per halte:
      • Identificaties van de halte
      • Naam en plaats van de halte
      • Toegankelijkheid van de halte voor minder validen
      • De geografische coordinaten van de halte (in WGS84 of RDM projectie)
  • Berichten van vervoerders over geplande en ongeplande verstoringen of veranderingen

 

Dienstregelingsgegevens voor ritten

Een of meer ritten binnen een lijn kunnen worden gespecificeerd in een request door de combinatie van:

  • DataOwnerCode van de uitvoerende vervoerder.
  • LijnPlanningsNummer
  • Rijrichting (optioneel)
  • Datum van de uitvoering
In het algemeen levert dit meerdere ritten op die op de gevraagde dag voor die lijn gereden worden. Per rit worden de volgende gegevens geleverd, naast de lijngegevens die hierboven zijn beschreven:
  • JourneyNumber (identificatie van de rit)
  • Rijrichting
  • Status (gepland, op tijd, vertraagd, e.d.)
  • Start- en eindtijd van de rit
  • Geplande en evt. gewijzigde bestemming
  • Toegankelijkheid van het voertuig voor minder validen
  • Meldingen van de vervoerder over de rit of lijn die in de dienstregeling zijn opgenomen, bijv. geplande veranderingen of contactgegevens voor aanvragen
  • De route over de weg of het spoor
  • De positie van het voertuig (indien beschikbaar)
  • De reeks haltes waar wordt gestopt en per halte:
    • Identificaties van de halte
    • Naam en plaats van de halte
    • Toegankelijkheid van de halte voor minder validen
    • De geografische coordinaten van de halte (in WGS84 of RDM)
    • Meldingen van de vervoerder over de halte (bijv. een tijdelijke verplaatsing van de halte)
    • Geplande aankomst- en vertrektijden
    • Verwachte aankomst- en vertrektijden, indien afwijkend van gepland
    • Geplande bestemming (dit kan veranderen bij een halte)
    • Aangepaste bestemming (bijv. bij verstoringen)
    • Drukte-indicatie bij instappen. Dit is als volgt gecodeerd:
      0 - Onbekend
      1 - Leeg
      2 - Rustig
      3 - Gemiddeld
      4 - Druk
      5 - Vol
    • Gepland vertrekperron of -spoor
    • Gewijzigd vertrekperron of -spoor
    • Status (gepland, vertraagd, te vroeg, vervallen, ...)
    • In-/uitstapmogelijkheid
Een enkele rit kan ook opgevraagd worden i.p.v. alle ritten van een lijn voor een hele dag en rijrichting. Hiervoor zijn een van de twee volgende aanvullende gegevens nodig:
  1. De identificatie van de rit (JourneyNmber). Dit gegeven kan uit ander APIs verkregen worden, bijv. de Vertrektijden API, waar dit bij iedere vertrektijd wordt meegeleverd
    OF
  2. Een combinatie van halte-code en vertrektijd. Deze gegevens kunnen afkomstig zijn uit andere APIs, waarbij de Dienstregeling API gebruikt wordt om meer informatie van een geselecteerde rit op te vragen, bijv. de volgende haltes, de gevolgde route en de voertuigpositie.

 

Taal en projecties

Bij ieder request kan een taalkeuze worden aangegeven (Nederlands of Engels) voor vertaalbare woorden in het resultaat. Namen van haltes, vervoerders of plaatsen worden niet vertaald i.v.m. de herkenbaarheid onderweg. In het request kan worden aangegeven of de geleverde geografische coordinaten in WGS84 (latitude/longitude) of RDM (RijksDriehoekMeting - X/Y) geprojecteerd moeten worden.

Errors en waarschuwingen

Indien er een error of waarschuwing optreedt tijdens de verwerking van een request, dan kan er een ErrorMessage zijn opgenomen in de response. Een ErrorMessage wordt normaliter geleverd met een tekstuele aanduiding van het probleem, bijv. dat een identificatie onbekend is. De HTTP-status van de response in het algemeen OK (200) bij te verwachten optredende situaties, bijv. als er geen data wordt gevonden bij een onbekende identificatie. Alleen bij meer technische en onverwachte fouten kunnen andere HTTP-statussen bij een response worden opgeleverd, bijv. bij een verkeerde parameter waarde of een protocolfout.

Object

Inhoud en betekenis

ErrorMessage

Dit object wordt alleen geleverd indien er fouten tijdens de verwerking worden geconstateerd, bijv. een identificatie van een lijn die niet (meer) bestaat.

Gebruiksvoorwaarden

Gebruik van de 9292 Dienstregeling 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

01-10-2021 v1.0.0

  • Eerste publieke release van de 9292 Dienstregeling API voor het opvragen van gedetailleerde ritgegevens

22-10-2021 v1.1.0

  • Uitbreiding met de EndPoints voor meerdere ritten en lijnen

14-02-2022 v1.2.0

  • Uitbreiding met actuele voertuigposities

 

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 Dienstregeling API. Aan belangstellenden kan een tijdelijk token verstrekt worden om te experimenteren met de werking van de Dienstregeling API.

Header Key

Waarde

Authorization

...het geleverde token...

Accept

Application/JSON

Content-Type

charset=utf-8