Main navigation

Go to content

Documentation: travel recommendations

The web-service for travel recommendations can be used to employ the NS Travel planner for a train journey from one station to another. A travel recommendation consists of multiple travel options, so that the passenger can make a choice. A travel recommendation includes both planned and up to date information.


The planned information is based on the latest published timetable and can be considered a reference point for the passenger. Up to date information is available on the day that the train journey takes place, and may deviate from the initial schedule due to platform changes, delays and unplanned disruptions. Giving both planned and up to date information to the passenger provides insight into the degree to which the actual journey deviates from the planned journey. Examples of this can be found in the Travel planner and on mobiel.ns.nl.

A journey option consists of 1 or more journey components: the journey components correspond to the different train rides that make up the journey. A transfer should take place between 2 journey components.

The most important differences between the planned and up to date travel recommendations are associated with the following information-elements:

  • Notifications: Notifications give a high level indication regarding whether a total journey option will be affected by a planned or unplanned disruption.
  • Platform changes: Platform changes give a detailed indication as to whether a departure or arrival will take place at a different platform than the one planned in the timetable.
  • Delays: Delays give a detailed indication as to whether a departure or arrival will occur later than specified in the timetable.
  • Status: Both journey options and journey components have a status. The status of a journey option indicates the way in which the journey option in its entirety deviates from the timetable. The status of a journey component indicates the way in which the journey component deviates from the timetable. The sum total of the status information can be used to explain the up to date journey options: for example, an invalid journey option can be explained by a delayed journey component.

Release notes

05-03-2012: Expansion with new elements JourneyOption/Status, JourneyComponent/Carrier, JourneyComponent/Status, JourneyComponent/PlannedDisruption, JourneyComponent/UnplannedDisruption.

Request

Parametername Description Required Use
fromStation The code (abbreviation) or short name or medium-length name or full name or synonym of the departure station Yes  
toStation The code (abbreviation) or short name or medium-length name or full name or synonym of the arrival station Yes  
viaStation The code (abbreviation) or short name or medium-length name or full name or synonym of the en route station No  
previousAdvices The number of recommendations in the past - relative to the departure/arrival time - that is required. There is no guarantee that the response to this will be sufficient; in some cases this number may be higher or lower.
 
No Default and maximum is 5
nextAdvices The number of recommendations in the future that is required. There is no guarantee that the response to this will be sufficient; in some cases this number may be higher or lower. No Default and maximum is 5
dateTime ISO8601 formatted date that indicates either the desired arrival time or the desired departure time. If not specified then the current date/time is used. E.g. 2012-02-21T15:50. No  
Departure Boolean (true or false) that indicates whether the dateTime parameters show the desired departure time (=true and the default) or the arrival time (=false) No  
hslAllowed Boolean (true or false) that indicates whether the travel recommendations may include high-speed trains. Default is true No  
yearCArd Boolean (true or false) that indicates whether the user has an annual travel card. Sometimes this can result in extra travel recommendations whereby the route extends beyond the final destination, and then goes back again (if this results in a faster journey). These recommendations are not given when yearCard=false, because they would incur additional charges. Default is false No  

Travel recommendations can be retrieved using the following url:

http://webservices.ns.nl/ns-api-treinplanner?<parameters>

See the table below for an overview of the available parameters:

Response

The response consists of the element JourneyOptions, which contains one JourneyOption element for each journey option.

A JourneyOption has the following structure:

  • Notification (0..n): A notification of a disruption or engineering work that affects the JourneyOption.
  • NumberOfTransfers (1): The number of transfers in this JourneyOption.
  • PlannedJourneyDuration (1): The total duration of the journey in minutes for this JourneyOption according to the timetable.
  • UptodateJourneyDuration (0..1): The total duration of the journey in minutes for this JourneyOption according to the available up to date information.
  • DepartureDelay (0..1): The up to date delay for this JourneyOption in minutes determined compared to the timetable.
  • ArrivalDelay (0..1): The up to date delay of arrival for this JourneyOption in minutes determined compared to the timetable.
  • Optimal (1): Indicates whether this journey option is recommended as the optimal JourneyOption by the NS Travel planner. There is always exactly one optimal JourneyOption amongst the JourneyOptions.
  • PlannedDepartureTime (1): The planned departure time for this JourneyOption according to the timetable.
  • UptodateDepartureTime (1): The up to date departure time of this JourneyOption according to the available up to date information.
  • PlannedArrivalTime (1): The planned arrival time for this JourneyOption according to the timetable.
  • UptodateArrivalTime (1): The up to date arrival time of this JourneyOption according to the available up to date information.
  • Status (0..1): The status of this JourneyOption . Possible values: ON-SCHEDULE, CHANGED, DELAYED, NEW, NOT-OPTIMAL, NOT-POSSIBLE, PLAN-CHANGED.
  • JourneyComponent (1..n): Component of the JourneyOption that can be travelled without a transfer.

A Notification has the following structure:

  • Id (1): Unique identification of a disruption. This can be linked to a (planned or unplanned) disruption (see API documentation: disruptions and engineering works).
  • Serious (1): Serious is "true" if the Notification involves a disruption and "false" if the Notification involves engineering work on the tracks. See www.ns.nl and mobiel.ns.nl for examples of how notifications can be displayed in travel recommendations: a red link for a disruption and a blue link for engineering work on the track.
  • Text (1): Text in the Notification.

A JourneyComponent has the following structure:

  • Carrier (1): The carrier for this JourneyComponent.
  • TransportType (1): The transport type for this JourneyComponent (Intercity, Sprinter, etc.)
  • RideNumber (1): A unique identification number for the train ride in this JourneyComponent.
  • Status (0..1): The status of this JourneyComponent. Possible values: ON-SCHEDULE, CANCELLED (=cancelled train), CHANGED (=change to the plan on the day itself), TRANSFER-NOT-POSSIBLE, DELAYED, NEW (=extra train).
  • JourneyDetails (0..1): Detailed information about this JourneyComponent.
  • PlannedDisruptionId (0..1): Unique identification code for a planned disruption. This can be linked to more detailed information about this disruption, which is can be retrieved from the ns-api-disruptions (see API documentation: disruptions and engineering work).
  • UnplannedDisruptionId (0..1): Unique identification code for an unplanned disruption. This can be linked to more detailed information about this disruption, which is can be retrieved from the ns-api-disruptions (see API documentation: disruptions and engineering work).
  • JourneyStop (1..n): A stop in the JourneyComponent.

A JourneyDetails-element has the following structure:

  • JourneyDetail (1..n): A line of text that explains a JourneyDetail. For example, information about exceptions applicable to international trains.

A JourneyStop has the following structure:

  • Name (1): The name of the JourneyStop station.
  • Time (1): The planned departure time of the JourneyStop according to the timetable.
  • DepartureDelay (0..1): The up to date departure delay of the JourneyStop in minutes determined compared to the timetable.
  • Platform (1): The JourneyStop platform. The attribute "wijziging" indicates whether or not the platform has been changed.

Examples

The following request:

http://webservices.ns.nl/ns-api-treinplanner?fromStation=Utrecht+Centraal&toStation=Wierden&departure=true

gives the following response:
<?xml version="1.0" encoding="UTF-8" ?>
  <ReisMogelijkheden>
    <ReisMogelijkheid>
      <AantalOverstappen>1</AantalOverstappen>
      <GeplandeReisTijd>1:30</GeplandeReisTijd>
      <ActueleReisTijd>1:30</ActueleReisTijd>
      <Optimaal>false</Optimaal>
      <GeplandeVertrekTijd>2012-02-27T12:51:00+0100</GeplandeVertrekTijd>
      <ActueleVertrekTijd>2012-02-27T12:51:00+0100</ActueleVertrekTijd>
      <GeplandeAankomstTijd>2012-02-27T14:21:00+0100</GeplandeAankomstTijd>
      <ActueleAankomstTijd>2012-02-27T14:21:00+0100</ActueleAankomstTijd>
      <Status>NIET-OPTIMAAL</Status>
      <ReisDeel reisSoort="TRAIN">
        <Vervoerder>NS</Vervoerder>
        <VervoerType>Intercity</VervoerType>
        <RitNummer>1743</RitNummer>
        <Status>VOLGENS-PLAN</Status>
        <ReisStop>
          <Naam>Utrecht Centraal</Naam>
          <Tijd>2012-02-27T12:51:00+0100</Tijd>
          <Spoor wijziging="false">11</Spoor>
        </ReisStop>
        <ReisStop>
          <Naam>Amersfoort</Naam>
          <Tijd>2012-02-27T13:08:00+0100</Tijd>
        </ReisStop>
        <ReisStop>
          <Naam>Apeldoorn</Naam>
          <Tijd>2012-02-27T13:32:00+0100</Tijd>
          <Spoor wijziging="false">4</Spoor>
        </ReisStop>
      </ReisDeel>
      <ReisDeel reisSoort="TRAIN">
        <Vervoerder>NS</Vervoerder>
        <VervoerType>Sprinter</VervoerType>
        <RitNummer>7043</RitNummer>
        <Status>VOLGENS-PLAN</Status>
        <ReisStop>
          <Naam>Apeldoorn</Naam>
          <Tijd>2012-02-27T13:38:00+0100</Tijd>
          <Spoor wijziging="false">3</Spoor>
        </ReisStop>
        <ReisStop>
          <Naam>Apeldoorn Osseveld</Naam>
          <Tijd>2012-02-27T13:42:00+0100</Tijd>
        </ReisStop>
        <ReisStop>
          <Naam>Twello</Naam>
          <Tijd>2012-02-27T13:47:00+0100</Tijd>
        </ReisStop>
        <ReisStop>
          <Naam>Deventer</Naam>
          <Tijd>2012-02-27T13:55:00+0100</Tijd>
        </ReisStop>
        <ReisStop>
          <Naam>Deventer Colmschate</Naam>
          <Tijd>2012-02-27T14:00:00+0100</Tijd>
        </ReisStop>
        <ReisStop>
          <Naam>Holten</Naam>
          <Tijd>2012-02-27T14:08:00+0100</Tijd>
        </ReisStop>
        <ReisStop>
          <Naam>Rijssen</Naam>
          <Tijd>2012-02-27T14:15:00+0100</Tijd>
        </ReisStop>
        <ReisStop>
          <Naam>Wierden</Naam>
          <Tijd>2012-02-27T14:21:00+0100</Tijd>
          <Spoor wijziging="false">1</Spoor>
        </ReisStop>
      </ReisDeel>
    </ReisMogelijkheid> ...

Example of planned engineering works

The example below is a journey option that is affected by planned engineering works. Take note of the Notification, the Status-elements, the TransportType, the PlannedDisruptionId and the JourneyDetails.
<ReisMogelijkheid>
  <Melding>
    <Id>2012_gn_asn_25feb_4mrt</Id>
    <Ernstig>false</Ernstig>
    <Text>Let op, werk aan het spoor Assen - Groningen</Text>
  </Melding>
  <AantalOverstappen>1</AantalOverstappen>
  <GeplandeReisTijd>1:18</GeplandeReisTijd>
  <ActueleReisTijd>1:18</ActueleReisTijd>
  <Optimaal>false</Optimaal>
  <GeplandeVertrekTijd>2012-03-02T13:17:00+0100</GeplandeVertrekTijd>
  <ActueleVertrekTijd>2012-03-02T13:17:00+0100</ActueleVertrekTijd>
  <GeplandeAankomstTijd>2012-03-02T14:35:00+0100</GeplandeAankomstTijd>
  <ActueleAankomstTijd>2012-03-02T14:35:00+0100</ActueleAankomstTijd>
  <Status>VOLGENS-PLAN</Status>
  <ReisDeel reisSoort="TRAIN">
    <Vervoerder>NS</Vervoerder>
    <VervoerType>Intercity</VervoerType>
    <RitNummer>541</RitNummer>
    <Status>VOLGENS-PLAN</Status>
    <ReisStop>
      <Naam>Zwolle</Naam>
      <Tijd>2012-03-02T13:17:00+0100</Tijd>
      <Spoor wijziging="false">3</Spoor>
    </ReisStop>
    <ReisStop>
      <Naam>Assen</Naam>
      <Tijd>2012-03-02T13:57:00+0100</Tijd>
      <Spoor wijziging="false">2</Spoor>
    </ReisStop>
  </ReisDeel>
  <ReisDeel reisSoort="TRAIN">
    <Vervoerder>NS</Vervoerder>
    <VervoerType>Snelbus i.p.v. Trein</VervoerType>
    <RitNummer>0</RitNummer>
    <Status>VOLGENS-PLAN</Status>
    <Reisdetails>
      <Reisdetail>Fiets meenemen niet mogelijk</Reisdetail>
    </Reisdetails>
    <GeplandeStoringId>2012_gn_asn_25feb_4mrt</GeplandeStoringId>
    <ReisStop>
      <Naam>Assen</Naam>
      <Tijd>2012-03-02T14:05:00+0100</Tijd>
      <Spoor wijziging="false" />
    </ReisStop>
    <ReisStop>
      <Naam>Groningen</Naam>
      <Tijd>2012-03-02T14:35:00+0100</Tijd>
      <Spoor wijziging="false" />
    </ReisStop>
  </ReisDeel>
</ReisMogelijkheid>

Example of an unplanned disruption

The example below is a Journey option that is affected by an unplanned disruption. Take note of the Notification, the Status-elements and the UnplannedDisruptionId.
<ReisMogelijkheid>
  <Melding>
    <Id />
    <Ernstig>true</Ernstig>
    <Text>Dit reisadvies vervalt</Text>
  </Melding>
  <AantalOverstappen>0</AantalOverstappen>
  <GeplandeReisTijd>0:32</GeplandeReisTijd>
  <ActueleReisTijd>0:32</ActueleReisTijd>
  <Optimaal>false</Optimaal>
  <GeplandeVertrekTijd>2012-03-02T12:56:00+0100</GeplandeVertrekTijd>
  <ActueleVertrekTijd>2012-03-02T12:56:00+0100</ActueleVertrekTijd>
  <GeplandeAankomstTijd>2012-03-02T13:28:00+0100</GeplandeAankomstTijd>
  <ActueleAankomstTijd>2012-03-02T13:28:00+0100</ActueleAankomstTijd>
  <Status>NIET-MOGELIJK</Status>
  <ReisDeel reisSoort="TRAIN">
    <Vervoerder>NS</Vervoerder>
    <VervoerType>Intercity</VervoerType>
    <RitNummer>848</RitNummer>
    <Status>GEANNULEERD</Status>
    <OngeplandeStoringId>prio-24008</OngeplandeStoringId>
    <ReisStop>
      <Naam>Maastricht</Naam>
      <Tijd>2012-03-02T12:56:00+0100</Tijd>
      <Spoor wijziging="false">3</Spoor>
    </ReisStop>
    <ReisStop>
      <Naam>Sittard</Naam>
      <Tijd>2012-03-02T13:13:00+0100</Tijd>
    </ReisStop>
    <ReisStop>
      <Naam>Roermond</Naam>
      <Tijd>2012-03-02T13:28:00+0100</Tijd>
      <Spoor wijziging="false">2</Spoor>
    </ReisStop>
  </ReisDeel>
</ReisMogelijkheid>

Example of a delay

The example below shows a component of a journey option affected by a delay.
<ReisMogelijkheden>
  <ReisMogelijkheid>
    <AantalOverstappen>1</AantalOverstappen>
    <GeplandeReistijd>0:31</GeplandeReistijd>
    <ActueleReistijd>0:31</ActueleReistijd>
    <AankomstVertraging>+17 min</AankomstVertraging>
    <Optimaal>false</Optimaal>
    <GeplandeVertrektijd>2010-09-14T15:17:00+0200</GeplandeVertrektijd>
    <ActueleVertrektijd>2010-09-14T15:17:00+0200</ActueleVertrektijd>
    <GeplandeAankomsttijd>2010-09-14T15:48:00+0200</GeplandeAankomsttijd>
    <ActueleAankomsttijd>2010-09-14T16:05:00+0200</ActueleAankomsttijd>

Example of journey details

The example below shows journey details recorded in the manner often used for international trains.
<Reisdetails>
  <Reisdetail>Reserveren buitenl. aanbevolen