The 9292 Reisadvies API offers the opportunity to use the planner engine of 9292 within a website or app to give Public Transport information from address to address with all the public transport in the Netherlands.
This documentation describes the features of the 9292 Reisadvies API and gives general information on how to use them. This information is an addition to the Swagger documentation we provide.
The 9292 Reisadvies API supports both XML and JSON. Knowledge of Web API's, XML and JSON are essential to be able to use this API.
Usage of the 9292 Reisadvies API is prohibited without the approval of 9292.
It is mandatory to show the 9292 Logo. 9292 will give approval on the location of the logo before you transfer to the production environment. This is done to safeguard the usage of the 9292 logo.
The logo can be found at the following URL:
|
Software version |
Documentation version |
Remarks |
|
11-05-2020 |
20-01-2020 |
|
|
24-09-2020 |
01-09-2020 |
|
|
08-12-2020 |
15-10-2020 |
|
|
22-03-2021 |
23-03-2021 |
|
|
26-04-2021 |
26-04-2021 |
|
The 9292 Reisadvies API is secured and can only be used when you have been given a Token or a so-called APIKey by 9292. This ‘Token’ exists of symbols and letters, which is provided through a license agreement. This license agreements allows our customers to make requests to our server.
This ‘Token’ should be kept secret and not shared with any other party. In case of misuse 9292 can deactivate your account.
You will receive a Token via e-mail from the 9292 Servicedesk. The Token is your identification code which gives you access to the acceptance environment of the 9292 Reisadvies API. Once you have completed your implementation and your service has been tested by 9292, you may switch to the production environment. The 9292 Servicedesk will send you a new Token for the production environment.
After transferring to the production environment, the acceptance environment will remained accessible for two weeks.
The Token must be included in the header of each request. Here is an example of a request header:
|
Header Key |
Value |
|
Authorization |
Token <MY_TOKEN> |
|
Accept |
Application/XML (for JSON use "Application/JSON") |
|
Content-Type |
charset=utf-8 |
Please note:
The 9292 Travel Advice API only supports HTTPS requests.
Tokens are sent to identify a particular customer and thus the tapping of the HTTP stream can be abused. This can result in a higher count in the statistics and a higher invoice.
The 9292 Reisadvies API makes use of changing data (public transport timetables). This is why only data within the validity date can be used. When a date beyond the validity date is used, the 9292 Reisadvies API will return an error message (400 BadRequest).
The validity can be requested using the Dataset endpoint.
Requesting the Dataset is not counted as an actual request.
In order to request a location, you will have to call the Locations endpoint of the 9292 Reisadvies API. With a location request, you can get information about a station, place, address, stops or POIs (Point of Interests). A location request will return 25 locations. The first locations will be the stations, then the bus/tram/metro stops, then street names, postal codes, etc.
This Locations endpoint is NOT an autosuggest. However, it is possible to develop your own autosuggest based on this endpoint.
The request of a location is not counted as an actual request.
The Journeys endpoint is used to request a public transport travelling advice. Requesting a travel advice will return 9 responses. These are advices around the requested time. The amount of responses cannot be adjusted.
The FromId, ToId and ViaId must correspond to the ‘Id’ of the location retrieved from the Locations endpoint.
Attributes are data which is sent by a transport company (i.e. NS) that pertains to a (part of the) journey. The Attributes element is not shown in every advice, but only in those where the information is included by the public transport company.
The following table contains examples of possible attributes.
|
Attribute Id |
Attribute value |
Description/Remarks |
|
TWEE |
alleen 2e klas |
The ‘Only 2nd class travel’ Attribute only appears on a small number of trails, namely:
|
|
WCA |
Rolstoeltoegankelijk |
Is shown when the modality is accessible |
|
SPEC |
Speciaal ticket vereist |
Usually shown with Intercity Direct & International trains |
|
FINI |
fiets meenemen niet mogelijk |
Usually shown with Intercity Direct & International trains |
|
RESM |
Reserveren mogelijk |
Usually shown with Intercity Direct & International trains |
|
TSR |
Toeslag Schiphol - Rotterdam |
Usually shown with Intercity Direct & International trains |
Attributes can be found in the “Attributes” component of a travel advice. The Attributes component consists of zero or more LegAttributes. Here is an example of an Attributes component:
|
Format |
Example |
|
XML |
<Attributes> |
|
JSON |
"Attributes": [{
|
Disruption messages can be associated with a journey. These messages are sent by the transport company (i.e. NS) for a particular place, station, stop, service and/or for all trips done by an operator.
The disruption messages, if present, are shown in the Disruption element of a journey's leg.
The 9292 Reisadvies API supports four types of disruption messages:
Fares are shown in all responses. They can be found under Farelegs. When there are no fares possible, for example a travelling advice with a ferry, then the element “Complete” will contain the value 'false'. In that case it is not possible to give a total fare for the advice. For the parts where it is possible to give the information, it will be shown per part of the journey.
Below an example is given of a NS train fare:
|
Format |
Example |
|
XML |
<FareInfo> |
|
JSON |
"FareInfo": {
|
The amount of price units of the train is shown under “PriceUnits” of the “FareLegs”.
Here is an example of a bus journey from a travelling advice from Leeuwarden to Harlingen with the following fare information:
|
Format |
Example |
|
XML |
<FareInfo> |
|
JSON |
"FareInfo": {
|
“FareLegs” within 1 Journey can be added up in the following combinations:
The elements below can also be used. These add up all the elements and will show the full and reduction price:
Please note:
We would like to point out that the presenting of reduction prices in case of different modalities needs some explanation. Qualification for reduction in the train has other conditions than the qualification for reduction in bus/tram/metro.
It is possible that there is no fare information available, because there is no OV-chip card information present (i.e. ferry information). This is indicated in <Fares> as follows:
|
Format |
Example |
|
XML |
<FareInfo> |
|
JSON |
"Fares": [{
|
To determine whether the OV-chipcard is valid on a Fareleg, the tariff calculator gives a field NoChipFare to the Planner. The planner gives this back to the client with the same name. This is a boolean-field. This value is true when the OV-chipcard is not valid and it is false when it can be used.
|
Format |
Example |
|
XML |
<FareInfo> |
|
JSON |
"FareInfo": {
|
This item is a standard feature of the 9292 Reisadvies API. By assigning the ‘FirstMile’ and or ‘LastMile’ parameter with the values ‘PrivateBicycle’ or ‘PrivateElectricBicycle’ you can provide the traveler with the appropriate public transport travel advice in which he or she can use their own bicycle or electric bicycle to and from a bicycle transfer point located near a train station or a bus/metro/tram stop.
To use a scooter in the transport travel advice use the value ‘PrivateMoped’.
The 9292 Reisadvies API also supports the use of rental bicycles and scooters. Assigning the value ‘PublicBicycle’, ‘PublicElectricBicycle’ or ‘PublicMoped’ to the ‘LastMile’ parameter will return a transport travel advice with an extra transition-leg to the appropriate rental location.
Please note:
- In the current release the traveler can only rent a bicycle or scooter for the last mile of a journey
- Information on rental locations at the arrival and departure location as well as the rental location details (such as number of available rentals and opening hours) are not yet available in the current release
The standard business rules for planning a journey by bicycle are:
The standard business rules for planning a journey by scooter are:
By using the option ‘Occupancy information’ you can provide the traveler with an appropriate travel advice including the occupancy per vehicle and you can give a occupancy forecast for the entire journey.
The following parameters are available to add the occupancy information to the travel advice:
|
Parameters |
Description (example) |
|
ShowOccupancy |
true |
The occupancy is indicated on a scale from 0-5 in accordance with the BISON specification “Concept interface occupancy”. The occupancy can be visualized with the corresponding color or the corresponding icon.
In the following table an example is given how 9292 translates the data in her own apps and website.
|
BISON occupancy value |
Enumeration |
Color |
9292 icon |
Remarks |
|
0 |
No information |
|
 |
No information received or occupancy unknown |
|
1 |
Empty |
|
 |
At the NS numbers 1 and 2 will be converted to 2 |
|
2 |
Many seats available |
|
 |
At the NS <65% of the seats on the train are taken |
|
3 |
Few seats available |
|
 |
At the NS >65% and <100% of the seats per train are taken |
|
4 |
Standing room only |
|
 |
At the NS >100% of the seats on the train are taken |
|
5 |
Full |
|
 |
Only relevant for realtime data. |
The icons accommodate the visually impaired by making a clear distinction between the icons.
A travel advice from Waterlooplein in Amsterdam to Stadsschouwburg in Utrecht.
The whole journey will get the indicator BUSY because 1 leg has the indicator “BUSY”.
The indicator will be aggregated to the busiest stop of the journey.
This is an optional feature that can be purchased and added to the 9292 Reisadvies API at your request.
The starvalues and centerzones are used in the so-called ‘Sterabonnementen’. If this functionality is activated, the 9292 Reisadvies API will calculate which monthly ticket is required for the travelling advice. This monthly ticket is no longer used everywhere in the Netherlands, thus it is only given when this monthly ticket is applicable. This is demonstrated in the following example
In this example the requested travelling advice is from Station Koog Zaandijk to Station Krommenie Assendelft where the modality train is excluded:
Request:
When there are Star zones present in the travelling advice, the response is as follows:
|
Format |
Example |
|
XML |
<PriceUnits i:nil="true" /> |
|
JSON |
"StarZones": [ |
When there are no Star zones present, the following is returned:
|
Format |
Example |
|
XML |
<StarZones xmlns:d7p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/> |
|
JSON |
"StarZones": [] |
The starvalue can be both a numeric and an alphabetic value. There are seven possible values: 1 to 6 and ‘Netabonnement’. With a value greater than 6, the value Netabonnement will be displayed, as this value is valid in the entire country for city and region transport.
It is possible that for one journey more than 1 monthly ticket is required. In that case multiple elements <FareLeg> are shown, in which the first FareLeg the tariff information shows for the total journey. After this the <FareLeg> is shown per required monthly ticket. This is shown as follows in the <Fares>:
|
Format |
Example |
|
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 & 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 & 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
}
]
}
|
This optional component can be purchased and added to the 9292 Reisadvies API upon request.
By using the CO2 option in the public transport travel advice, your users can compare how much CO2 they save per public transport journey by travelling with Public Transport.
The calculation of CO2 is based on CO2 emissions per kilometre and Well-to-Wheel (WTW) = the emissions of both the pre-use phase and the direct emissions together.
The summaries are shown below for the different modes of transport.
The CO2 values listed below originate from the website co2emissiefactoren.nl and are the initiative of SKAO, Stimular, Connekt, Milieu Centraal and the central government and were created in collaboration with various stakeholders.
Car
|
Category |
CO2 emissions |
|
Small Car |
180 |
|
Mid-class Car |
202 |
|
Large Car |
236 |
Public transport
|
Category |
CO2 emissions |
|
Tram |
66 |
|
Bus |
140 |
|
Metro |
74 |
|
Train |
6 |
|
Ferry |
115 |
|
Taxi |
202 |
Sources consulted:
A sample travel advice with CO2 from zipcode 3221AL in Hellevoetsluis to zipcode 3078PE in Rotterdam:
Request:
Response:
|
Format |
Example |
|
XML |
<CO2Info> |
|
JSON |
"CO2Info": {
|
An explanation of the most relevant elements of the response above:
|
Elements |
Description (example) |
|
JourneyDistance |
measured distance of the journey in kilometres |
|
JourneyEmission |
total CO2 emissions from travel by public transport in kilograms |
This is an extra feature that can be purchased and added to the 9292 Reisadvies API at your request.
By using the functionality ‘Realtime travelling advice’ you provide the traveler with an appropriate travelling advice including delays (train, bus, metro or tram). When there are changes in time, the journey can be rescheduled and alternatives are offered by 9292.
The following parameters are added to the 9292 Reisadvies API to display realtime in the travelling advices.
|
Parameters |
Description (example) |
|
RealtimeArrival |
Actual arrival time |
|
RealtimeDeparture |
Actual departure time |
|
RealtimeState |
None, Offset, Cancelled |
|
Cancellations |
None of Cancellations |
|
Delays |
None, InternalDelay |
|
Detour |
Normal |
|
LudMessage |
<Text>Dit is een alternatief reisadvies.</ Text> |
The example below shows how delays are indicated. In the example both the departure time and the arrival time have changed compared to the original time.
Original departure time and arrival time are:
|
Format |
Example |
|
XML |
<RealtimeArrival>2014-11-05T11:55:00</RealtimeArrival> |
|
JSON |
"RealtimeDeparture": "2014-11-05T11:32:00", |
In a travelling advice for every stop the realtime departure and arrival time is indicated, as is also the case for stops in-between. In the example below the bus has left the bus stop Claudius Prinsenlaan in Breda earlier than originally planned. The bus should have departed at 10:05h but has left the stop at 10:02h.
|
Format |
Example |
|
XML |
<Call> |
|
JSON |
"Calls": [{
|
When a planned journey is cancelled, a cancelled message will be sent by the public transport company. This is shown in the example below.
The sprinter (train) from Amersfoort to Zwolle is cancelled. For every station/ stop of that journey, the RealtimeState shows Cancelled.
Thus, this travelling advice is cancelled. It is considered very important to present this information to the traveler and to give an explanation.
Request:
|
Format |
Example |
|
XML |
<Call> |
|
JSON |
"RealtimeInfo": {
|
It can occur that a transfer connection cannot be realized. For example when there is a delay in the first part of the journey. The RealtimeInfo shows a FatalDelay, the remaining output does not change.
Thus, this travelling advice is cancelled. It is considered very important to present this information to the traveler and to give an explanation.
|
Format |
Example |
|
XML |
<RealtimeInfo> |
|
JSON |
"RealtimeInfo": {
|
When a public transport travelling advice is cancelled, often an alternative travelling advice is offered. It is considered very important to present this information to the traveler.
For example the journey from Kampen Zuid to Amsterdam Bijlmer Arena (sprinter train) has been cancelled. There is an Intercity (train) from Kampen Zuid to Duivendrecht followed by a transfer with the Metro to Amsterdam Bijlmer Arena.
The most important change in the response is displayed in the example below:
|
Format |
Example |
|
XML |
<RealtimeInfo> |
|
JSON |
"RealtimeInfo": {
|
When the NS inserts an extra journey, this is displayed in the 9292 Reisadvies API.
In the example below an extra journey is inserted between Harderwijk and Zwolle: an extra intercity (train) with journey number 29600.
These travelling advices are called ‘Alternatief reisadvies’ as is shown in the Ludmessage.
It can occur that there is no Platform or Platformchange information available, as is shown in the example below. This means that 9292 has not received this information or that this information has not been processed. Except for when it is the last stop of an extra journey, or an alternative journey (then this information is not displayed), this is a known error and will be fixed in the next version of the 9292 Reisadvies API.
|
Format |
Example |
|
XML |
<Journey> |
|
JSON |
"RealtimeInfo": {
|
When a journey has an extra stop, this will be displayed as followed in the 9292 Reisadvies API:
In the 9292 Reisadvies API it is not visible which station/stop is extra inserted. However, it might occur that for that station/stop the departure/arrival platform information is not available.
The response of a journey with an extra stop is as follows:
|
Format |
Example |
|
XML |
<Destination>Den Haag</Destination> |
|
JSON |
"RealtimeInfo": {
|
This feature is optional and can be added to the 9292 Reisadvies API on request.
By using the ‘OV Prijswijzer’ option, you will provide the traveler with an appropriate OV travel advice including the prices of the train, bus, metro or tram. For more information about the ‘OV Prijswijzer’ we refer you to our website 9292.nl. There you will find with which subscriptions the ‘OV Prijswijzer’ calculates.
The following parameters have been added to the 9292 Reisadvies API to show the OV Prijswijzer advice in a travel advice.
|
Parameters |
Description (example) |
|
TravellerAge |
Age (number between 4 and 100) |
|
TravellerFrequencyPeriod |
Periode (number 1 or 2) 1=week, 2=month |
|
TravellerFrequency |
Number of days (number between 1 and 31, dependent on TravellerFrequencyPeriode) If TravellerFrequencyPeriod = 1, then TravellerFrequency must be between 1 and 7. If TravellerFrequencyPeriod = 2, then TravellerFrequency must be bewtween 1 and 31. |
The standard travel advice request must include the aforementioned parameter to add ‘OV Prijswijzer’ advice to the travel advice.
Here is an example of a valid request with the following information:
|
Field |
Parameter |
|
From |
Amsterdam centraal station |
|
To |
Den haag centraal station |
|
Date |
17-07-2017 |
|
Time |
07:45 |
|
Traveler Age |
24 |
|
Number of days |
3 |
|
Periode (week) |
1 |
Request:
In the example below, we show the XML & JSON sections that show a ‘OV Prijswijzer’ advice for a journey.
|
Format |
Example |
|
XML |
<ProductAdviceInfo> |
|
JSON |
"ProductAdviceInfo": {
|
This optional feature can be added to the 9292 Reisadvies API at your request.
By using the option ‘Planning an accessible journey & Stop Accessibility’ you provide the traveler with the appropriate travel advice suited for someone with a physical disability. In addition, all travel advices (whether or not planned with accessibility) are provided with information regarding a stop's accessibility.
The following parameters are available to get an accessible public transport travel advice.
|
Parameters |
Description (example) |
|
PlanWithAccessibility |
true |
The following attributes are added to the call element:
Possible values for these attributes:
|
Values |
Meaning |
|
Accessible |
Stop is accessible |
|
NotAccessible |
Stop is not accessible |
|
Unknown |
No information available |