Zakelijk

Reisadvies API aanvullende documentatie

Inleiding 9292 Reisadvies API

De 9292 Reisadvies API biedt de mogelijkheid om gebruik te maken van de planner engine van 9292 binnen een eigen website of app voor het geven van OV-reisadviezen van adres naar adres van al het openbaar vervoer in heel Nederland.

Deze handleiding beschrijft hoe u de interface van de 9292 Reisadvies API kunt gebruiken om op uw website of andere toepassing een OV-routeplanner aan uw klanten aan te bieden. Dit is een aanvulling op de online swaggerdocumentatie van ons product.

Als basis voor de 9292 Reisadvies API wordt XML of JSON gebruikt. Kennis van WebAPI als ontwikkelaar en XML of JSON is dan ook noodzakelijk om deze uitvoering te kunnen installeren.

Gebruiksvoorwaarden

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

 

9292 Logo

Het is verplicht het 9292 Logo te tonen. 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:

 

Release notes

Software versie

Documentatie versie

Opmerking

11-05-2020
v2.6.1

20-01-2020
v1.7.5

  • Plannen met de fiets en toegankelijk plannen zijn aan de 9292 Reisadvies API toegevoegd
  • Foutmeldingen bijgewerkt

24-09-2020
v2.7.1

01-09-2020
v1.7.6

  • Bezetting toegevoegd aan de 9292 Reisadvies API

08-12-2020
v2.7.2

15-10-2020
v1.7.7

  • Fietsafstand is vergroot van 20min. naar 30min.
  • CO2 gegevens bijgewerkt

22-03-2021
v2.8.0

23-03-2021
v1.7.8

  • Documentatie op basis van de OpenAPI 3 standaard
  • Betere zoekresultaten voor zoeken naar bestemmingen, o.a. betere matching met zoektermen, bij straatnamen met nummers erin en met huisnummers
  • Verstoringsberichten van verstoringen worden direct in het reisadvies getoond
  • Nieuwe modaliteiten om mee te plannen aan het begin en eind van de reis (first- en lastmile): huurfiets, elektrische (huur)fiets, (huur)scooter
  • Ondersteuning voor vervoer op aanvraag zoals Watertaxi Rotterdam
  • Vertalingen voor land-, provincie- en haltetype-namen
  • Modaliteit "taxi" toegevoegd aan de vergelijkingslijst van voertuigemissies
  • Standaard stallingstijd voor fietsen is verhoogd van 2min. naar 5min.
  • Diverse bugfixes

26-04-2021
v2.8.1

26-04-2021
v1.7.9

  • Betere zoekresultaten voor zoeken naar stations en haltes met samengestelde namen
  • Betere matching van drukte informatie aan journey legs
  • Verstoringsbericht model is uitgebreid om meer details over de aard van de verstoring te tonen
  • Diverse bugfixes

 

API Beveiliging

De 9292 Reisadvies 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.

Toegangstoken

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 Reisadvies 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/XML  (voor JSON gebruik "Application/JSON")

Content-Type

charset=utf-8

Let op:

De 9292 Reisadvies API ondersteund 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. Dit kan resulteren in een hogere telling in de statistieken en een hogere factuur.

 

Reisadvies API Basis Features

Geldigheidsdatum voor reisadviezen

De 9292 Reisadvies API maakt gebruik van gegevens die verouderen of wijzigen (o.a. dienstregelingen). Daarom kan alleen data gebruikt worden die binnen de geldigheidsduur valt. Zodra er een datum wordt gebruikt die buiten de geldigheidsdatum valt zal de 9292 Reisadvies API altijd een foutmelding (400 BadRequest) teruggeven.
De geldigheidsduur kan d.m.v. de Dataset endpoint worden opgevraagd.

Het opvragen van de Dataset wordt niet meegeteld als request voor de facturatie.

 

Locaties opvragen voor reisadviezen

Om een locatie op te vragen dient u binnen de 9292 Reisadvies API de Locations endpoint aan te roepen. Met een locatie request kunt u informatie opvragen over een station, plaats, straat, huisnummer, haltenaam of POI (Point Of Interest). Een locatie request zal 25 locaties teruggeven. De stations zullen eerst teruggegeven worden, daarna de bus-/tram-/metrohaltes, daarna de straatnamen, postcodes etc.
Deze Locations endpoint is geen autosuggest. Met behulp van de Locations endpoint kunt u wel zelf een autosuggest voor uw applicatie(s) ontwikkelen.

Het opvragen van een locatie wordt niet meegeteld als request voor de facturatie.

 

OV-reisadvies opvragen

Om een reisadvies op te vragen dient u de Journeys endpoint aan te roepen. Het opvragen van een OV-reisadvies geeft 9 responses terug. Dit zijn reizen rond het opgevraagde tijdstip. Dit aantal is niet instelbaar.
De vertrek-, via- en bestemmingslocatie in een OV-reisadvies request dient te corresponderen met de ‘Id’ van een locatie van de Location endpoint.

Attributen in het OV-reisadvies

Attributes zijn gegevens die door bijvoorbeeld NS worden meegestuurd met betrekking tot een reis(deel). Deze worden niet bij alle reizen getoond, alleen waar de informatie is toegevoegd aan het OV-reisadvies zal het element Attributes worden getoond.

Onderstaand tabel bevat een aantal voorbeelden van mogelijke attributen.

Attribuut Id

Attribuut waarde

Omschrijving/Opmerking

TWEE

alleen 2e klas

Aanduiding dat alleen 2de klas beschikbaar is voor een reis.

Dit komt maar op een aantal trajecten voor namelijk:


  • Leeuwarden – Harlingen Haven
  • Leeuwarden – Stavoren
  • Zutphen – Hengelo – Oldenzaal
  • Dordrecht - Geldermalen

WCA

Rolstoeltoegankelijk

komt voor als de modaliteit toegankelijk is

SPEC

Speciaal ticket vereist

Komt voornamelijk voor bij (Intercity Direct & Internationale treinen)

FINI

fiets meenemen niet mogelijk

Komt voornamelijk voor bij (Intercity Direct & Internationale treinen)

RESM

Reserveren mogelijk

Komt voornamelijk voor bij (Intercity Direct & Internationale treinen)

TSR

Toeslag Schiphol - Rotterdam

Komt voornamelijk voor bij (Intercity Direct & Internationale treinen)

Structuur van een attribuut

Attributen in het OV-reisadvies zijn in het “Attributes” component te vinden. Attributes bestaat uit nul of meerdere LegAttributes. Hierbij een voorbeeld van een Attributes component:

Formaat

Voorbeeld

XML

<Attributes>
<LegAttribute>
<Id>TWEE</Id>
<Title>alleen 2e klas</Title>
</LegAttribute>
</Attributes>

JSON

"Attributes": [{
"Id": "TWEE",
"Title": "alleen 2e klas"
}]

 

Verstoringsberichten in het OV-reisadvies

Er kunnen verstoringsberichten aan een reisadvies worden gekoppeld. Deze berichten worden door vervoerders (bijvoorbeeld NS) opgestuurd voor een bepaalde plaats, station, halte lijnnummer en/of alle ritten van een vervoerder.
Een verstoringsbericht, indien aanwezig, wordt in het Disruption element van een leg getoond.

Business rules voor het koppelen van verstoringen aan het reisadvies

De 9292 Reisadvies API onderkent vier soorten verstoringsberichten:

  1. Berichten die gelden voor plaatsen
    • Een bericht wordt gekoppeld indien de plaatsnaam van de halte in een leg overeenkomt met de plaatsnaam in een bericht.
    • Indien het betreffend bericht ook de vervoerder bevat, wordt het bericht alleen gekoppeld als zowel de plaatsnaam als de operator in de leg in combinatie voorkomen in het bericht
  2. Berichten die gelden voor haltes
    • Een bericht wordt gekoppeld indien de vertrek- of aankomsthalte van een leg voorkomt in het bericht
  3. Berichten die gelden voor lijnen
    • Een bericht wordt gekoppeld indien het lijnnummer van de leg voorkomt in een bericht
    • Indien een bericht zowel haltes als lijnen bevat geldt dat het bericht alleen wordt getoond als de combinatie lijnnummer met vertrek- of aankomsthalte in het bericht voorkomt
  4. Berichten die gelden voor vervoerders
    • Een bericht wordt gekoppeld indien de operator in de leg voor komt in een bericht en er in het betreffende bericht geen plaatsnaam, lijn of halte is opgenomen

Tarieven in het OV-reisadvies

In alle responses zitten tarieven, deze tarieven staan onder FareLegs. Indien er geen tarieven mogelijk zijn, zoals een OV-reisadvies met een veerboot, dan komt onder element “Complete” false terug. Dan is het niet mogelijk om een totaal OV-reisadvies prijs af te geven. Voor de delen waar het wel mogelijk is, wordt dit per reisdeel getoond.

Tarieven met de trein

Hieronder een voorbeeld response van een treintarief van NS met tariefinformatie:                         

  • 2e klas tarief 14,00 euro volle prijs
  • 2e klas tarief 8,40 euro reductie
  • 1e klas tarief 23,80 euro volle prijs
  • 1e klas tarief 14,30 euro reductie

Formaat

Voorbeeld

XML

<FareInfo>
<Complete>true</Complete>
<FareLegs>
<FareLeg>
<Fares>
<Fare>
<Eurocents>1400</Eurocents>
<FareClass>Second</FareClass>
<Reduced>false</Reduced>
</Fare>
<Fare>
<Eurocents>840</Eurocents>
<FareClass>Second</FareClass>
<Reduced>true</Reduced>
</Fare>
<Fare>
<Eurocents>2380</Eurocents>
<FareClass>First</FareClass>
<Reduced>false</Reduced>
</Fare>
<Fare>
<Eurocents>1430</Eurocents>
<FareClass>First</FareClass>
<Reduced>true</Reduced>
</Fare>
</Fares>
<FromId>station-amsterdam-centraal</FromId>
<OperatorsString>NS</OperatorsString>
<PlaceNamesString>Amsterdam - Rotterdam</PlaceNamesString>
<PriceUnits>86</PriceUnits>
<StarValue></StarValue>
<StarZones xmlns:d7p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
<ToId>station-rotterdam-centraal</ToId>
</FareLeg>
</FareLegs>
<FullPriceEuroCents>1400</FullPriceEuroCents>
<ReducedPriceEuroCents>840</ReducedPriceEuroCents>
</FareInfo>

JSON

"FareInfo": {
"Complete": true,
"ReducedPriceEuroCents": 1400,
"FullPriceEuroCents": 840,
"FareLegs": [{
"FromId": "station-amsterdam-centraal",
"ToId": " station-rotterdam-centraal ",
"PlaceNamesString": " Amsterdam - Rotterdam",
"OperatorsString": "NS",
"Fares": [{
"Eurocents": 1400,
"Reduced": false,
"FareClass": "Second"
},
{
"Eurocents": 840,
"Reduced": true,
"FareClass": "Second"
},
{
"Eurocents": 2380,
"Reduced": false,
"FareClass": "First"
},
{
"Eurocents": 1430,
"Reduced": true,
"FareClass": "First"
}
],
"StarZones": [],
"StarValue": "",
"PriceUnits": 86
}]
}

Tariefeenheden trein

Het aantal tariefeenheden van de trein staan onder “PriceUnits” van de “FareLegs”.

Tram, bus, metro of veer

Hierbij een voorbeeld van een busreis bij het OV-reisadvies van Leeuwarden naar Harlingen met het volgende prijsadvies:

  • Het deel van de reis met Arriva bus 97 is:
    • € 5,30 zonder korting
    • € 3,49 met korting

Formaat

Voorbeeld

XML

<FareInfo>
<Complete>true</Complete>
<FareLegs>
<FareLeg>
<Fares>
<Fare>
<Eurocents>530</Eurocents>
<FareClass>None</FareClass>
<Reduced>false</Reduced>
</Fare>
<Fare>
<Eurocents>349</Eurocents>
<FareClass>None</FareClass>
<Reduced>true</Reduced>
</Fare>
</Fares>
<FromId>leeuwarden/bushalte-station</FromId>
<OperatorsString>Arriva</OperatorsString>
<PlaceNamesString>Leeuwarden - Harlingen</PlaceNamesString>
<PriceUnits i:nil="true" />
<StarValue></StarValue>
<StarZones xmlns:d7p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
<ToId>harlingen/bushalte-station</ToId>
</FareLeg>
</FareLegs>
<FullPriceEuroCents>530</FullPriceEuroCents>
<ReducedPriceEuroCents>349</ReducedPriceEuroCents>
</FareInfo>

JSON

"FareInfo": {
"Complete": true,
"ReducedPriceEuroCents": 349,
"FullPriceEuroCents": 530,
"FareLegs": [{
"FromId": "leeuwarden/bushalte-station",
"ToId": "harlingen/bushalte-station",
"PlaceNamesString": "Leeuwarden - Harlingen",
"OperatorsString": "Arriva",
"Fares": [{
"Eurocents": 530,
"Reduced": false,
"FareClass": "None"
},
{
"Eurocents": 349,
"Reduced": true,
"FareClass": "None"
}
],
"StarZones": [],
"StarValue": "",
"PriceUnits": null
}]
}

“FareLegs” binnen 1 Journey kunnen opgeteld worden bij de volgende combinaties:

  • Combi: Trein + bus/metro of tram
  • Combi: bus/metro/tram + veerboot
  • Combi: Trein + veerboot
  • Combi: Trein + veerboot + bus/metro/tram
  • Combi: Veerboot + bus/metro/tram

Er kan ook gebruik worden gemaakt van onderstaande elementen, deze tellen alle losse elementen bij elkaar op en tonen het volledige en gereduceerde tarief:

  • <FullPriceEuroCents>603</FullPriceEuroCents>
  • <ReducedPriceEuroCents>398</ReducedPriceEuroCents>

Let op:

We willen u erop wijzen dat het presenteren van het totaal van de reductiebedragen in het geval van diverse modaliteiten uitleg aan de reiziger behoeft. Het recht op reductie in de trein kent andere voorwaarden dan het recht op korting in bus, tram en metro.

Geen Tarief beschikbaar

Het kan voorkomen dat er geen tarief beschikbaar is omdat er geen OV-chipkaart informatie aanwezig is (bijv. informatie over een veerboot). Dan komt dit als volgt in de <Fares> terug:

Formaat

Voorbeeld

XML

<FareInfo>
<Complete>false</Complete>
<FareLegs>
<FareLeg>
<Fares>
<Fare>
<Eurocents i:nil="true" />
<FareClass>None</FareClass>
<Reduced>false</Reduced>
</Fare>
<Fare>
<Eurocents i:nil="true" />
<FareClass>None</FareClass>
<Reduced>true</Reduced>
</Fare>
</Fares>
</FareLeg>
</FareLegs>
</FareInfo>

JSON

"Fares": [{
"Eurocents": null,
"Reduced": false,
"FareClass": "None"
},
{
"Eurocents": null,
"Reduced": true,
"FareClass": "None"
}
]

OV-chipkaart wel/niet geldig

Voor het bepalen of op een FareLeg de OV-chipkaart geldig is wordt door de tariefberekening een veld NoChipFare teruggeven aan de 9292 planner. De 9292 planner geeft deze met dezelfde naam weer door aan de client. Dit is een boolean-veld. De waarde is true als er geen OV-chipkaart gebruikt kan worden en false als deze wel gebruikt kan worden.

Formaat

Voorbeeld

XML

<FareInfo>
<Complete>false</Complete>
<FareLegs>
<FareLeg>
<Fares>
<Fare>
<Eurocents>550</Eurocents>
<FareClass>Second</FareClass>
<Reduced>false</Reduced>
</Fare>
<Fare>
<Eurocents>330</Eurocents>
<FareClass>Second</FareClass>
<Reduced>true</Reduced>
</Fare>
<Fare>
<Eurocents>550</Eurocents>
<FareClass>First</FareClass>
<Reduced>false</Reduced>
</Fare>
<Fare>
<Eurocents>330</Eurocents>
<FareClass>First</FareClass>
<Reduced>true</Reduced>
</Fare>
</Fares>
<FromId>station-leeuwarden</FromId>
<NoChipFare>false</NoChipFare>
<OperatorsString>Arriva</OperatorsString>
<PlaceNamesString>Leeuwarden - Harlingen</PlaceNamesString>
<PriceUnits>27</PriceUnits>
<StarValue></StarValue>
<StarZones xmlns:d7p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
<ToId>station-harlingen-haven</ToId>
</FareLeg>
<FareLeg>
<Fares />
<FromId>harlingen/halte-veer-harlingen</FromId>
<NoChipFare>true</NoChipFare>
<OperatorsString>Doeksen</OperatorsString>
<PlaceNamesString>Harlingen - Vlieland</PlaceNamesString>
<PriceUnits i:nil="true" />
<StarValue></StarValue>
<StarZones xmlns:d7p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
<ToId>vlieland/halte-veer-vlieland</ToId>
</FareLeg>
</FareLegs>
<FullPriceEuroCents i:nil="true" />
<ReducedPriceEuroCents i:nil="true" />
</FareInfo>

JSON

"FareInfo": {
"Complete": false,
"ReducedPriceEuroCents": null,
"FullPriceEuroCents": null,
"FareLegs": [{
"FromId": "station-leeuwarden",
"ToId": "station-harlingen-haven",
"PlaceNamesString": "Leeuwarden - Harlingen",
"OperatorsString": "Arriva",
"Fares": [{
"Eurocents": 550,
"Reduced": false,
"FareClass": "Second"
},
{
"Eurocents": 330,
"Reduced": true,
"FareClass": "Second"
},
{
"Eurocents": 550,
"Reduced": false,
"FareClass": "First"
},
{
"Eurocents": 330,
"Reduced": true,
"FareClass": "First"
}
],
"StarZones": [],
"StarValue": "",
"PriceUnits": 27,
"NoChipFare": false
},
{
"FromId": "harlingen/halte-veer-harlingen",
"ToId": "vlieland/halte-veer-vlieland",
"PlaceNamesString": "Harlingen - Vlieland",
"OperatorsString": "Doeksen",
"Fares": [],
"StarZones": [],
"StarValue": "",
"PriceUnits": null,
"NoChipFare": true
}
]
}

 

Fiets en scooter in het OV-reisadvies

Plannen met de fiets of scooter is standaard toegevoegd aan 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-, metro- of tram-fietsoverstappunt.
Met de waarde ‘PrivateMoped’ kunt u de reiziger een OV-reisadvies met de scooter i.p.v. de fiets geven.

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 passend verhuurlocatie. 

Let op:

  • De reiziger kan op dit moment alleen bij de ‘LastMile’ gebruik maken van huurfietsen en huurscooters.
  • Informatie over beschikbare verhuurlocaties per aankomst- of vertreklocatie en de details van een verhuurlocatie (o.a. het aantal beschikbare voertuigen en openingstijden) zijn in de huidige release nog niet beschikbaar.

Business rules voor plannen met de fiets

De standaard business regels voor plannen met de fiets zijn:

  • Fietssnelheid is 230 meter per minuut, dat geeft 13,8 km per uur
  • De maximale fietsafstand die we hanteren, is 6,9 km (30 min)
  • Standaard wordt er in de 9292 Reisadvies API gerekend met 5 minuten stalling- en looptijd naar de halte toe
  • In het geval van huurfietsen wordt er gerekend met 10 minuten voor het ophalen van het voertuig

Business rules voor plannen met de scooter

De standaard business regels voor plannen met de scooter zijn:

  • Scootersnelheid is 20 km per uur
  • De maximale afstand die we hanteren, is 10 km (30 min)
  • Er wordt gerekend met 5 minuten stalling- en looptijd naar de halte toe
  • Voor huurscooters wordt er gerekend met 10 minuten voor het ophalen van het voertuig

 

Bezettingsinformatie in het OV-reisadvies

Door gebruik te maken van de optie ‘Bezettingsinfomatie’ geeft u de reiziger een passend OV-reisadvies met daarin de drukte per gereisde modaliteit en u kunt een totaal drukte voorspelling meegeven over de gehele reis.

De volgende parameters zijn beschikbaar om bezettingsinformatie in het OV-reisadvies te krijgen:

Parameters

Beschrijving (voorbeeld)

ShowOccupancy

true

Classificatie en visualisatie van de bezetting

De bezetting wordt aangegeven op een schaal van 0 tot 5 conform de BISON specificatie “Concept koppelvlak bezetting” Het bezetting kan worden gevisualiseerd middels de bijbehorende kleur of het bijbehorende icoontje.

Zie onderstaande tabel.

Dit is een concept voorbeeld van hoe 9292 zelf de gegevens gaat vertalen in haar apps en website.

Drukte volgens BISON

Enumeratie

Kleur

Icoontje 9292

Opmerkingen

0

No information

 

Level 0 icon

Geen informatie ontvangen of bezetting onbekend.

1

Empty

 

Level 1 icon

Bij NS worden 1 en 2 samengevoegd naar 2

2

Many seats available

 

Level 2 icon

Bij NS <65% van zitplaatsen per bak bezet

3

Few seats available

 

Level 3 icon

Bij NS >65% en < 100%van zitplaatsen per bak bezet

4

Standing room only

 

Level 4 icon

Bij NS >100% van zitplaatsen per bak bezet

5

Full

 

Level 5 icon

Alleen relevant voor realtime gegevens.

Dit is toekomstige informatie en wordt nog niet aangeleverd.

Bij de icoontjes wordt rekening gehouden met onderscheid in de afbeelding, zodat dit ook te zien is bij kleurenblindheid.

Voorbeeld van de bezetting

Een reis van Waterlooplein in Amsterdam, naar de Stadsschouwburg in Utrecht.

  • leg 1:     Tram - 3 haltes (druk-rustig-rustig) krijgt indicator druk
  • leg 2:     Trein Amsterdam Centraal naar Utrecht Centraal - 2 haltes (gemiddeld-rustig) krijgt indicator gemiddeld
  • leg 3:     Bus - paar haltes (rustig-rustig-gemiddeld-rustig-gemiddeld) krijgt indicator gemiddeld

De gehele reis krijgt indicator druk omdat 1 leg de indicator “druk” heeft. 

Er wordt dus geaggregeerd naar de drukste halte van het traject.

 

Reisadvies API Optionele Features

StarZones in het OV-reisadvies

Dit optioneel af te nemen onderdeel kan op verzoek worden toegevoegd aan de 9292 Reisadvies API. De sterwaarden en centrumzones worden gebruikt bij de zogenoemde sterabonnementen. Als u voor dit onderdeel kiest, dan zal de 9292 Reisadvies API berekenen welk sterabonnement nodig is voor het betreffende OV-reisadvies. Er wordt nog in enkele gevallen gebruik gemaakt van sterabonnementen en zodoende zal niet bij ieder OV-reisadvies de sterwaarde/centrumzone worden meegegeven. Zie onderstaand voorbeeld.

In dit voorbeeld is een OV-reisadvies opgevraagd van Station Koog Zaandijk naar Station Krommenie Assendelft. De modaliteit trein is in dit advies uitgeschakeld:

Request:

  • https://<RAPI domain>/v1/api/Journeys?FromId=station-koog-zaandijk&ToId=station-krommenie-assendelft&DateTime=09/27/2013 13:24:00&ExcludedTravelModes=1

Als er starzones aanwezig zijn in het OV-reisadvies dan ziet het er als volgt uit:

Formaat

Voorbeeld

XML

<PriceUnits i:nil="true" />
<StarValue>2</StarValue>
<StarZones xmlns:d7p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<d7p1:string>3722, 3732, 3733, 3742</d7p1:string>
</StarZones>

JSON

"StarZones": [
"3722, 3732, 3733, 3742"
],
"StarValue": "2",
"PriceUnits": null

Als er geen Starzones aanwezig zijn dan wordt het volgende getoond:

Formaat

Voorbeeld

XML

<StarZones xmlns:d7p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />

JSON

"StarZones": []

De sterwaarde kan zowel een numerieke als alfabetische waarde hebben. Er zijn zeven mogelijkheden als waarde: 1 t/m 6 en Netabonnement. Bij een waarde groter dan 6 komt het Netabonnement als waarde naar voren, omdat deze geldig is in het hele land op stad- en streekvervoer.

Meerdere abonnementen

Het kan voorkomen dat voor een reis meer dan 1 abonnement nodig is. In dat geval worden meerdere elementen <FareLeg> getoond waarbij geldt dat de eerste FareLeg de tarief informatie laat zien voor de totale reis. Vervolgens wordt per benodigd abonnement de bijbehorende <FareLeg> getoond. Dit is als volgt zichtbaar in de <Fares>:

Formaat

Voorbeeld

XML

<FareInfo>
    <Complete>true</Complete>
    <FareLegs>
        <FareLeg>
            <Fares>
                <Fare>
                    <Eurocents>1759</Eurocents>
                    <FareClass>None</FareClass>
                    <Reduced>false</Reduced>
                </Fare>
                <Fare>
                    <Eurocents>1161</Eurocents>
                    <FareClass>None</FareClass>
                    <Reduced>true</Reduced>
                </Fare>
            </Fares>
            <FromId>scherpenisse/bushalte-spuidamstraat</FromId>
            <NoChipFare>false</NoChipFare>
            <OperatorsString>Connexxion, Arriva, RET &amp; EBS</OperatorsString>
            <PlaceNamesString>Scherpenisse - Hellevoetsluis</PlaceNamesString>
            <PriceUnits i:nil="true" />
            <StarValue></StarValue>
            <StarZones xmlns:d7p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
            <ToId>hellevoetsluis/bushalte-amnesty-internationallaan</ToId>
        </FareLeg>
        <FareLeg>
            <Fares />
            <FromId>scherpenisse/bushalte-spuidamstraat</FromId>
            <NoChipFare>false</NoChipFare>
            <OperatorsString>Connexxion</OperatorsString>
            <PlaceNamesString>Scherpenisse - Halsteren</PlaceNamesString>
            <PriceUnits i:nil="true" />
            <StarValue>3</StarValue>
            <StarZones xmlns:d7p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                <d7p1:string>7233, 7243, 7248, 7259, 7738</d7p1:string>
            </StarZones>
            <ToId>halsteren/bushalte-nieuwe-molenweg</ToId>
        </FareLeg>
        <FareLeg>
            <Fares />
            <FromId>rotterdam/metrostation-zuidplein</FromId>
            <NoChipFare>false</NoChipFare>
            <OperatorsString>RET &amp; EBS</OperatorsString>
            <PlaceNamesString>Rotterdam - Hellevoetsluis</PlaceNamesString>
            <PriceUnits i:nil="true" />
            <StarValue>5</StarValue>
            <StarZones xmlns:d7p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                <d7p1:string>5246, 5247, 5336, 5337, 5358</d7p1:string>
            </StarZones>
            <ToId>hellevoetsluis/bushalte-amnesty-internationallaan</ToId>
        </FareLeg>
    </FareLegs>
    <FullPriceEuroCents>1759</FullPriceEuroCents>
    <ReducedPriceEuroCents>1161</ReducedPriceEuroCents>
</FareInfo>

JSON

"FareInfo": {
    "Complete"true,
    "ReducedPriceEuroCents"1161,
    "FullPriceEuroCents"1759,
    "FareLegs": [{
            "FromId""scherpenisse/bushalte-spuidamstraat",
            "ToId""hellevoetsluis/bushalte-amnesty-internationallaan",
            "PlaceNamesString""Scherpenisse - Hellevoetsluis",
            "OperatorsString""Connexxion, Arriva, RET & EBS",
            "Fares": [{
                    "Eurocents"1759,
                    "Reduced"false,
                    "FareClass""None"
                },
                {
                    "Eurocents"1161,
                    "Reduced"true,
                    "FareClass""None"
                }
            ],
            "StarZones": [],
            "StarValue""",
            "PriceUnits"null,
            "NoChipFare"false
        },
        {
            "FromId""scherpenisse/bushalte-spuidamstraat",
            "ToId""halsteren/bushalte-nieuwe-molenweg",
            "PlaceNamesString""Scherpenisse - Halsteren",
            "OperatorsString""Connexxion",
            "Fares": [],
            "StarZones": [
                "7233, 7243, 7248, 7259, 7738"
            ],
            "StarValue""3",
            "PriceUnits"null,
            "NoChipFare"false
        },
        {
            "FromId""rotterdam/metrostation-zuidplein",
            "ToId""hellevoetsluis/bushalte-amnesty-internationallaan",
            "PlaceNamesString""Rotterdam - Hellevoetsluis",
            "OperatorsString""RET & EBS",
            "Fares": [],
            "StarZones": [
                "5246, 5247, 5336, 5337, 5358"
            ],
            "StarValue""5",
            "PriceUnits"null,
            "NoChipFare"false
        }
    ]
}

 

CO2 in het OV-reisadvies

Dit optioneel af te nemen onderdeel kan op verzoek worden toegevoegd aan de 9292 Reisadvies API.
Door gebruik te maken van de optie CO2 in het OV-reisadvies, kunnen uw gebruikers per OV-reis vergelijken hoeveel CO2 zij besparen door met het Openbaar Vervoer te reizen.
De berekening van CO2 is gebaseerd op basis van CO2 uitstoot per kilometer en Well to Wheel (WTW) = de uitstoot van zowel de voorketen als de directe emissies samen.

De overzichten worden hieronder weergegeven voor de verschillende vervoermiddelen.

De CO2 waarden zoals hieronder vermeld staan zijn afkomstig van de website co2emissiefactoren.nl en is het initiatief van SKAO, Stimular, Connekt, Milieu Centraal en de Rijksoverheid en is tot stand gekomen in samenwerking met diverse stakeholders.


Auto

Categorie

CO2 uitstoot

Auto Klein

180

Auto Middenklasse

202

Auto Groot

236


Openbaar vervoer

Categorie

CO2 uitstoot

Tram

66

Bus

140

Metro

74

Trein

6

Veerboot

115

Taxi

202

Geraadpleegde bronnen:

Hierbij een voorbeeld van COwaardes in het OV-reisadvies van postcode 3221AL in Hellevoetsluis naar postcode 3078 PE in Rotterdam.

Request:

  • https://<RAPI domain>/v1/api/Journeys?FromId=hellevoetsluis/3221al&ToId=rotterdam/3078pe&DateTime=01/01/2017 10:45:00

Response:

Formaat

Voorbeeld

XML

<CO2Info>
<EmissionByModality>
<Bicycle>0</Bicycle>
<Bus> 4.1666140966497007</Bus>
<CarLarge> 7.0237209057809231</CarLarge>
<CarMedium> 6.0118289108802827</CarMedium>
<CarSmall> 5.3570752671210435</CarSmall>
<Ferry> 3.4225758651051112</Ferry>
<Subway> 2.2023531653719846</Subway>
<Train> 0.17856917557070145</Train>
<Tram> 1.9642609312777162</Tram>
</EmissionByModality>
<JourneyDistance> 29.761529261783576</JourneyDistance>
<JourneyEmission> 4.0814766438217758</JourneyEmission>
</CO2Info>

JSON

"CO2Info": {
"JourneyEmission": 4.0814766438217758,
"JourneyDistance": 29.761529261783576,
"EmissionByModality": {
"Train": 0.17856917557070145,
"Tram": 1.9642609312777162,
"Bus": 4.1666140966497007,
"Subway": 2.2023531653719846,
"Ferry": 3.4225758651051112,
"CarSmall": 5.3570752671210435,
"CarMedium": 6.0118289108802827,
"CarLarge": 7.0237209057809231,
"Bicycle": 0.0
}
}

 Toelichting van de meest relevante elementen uit bovenstaande response:

Element

Beschrijving (voorbeeld)

JourneyDistance

gemeten afstand van de reis in kilometers

JourneyEmission

totale CO2 emissie van de reis met het openbaar vervoer in kilogrammen

 

Realtime in het OV-reisadvies

Dit optioneel af te nemen onderdeel kan op verzoek worden toegevoegd aan de 9292 Reisadvies API. Door gebruik te maken van de optie ‘Realtime OV-reisadviezen’ geeft u de reiziger een passend OV-reisadvies inclusief vertraging van de trein, bus, metro of tram. Waar wijzigingen in tijden optreden, kan de reis herpland worden en biedt 9292 alternatieven aan.

De volgende parameters zijn toegevoegd aan de 9292 Reisadvies API om realtime te tonen in het OV-reisadvies.

Parameters

Beschrijving (voorbeeld)

RealtimeArrival

Actuele aankomsttijd

RealtimeDeparture

Actuele vertrektijd

RealtimeState

None, Offset, Cancelled

Cancellations

None of Cancellations

Delays

None, InternalDelay

Detour

Normal

LudMessage

<Text> Dit is een alternatief reisadvies.</ Text>

Vertraging op een rit

In onderstaand voorbeeld tonen we hoe een vertraging op een rit wordt weergegeven. In dit voorbeeld is zowel de vertrektijd als de aankomsttijd gewijzigd ten opzichte van de oorspronkelijke vertrek- en aankomsttijd.

Oorspronkelijke vertrek en aankomsttijden zijn:

  • Departure 2014-11-05T11:03:00
  • Arrival 2014-11-05T11:27:00

Formaat

Voorbeeld

XML

<RealtimeArrival>2014-11-05T11:55:00</RealtimeArrival>
<RealtimeDeparture>2014-11-05T11:32:00</RealtimeDeparture>
<RealtimeInfo>
<Cancellations>None</Cancellations>
<Delays>InternalDelay</Delays>
<Detour>Normal</Detour>
<LudMessages />
</RealtimeInfo>

JSON

"RealtimeDeparture": "2014-11-05T11:32:00",
"RealtimeArrival": "2014-11-05T11:55:00",
"RealtimeInfo": {
"LudMessages": [],
"Detour": "Normal",
"Cancellations": "None",
"Delays": "InternalD
}

Realtime vertrek- en aankomsttijden op een halte

In een OV-reisadvies wordt voor elke halte de realtime vertrek- en aankomsttijd doorgegeven, ook op de tussenliggende haltes. In onderstaand voorbeeld op de halte Claudius Prinsenlaan in Breda is de bus eerder vertrokken dan de oorspronkelijke planning.

De bus zou moeten vertrekken om 10:05 uur maar vertrekt om 10:02 uur.

Formaat

Voorbeeld

XML

<Call>
<Arrival>2014-11-17T10:05:00</Arrival>
<Departure>2014-11-17T10:05:00</Departure>
<FareZones>
<FareZone>
<Selected>true</Selected>
<Zone>7200</Zone>
</FareZone>
</FareZones>
<Location>
<Coordinate>
<Latitude>51.587575</Latitude>
<Longitude>4.784468</Longitude>
</Coordinate>
<DisplayName>Claudius Prinsenlaan</DisplayName>
<Id>breda/bushalte-claudius-prinsenlaan</Id>
<Place>
<Coordinate>
<Latitude>51.594976</Latitude>
<Longitude>4.779766</Longitude>
</Coordinate>
<CountryCode>NL</CountryCode>
<CountryName>Nederland</CountryName>
<Id>breda</Id>
<Name>Breda</Name>
<RegionCode>NB</RegionCode>
<RegionName>Noord-Brabant</RegionName>
<ShowCountry>false</ShowCountry>
<ShowRegion>false</ShowRegion>
</Place>
<StationAbbreviation i:nil="true" />
<Type>Stop</Type>
<TypeName>Bushalte</TypeName>
</Location>
<Platform i:nil="true" />
<PlatformChange i:nil="true" />
<RealtimeArrival>2014-11-17T10:02:00</RealtimeArrival>
<RealtimeDeparture>2014-11-17T10:02:00</RealtimeDeparture>
<RealtimeState>Offset</RealtimeState>
</Call>

JSON

"Calls": [{
"Location": {
"Id": "breda/bushalte-claudius-prinsenlaan",
"StationAbbreviation": null,
"DisplayName": "ClaudiusPrinsenlaan",
"Place": {
"Id": "breda",
"Name": "Breda",
"RegionCode": "NB",
"RegionName": "Noord-Brabant",
"ShowRegion": false,
"CountryCode": "NL",
"CountryName": "Nederland",
"ShowCountry": false,
"Coordinate": {
"Latitude": 51.594976,
"Longitude": 4.779766
}
},
"Type": "Stop",
"TypeName": "Bushalte",
"Coordinate": {
"Latitude": 51.587575,
"Longitude": 4.784468
}
},
"Platform": null,
"PlatformChange": null,
"Arrival": "2014-11-17T10: 05: 00",
"Departure": "2014-11-17T10: 05: 00",
"RealtimeArrival": "2014-11-17T10: 02: 00",
"RealtimeDeparture": "2014-11-17T10: 02: 00",
"RealtimeState": "Offset",
"FareZones": [{
"Zone": "7200",
"Selected": true
}]
}]

Geplande rit wordt niet gereden

Als een geplande rit niet wordt gereden, dan zal er een cancel bericht worden verzonden vanuit de vervoerder. Dit is zichtbaar in onderstaand voorbeeld.

De sprinter van Amersfoort naar Zwolle rijdt niet. Voor elk station/halte die de rit aan doet, wordt in de RealtimeState een Cancelled ingevuld.

Dit OV-reisadvies gaat dus niet door. Het is van belang dit in de presentatie aan de reiziger uit te leggen.

Request:

  • https://<RAPI domain>/v1/api/Journeys?FromId=station-amersfoort&ToId=zwolle&DateTime=11/04/2014 19:45:00

Formaat

Voorbeeld

XML

<Call>
<Arrival>2014-11-04T19:47:00</Arrival>
<Departure>2014-11-04T19:47:00</Departure>
<FareZones>
<Location>
<Coordinate>
<Latitude>52.153484</Latitude>
<Longitude>5.373807</Longitude>
</Coordinate>
<DisplayName>Amersfoort</DisplayName>
<Id>station-amersfoort</Id>
<Place>
<Coordinate>
<Latitude>52.153484</Latitude>
<Longitude>5.373807</Longitude>
</Coordinate>
<CountryCode>NL</CountryCode>
<CountryName>Nederland</CountryName>
<Id>amersfoort</Id>
<Name>Amersfoort</Name>
<RegionCode>UT</RegionCode>
<RegionName>Utrecht</RegionName>
<ShowCountry>false</ShowCountry>
<ShowRegion>false</ShowRegion>
</Place>
<StationAbbreviation>amf</StationAbbreviation>
<Type>Station</Type>
<TypeName>Station</TypeName>
</Location>
<Platform>2b</Platform>
<PlatformChange i:nil="true" />
<RealtimeArrival i:nil="true" />
<RealtimeDeparture i:nil="true" />
<RealtimeState>Cancelled</RealtimeState>
</Call>
<RealtimeInfo>
<Cancellations>Cancellations</Cancellations>
<Delays>None</Delays>
<Detour>Normal</Detour>
<LudMessages />
</RealtimeInfo>

JSON

"RealtimeInfo": {
"LudMessages": [],
"Detour": "Normal",
"Cancellations": "Cancellations",
"Delays": "None"
"Location": {
"Id": "station-amersfoort",
"StationAbbreviation": "amf",
"DisplayName": "Amersfoort",
"Place": {
"Id": "amersfoort",
"Name": "Amersfoort",
"RegionCode": "UT",
"RegionName": "Utrecht",
"ShowRegion": false,
"CountryCode": "NL",
"CountryName": "Nederland",
"ShowCountry": false,
"Coordinate": {
"Latitude": 52.153484,
"Longitude": 5.373807
}
},
"Type": "Station",
"TypeName": "Station",
"Coordinate": {
"Latitude": 52.153484,
"Longitude": 5.373807
}
},
"Platform": "2b",
"PlatformChange": null,
"Arrival": "2014-11-04T19:42:00",
"Departure": "2014-11-04T19:43:00",
"RealtimeArrival": null,
"RealtimeDeparture": null,
"RealtimeState": "Cancelled",
"FareZones": [{
"Zone": "5042",
"Selected": true
}]
}

Aansluiting wordt niet gehaald

Het kan voorkomen dat een aansluiting niet gehaald wordt. Bijvoorbeeld als bij een overstap in het eerste deel van de reis sprake was van vertraging. In de RealtimeInfo wordt dan een FatalDelay getoond, de rest van de output wijzigt niet.

Dit OV-reisadvies gaat dus niet door. Het is van belang dit in de presentatie aan de reiziger uit te leggen.

Formaat

Voorbeeld

XML

<RealtimeInfo>
<Cancellations>None</Cancellations>
<Delays>FatalDelay</Delays>
<Detour>Normal</Detour>
<LudMessages />
</RealtimeInfo>

JSON

"RealtimeInfo": {
"LudMessages": [],
"Detour": "Normal",
"Cancellations": "None",
"Delays": "FatalDelay"
}

Alternatief OV-reisadvies na vervallen rit

Bij een vervallen OV-reisadvies wordt er vaak een alternatief advies geboden. Het is van belang dit in de presentatie aan de reiziger uit te leggen.

Stel dat voor de reis van Kampen Zuid naar Amsterdam Bijlmer Arena de rit met de sprinter is vervallen. Er rijdt nu een Intercity vanaf Kampen Zuid naar Duivendrecht en vervolgens ga je met de Metro naar Amsterdam Bijlmer Arena.

De belangrijkste wijziging in de response is weergegeven in onderstaand voorbeeld:

Formaat

Voorbeeld

XML

<RealtimeInfo>
<Cancellations>None</Cancellations>
<Delays>InternalDelay</Delays>
<Detour>Normal</Detour>
<LudMessages>
<LudMessage>
<Text>Dit is een alternatief reisadvies.</Text>
<Url i:nil="true" />
</LudMessage>
</LudMessages>
</RealtimeInfo>

JSON

"RealtimeInfo": {
"LudMessages": [{
"Text": "Dit is een alternatief reisadvies.",
"Url": null
}],
"Detour": "Normal",
"Cancellations": "None",
"Delays": "InternalDelay"
}

Extra rit

Wanneer NS een extra rit inlegt wordt dit getoond in de 9292 Reisadvies API.
In onderstaand voorbeeld wordt er een extra rit ingelegd tussen Harderwijk en Zwolle: een extra intercity met ritnummer 29600.
Deze adviezen noemen wij altijd een Alternatief reisadvies zoals je in de Ludmessage ziet staan. Het kan zijn dat er geen Platform of Platformchange is ingevuld zoals hier het geval is. Dat betekent dat 9292 deze informatie niet heeft binnengekregen of de informatie niet is verwerkt. Behalve als het de laatste halte van een extra rit of gewijzigde rit betreft, deze wordt dan niet getoond, dit is een bekende fout en wordt hersteld in een volgende versie.

Formaat

Voorbeeld

XML

<Journey>
<Legs>
<Leg>
<Calls>
<Call>
<Arrival i:nil="true" />
<Departure>2014-11-17T09:00:00</Departure>
<FareZones>
<FareZone>
<Selected>true</Selected>
<Zone>4961</Zone>
</FareZone>
</FareZones>
<Location>
<Coordinate>
<Latitude>52.337846</Latitude>
<Longitude>5.620297</Longitude>
</Coordinate>
<DisplayName>Harderwijk</DisplayName>
<Id>station-harderwijk</Id>
<Place>
<Coordinate>
<Latitude>52.337675</Latitude>
<Longitude>5.620047</Longitude>
</Coordinate>
<CountryCode>NL</CountryCode>
<CountryName>Nederland</CountryName>
<Id>harderwijk</Id>
<Name>Harderwijk</Name>
<RegionCode>GL</RegionCode>
<RegionName>Gelderland</RegionName>
<ShowCountry>false</ShowCountry>
<ShowRegion>false</ShowRegion>
</Place>
<StationAbbreviation>hd</StationAbbreviation>
<Type>Station</Type>
<TypeName>Station</TypeName>
</Location>
<Platform i:nil="true" />
<PlatformChange i:nil="true" />
<RealtimeArrival i:nil="true" />
<RealtimeDeparture i:nil="true" />
<RealtimeState>None</RealtimeState>
</Call>
<Call>
<Arrival>2014-11-17T09:27:00</Arrival>
<Departure i:nil="true" />
<FareZones>
<FareZone>
<Selected>true</Selected>
<Zone>4680</Zone>
</FareZone>
<FareZone>
<Selected>false</Selected>
<Zone>4610</Zone>
</FareZone>
<FareZone>
<Selected>false</Selected>
<Zone>4601</Zone>
</FareZone>
</FareZones>
<Location>
<Coordinate>
<Latitude>52.505185</Latitude>
<Longitude>6.091078</Longitude>
</Coordinate>
<DisplayName>Zwolle</DisplayName>
<Id>station-zwolle</Id>
<Place>
<Coordinate>
<Latitude>52.505185</Latitude>
<Longitude>6.091078</Longitude>
</Coordinate>
<CountryCode>NL</CountryCode>
<CountryName>Nederland</CountryName>
<Id>zwolle</Id>
<Name>Zwolle</Name>
<RegionCode>OV</RegionCode>
<RegionName>Overijssel</RegionName>
<ShowCountry>false</ShowCountry>
<ShowRegion>false</ShowRegion>
</Place>
<StationAbbreviation>zl</StationAbbreviation>
<Type>Station</Type>
<TypeName>Station</TypeName>
</Location>
<Platform i:nil="true" />
<PlatformChange i:nil="true" />
<RealtimeArrival>2014-11-17T09:58:00</RealtimeArrival>
<RealtimeDeparture i:nil="true" />
<RealtimeState>Offset</RealtimeState>
</Call>
</Calls>
<Destination>Zwolle</Destination>
<DurationMinutes i:nil="true" />
<LegType>Scheduled</LegType>
<ModeId>0</ModeId>
<ModeName>Intercity</ModeName>
<ModeType>Train</ModeType>
<OperatorName>NS</OperatorName>
<Service>29600</Service>
</Leg>
</Legs>
<RealtimeArrival>2014-11-17T09:58:00</RealtimeArrival>
<RealtimeDeparture i:nil="true" />
<RealtimeInfo>
<Cancellations>None</Cancellations>
<Delays>InternalDelay</Delays>
<Detour>Normal</Detour>
<LudMessages>
<LudMessage>
<Text>Dit is een alternatief reisadvies.</Text>
<Url i:nil="true" />
</LudMessage>
</LudMessages>
</RealtimeInfo>
</Journey>

JSON

"RealtimeInfo": {
"LudMessages": [{
"Text": "Dit is een alternatief reisadvies.",
"Url": null
}],
"Detour": "Normal",
"Cancellations": "None",
"Delays": "InternalDelay"
},
"Departure": "2014-11-17T09:00:00",
"Arrival": "2014-11-17T09:27:00",
"RealtimeDeparture": null,
"RealtimeArrival": "2014-11-17T09:58:00",
"Legs": [{
"LegType": "Scheduled",
"ModeType": "Train",
"DurationMinutes": null,
"ModeName": "Intercity",
"OperatorName": "NS",
"Destination": "Zwolle",
"Service": "29600",
"Attributes": [],
"Calls": [{
"Location": {
"Id": "station-harderwijk",
"StationAbbreviation": "hd",
"DisplayName": "Harderwijk",
"Place": {
"Id": "harderwijk",
"Name": "Harderwijk",
"RegionCode": "GL",
"RegionName": "Gelderland",
"ShowRegion": false,
"CountryCode": "NL",
"CountryName": "Nederland",
"ShowCountry": false,
"Coordinate": {
"Latitude": 52.337675,
"Longitude": 5.620047
}
},
"Type": "Station",
"TypeName": "Station",
"Coordinate": {
"Latitude": 52.337846,
"Longitude": 5.620297
}
},
"Platform": null,
"PlatformChange": null,
"Arrival": null,
"Departure": "2014-11-17T09:00:00",
"RealtimeArrival": null,
"RealtimeDeparture": null,
"RealtimeState": "None",
"FareZones": [{
"Zone": "4961",
"Selected": true
}]
},
{
"Location": {
"Id": "station-zwolle",
"StationAbbreviation": "zl",
"DisplayName": "Zwolle",
"Place": {
"Id": "zwolle",
"Name": "Zwolle",
"RegionCode": "OV",
"RegionName": "Overijssel",
"ShowRegion": false,
"CountryCode": "NL",
"CountryName": "Nederland",
"ShowCountry": false,
"Coordinate": {
"Latitude": 52.505185,
"Longitude": 6.091078
}
},
"Type": "Station",
"TypeName": "Station",
"Coordinate": {
"Latitude": 52.505185,
"Longitude": 6.091078
}
},
"Platform": null,
"PlatformChange": null,
"Arrival": "2014-11-17T09:27:00",
"Departure": null,
"RealtimeArrival": "2014-11-17T09:58:00",
"RealtimeDeparture": null,
"RealtimeState": "Offset",
"FareZones": [{
"Zone": "4680",
"Selected": true
},
{
"Zone": "4610",
"Selected": false
},
{
"Zone": "4601",
"Selected": false
}
],
"ModeId": 0
},
]
}]

Extra stop

Wanneer een rit een extra stop bevat dan is dit als volgt zichtbaar in de 9292 Reisadvies API:

  • De Service wordt omgezet naar het 9292-formaat.
  • En het element LudMessages is ingevuld.

In de 9292 Reisadvies API is niet zichtbaar welk halte/station er extra wordt aangedaan, alleen is het mogelijk dat het aankomst/vertrekperron niet is ingevuld.

De response van een rit met een extra stop ziet er als volgt uit:

Formaat

Voorbeeld

XML

<Destination>Den Haag</Destination>
<DurationMinutes i:nil="true" />
<LegType>Scheduled</LegType>
<ModeId>0</ModeId>
<ModeName>Intercity</ModeName>
<ModeType>Train</ModeType>
<OperatorName>NS</OperatorName>
<Service> G0746</Service>
<RealtimeArrival i:nil="true" />
<RealtimeDeparture i:nil="true" />
<RealtimeInfo>
<Cancellations>None</Cancellations>
<Delays>None</Delays>
<Detour>Normal</Detour>
<LudMessages>
<LudMessage>
<Text>Dit is een alternatief reisadvies.</Text>
<Url i:nil="true" />
</LudMessage>
</LudMessages>
</RealtimeInfo>

JSON

"RealtimeInfo": {
"LudMessages": [{
"Text": "Dit is een alternatief reisadvies.",
"Url": null
}],
"Detour": "Normal",
"Cancellations": "None",
"Delays": "None"
},
"Departure": "2014-11-18T13:24:00",
"Arrival": "2014-11-18T14:01:00",
"RealtimeDeparture": null,
"RealtimeArrival": null,
"Legs": [{
"LegType": "Scheduled",
"ModeType": "Train",
"DurationMinutes": null,
"ModeName": "Intercity",
"OperatorName": "NS",
"Destination": "Den Haag",
"Service": "G0746",
"Attributes": [],
]
}

 

OV Prijswijzer in het OV-reisadvies

Dit optioneel af te nemen onderdeel kan op verzoek worden toegevoegd aan de 9292 Reisadvies API. Door gebruik te maken van de optie ‘OV Prijswijzer’ geeft u de reiziger een passend OV-reisadvies inclusief de abonnement informatie over de trein, bus, metro of tram. Voor informatie over de OV Prijswijzer verwijzen we u naar onze website. Daar vindt u ook met welke abonnementen de OV Prijswijzer rekent.

OV Prijswijzer request

De volgende parameters zijn toegevoegd aan de 9292 Reisadvies API om het OV Prijswijzer advies te tonen in het OV-reisadvies.

Parameters

Beschrijving (voorbeeld)

TravellerAge

Leeftijd (getal tussen de 4 en 100)

TravellerFrequencyPeriod

Periode (getal 1 of 2)

1 = week,

2 = maand

TravellerFrequency

Aantal dagen (getal tussen 1 en 31, afhankelijk van TravellerFrequencyPeriode)

Als TravellerFrequencyPeriod = 1, dan moet TravellerFrequency tussen 1 en 7 zijn.

Als TravellerFrequencyPeriod = 2 dan moet TravellerFrequency tussen de 1 en 31 zijn.


Het bestaande request moet uitgebreid worden met bovenstaande parameters om in het OV-reisadvies ook een OV Prijswijzer advies op te vragen. Hieronder een voorbeeld van een valide request, met de volgende gegevens:

Veld

Parameter

Van

Amsterdam centraal station

Naar

Den haag centraal station

Datum

17-07-2017

Tijd

07:45

Leeftijd reiziger

24

Aantal dagen

3

Periode (week)

1

Request:

  • https://<RAPI domain>/v1/api/Journeys? FromId=station-amsterdam-centraal&ToId=station-den-haag-centraal&DateTime=07/17/2017 07:45:00&TravellerAge=24&TravellerFrequency=3&TravellerFrequencyPeriod=1

OV Prijswijzer response

In onderstaand voorbeeld tonen we de XML- en JSON-gedeeltes waarin een OV Prijswijzer advies op een rit wordt weergegeven.

Formaat

Voorbeeld

XML

<ProductAdviceInfo>
<ErrorMessage i:nil="true" />
<MonthBasedProducts>
<ProductAdviceCollection>
<ProductAdviceSubSet>
<ProductAdvice>
<ProductDetail>
<AdditionalInformation i:nil="true" />
<CentrumZones i:nil="true" />
<InformationURL>http://9292.nl/prijzen-en-abonnementen/trein/abonnementen/altijd-voordeel#
</InformationURL>
<ProductCompanies />
<ProductName>Altijd Voordeel Maand</ProductName>
<ProductPrice>26402</ProductPrice>
<ProductRoutes>
<ProductRoute>
<Departure>Station Amsterdam Centraal</Departure>
<Destination>Station Leiden Centraal</Destination>
<TransportType>Train</TransportType>
</ProductRoute>
<ProductRoute>
<Departure>Station Leiden Centraal</Departure>
<Destination>Station Den Haag Centraal</Destination>
<TransportType>Train</TransportType>
</ProductRoute>
</ProductRoutes>
<ProductSaldoPrice>29877</ProductSaldoPrice>
<SaldoPrice>29877</SaldoPrice>
<StarValue i:nil="true" />
</ProductDetail>
</ProductAdvice>
</ProductAdviceSubSet>
</ProductAdviceCollection>
</MonthBasedProducts>
<Parameters>
<Age>24</Age>
<Frequency>3</Frequency>
<Period>Week</Period>
</Parameters>
<ROSMonthTotal>29877</ROSMonthTotal>
<ROSYearTotal>358524</ROSYearTotal>
<YearBasedProducts>
<ProductAdviceCollection>
<ProductAdviceSubSet>
<ProductAdvice>
<ProductDetail>
<AdditionalInformation i:nil="true" />
<CentrumZones i:nil="true" />
<InformationURL>http://9292.nl/prijzen-en-abonnementen/trein/abonnementen/altijd-voordeel#
</InformationURL>
<ProductCompanies />
<ProductName>Altijd Voordeel Jaar</ProductName>
<ProductPrice>310819</ProductPrice>
<ProductRoutes>
<ProductRoute>
<Departure>Station Amsterdam Centraal</Departure>
<Destination>Station Leiden Centraal</Destination>
<TransportType>Train</TransportType>
</ProductRoute>
<ProductRoute>
<Departure>Station Leiden Centraal</Departure>
<Destination>Station Den Haag Centraal</Destination>
<TransportType>Train</TransportType>
</ProductRoute>
</ProductRoutes>
<ProductSaldoPrice>358524</ProductSaldoPrice>
<SaldoPrice>358524</SaldoPrice>
<StarValue i:nil="true" />
</ProductDetail>
</ProductAdvice>
</ProductAdviceSubSet>
</ProductAdviceCollection>
</YearBasedProducts>
</ProductAdviceInfo>

JSON

"ProductAdviceInfo": {
"ErrorMessage": null,
"Parameters": {
"Age": 24,
"Frequency": 3,
"Period": "Week"
},
"ROSYearTotal": 358524,
"ROSMonthTotal": 29877,
"YearBasedProducts": [{
"ProductAdviceSubSet": [{
"ProductDetail": {
"ProductRoutes": [{
"Destination": "Station Leiden Centraal",
"Departure": "Station Amsterdam Centraal",
"TransportType": "Train"
},
{
"Destination": "Station Den Haag Centraal",
"Departure": "Station Leiden Centraal",
"TransportType": "Train"
}
],
"InformationURL": "http://9292.nl/prijzen-en-abonnementen/trein/abonnementen/altijd-voordeel#",
"ProductName": "Altijd Voordeel Jaar",
"ProductPrice": 310819,
"ProductSaldoPrice": 358524,
"SaldoPrice": 358524,
"StarValue": null,
"CentrumZones": null,
"AdditionalInformation": null,
"ProductCompanies": []
}
}]
}]
}

 

Toegankelijk plannen in het OV-reisadvies

Dit onderdeel wordt op verzoek toegevoegd aan de 9292 Reisadvies API. Door gebruik te maken van de optie ‘Toegankelijk Plannen & Haltetoegankelijkheid’ geeft u de reiziger een passend OV-reisadvies voor modaliteiten en haltes die geschikt zijn voor iemand met een motorische beperking. Daarnaast worden alle reisadviezen (wel of niet gepland met toegankelijkheid) voorzien van informatie met betrekking tot haltetoegankelijkheid.

De volgende parameters zijn beschikbaar om een toegankelijk OV-reisadvies te krijgen.

Parameters

Beschrijving (voorbeeld)

PlanWithAccessibility

true

Business rules voor een toegankelijk reisadvies

  • De loopsnelheid is 45 meter per minuut.
  • Bij iedere overstaphalte wordt standaard gerekend met 10 minuten extra overstaptijd.
  • Er wordt gepland met toegankelijke haltes zoals aangegeven in het CHB-bestand en met toegankelijke voertuigen zoals aangegeven door de vervoerder in de dienstregeling.

Haltetoegankelijkheid

In de call zijn de volgende eigenschappen toegevoegd:

  • DisabledAccessible
    • Met deze eigenschap kan bepaald worden of een halte rolstoeltoegankelijk is of niet
  • VisuallyAccessible
    • Met deze eigenschap kan bepaald worden of een halte toegankelijk is voor mensen met een visuele beperking

Mogelijke waarden van deze eigenschappen:

Waarden

Betekenis

Accessible

Halte is toegankelijk

NotAccessible

Halte is niet toegankelijk

Unknown

Geen informatie beschikbaar