Hoofdnavigatie

Naar content

Documentatie reisadviezen

De webservice voor de reisadviezen maakt het mogelijk de NS Reisplanner aan te roepen voor een treinreis van een station naar een station. Een reisadvies bestaat uit meerdere reismogelijkheden, zodat de treinreiziger hier een keuze uit kan maken. Een reismogelijkheid bevat zowel geplande als actuele informatie.


De geplande informatie is gebaseerd op de laatst gepubliceerde dienstregeling, en kan worden beschouwd als het referentiepunt voor de treinreiziger. De actuele informatie is beschikbaar op de dag dat de treindienst wordt uitgevoerd, en kan afwijkingen t.o.v. de planning bevatten ten gevolge van spoorwijzigingen, vertragingen en ongeplande storingen. Door geplande en actuele informatie hand in hand aan de treinreiziger aan te bieden, kan inzichtelijk worden gemaakt hoe de actuele treinreis afwijkt van de geplande treinreis. Voorbeelden hiervan zijn te vinden in de Reisplanner en op mobiel.ns.nl.

Een reismogelijkheid bestaat uit 1 of meer reisdelen: de reisdelen komen overeen met de verschillende treinritten waaruit een reis bestaat. Tussen 2 reisdelen dient te worden overgestapt.

De belangrijkste verschillen tussen het planmatige en actuele reisadvies zijn vervat in de volgende informatie-elementen:

  • Meldingen: De meldingen geven op hoog niveau aan of een reismogelijkheid in z'n totaliteit wordt geraakt door een geplande of ongeplande storing.
  • Spoorwijzigingen: Spoorwijzigingen geven op gedetailleerd niveau aan of een vertrek of een aankomst plaatsvindt op een ander spoor dan gepland volgens de dienstregeling.
  • Vertragingen: Vertragingen geven op gedetailleerd niveau aan of een vertrek of een aankomst later plaatsvindt dan volgens de dienstregeling.
  • Status: Zowel een reismogelijkheid als een reisdeel heeft een status. De status van de reismogelijkheid geeft aan op welke manier de reismogelijkheid als geheel afwijkt van de dienstregeling. De status van een reisdeel geeft aan op welke manier een reisdeel afwijkt van de dienstregeling. De optelsom van de statusinformatie kan worden gebruikt om een toelichting te geven bij de actuele reismogelijkheden: zo kan bv. een vervallen reismogelijkheid worden verklaard door een vertraagd reisdeel.

Releasenotes

05-03-2012: Uitbreiding met nieuwe elementen ReisMogelijkheid/Status, Reisdeel/Vervoerder, Reisdeel/Status, Reisdeel/GeplandeStoringId, Reisdeel/OngeplandeStoringId.

Request

Parameternaam Omschrijving Verplicht Gebruik
fromStation De code (afkorting) of korte naam of middellange naam of volledige naam of synoniem van het vertrekstation Ja  
toStation De code (afkorting) of korte naam of middellange naam of volledige naam of synoniem van het aankomststation Ja  
viaStation De code (afkorting) of korte naam of middellange naam of volledige naam of synoniem van het viastation Nee  
previousAdvices Het aantal adviezen in het verleden - relatief van de vertrek/aankomsttijd - dat gewenst is. Er is geen garantie dat de response hieraan zal voldoen; in sommige situaties kan dit aantal groter of kleiner zijn.
 
Nee Default en maximum is 5
nextAdvices Het aantal adviezen in de toekomst dat gewenst is. Er is geen garantie dat de response hieraan zal voldoen; in sommige situaties kan dit aantal groter of kleiner zijn. Nee Default en maximum is 5
dateTime ISO8601 geformateerde datum die dan wel de gewenste aankomsttijd dan wel vertrektijd aangeeft. Indien niet gespecificeerd dan is de wordt de huidige tijd/datum gebruikt. Bv. 2012-02-21T15:50. Nee  
Departure Boolean (true of false) die aangeeft of de dateTime parameters de gewenste vertrektijd (=true en de default) dan wel de aankomsttijd is (=false) Nee  
hslAllowed Boolean (true of false) die aangeeft of de reisadviezen hogesnelheidstreinen mogen bevatten. Default is true Nee  
yearCArd Boolean (true of false) die aangeeft of de gebruiker een jaarkaart heeft. In sommige gevallen leidt dit tot extra reisadviezen waarbij tot voorbij de eindbestemming wordt gereisd om vervolgens weer terug te reizen (indien dit een snellere reismogelijkheid oplevert). Deze adviezen worden met yearCard=false niet gegeven, omdat hiervoor een hoger tarief geldt. Default is false Nee  

Het opvragen van een reisadvies kan met behulp van de volgende url:

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

Zie onderstaande tabel voor een overzicht van de beschikbare parameters:

Response

De response bestaat uit het element ReisMogelijkheden, dat per reismogelijkheid een element ReisMogelijkheid bevat.

Een ReisMogelijkheid kent de volgende structuur:

  • Melding (0..n): Een melding over een storing of werk aan het spoor waardoor de ReisMogelijkheid wordt geraakt.
  • AantalOverstappen (1): Het aantal keren dat in deze ReisMogelijkheid moet worden overgestapt.
  • GeplandeReisTijd (1): De totale reistijd in minuten van deze ReisMogelijkheid volgens de dienstregeling.
  • ActueleReisTijd (0..1): De totale reistijd in minuten van deze ReisMogelijkheid volgens de beschikbare actuele informatie.
  • VertrekVertraging (0..1): De actuele vertraging in minuten van het eerste vertrek van deze Reismogelijkheid, bepaald t.o.v. de dienstregeling.
  • AankomstVertraging (0..1): De actuele vertraging in minuten van de laatste aankomst van deze ReisMogelijkheid, bepaald t.o.v. de dienstregeling.
  • Optimaal (1): Geeft aan of deze reismogelijkheid door de NS Reisplanner wordt geadviseerd als optimale ReisMogelijkheid . Er is altijd precies één optimale ReisMogelijkheid binnen de ReisMogelijkheden.
  • GeplandeVertrekTijd (1): De geplande vertrektijd van deze ReisMogelijkheid volgens de dienstregeling.
  • ActueleVertrekTijd (1): De actuele vertrektijd van deze ReisMogelijkheid volgens de beschikbare actuele informatie.
  • GeplandeAankomstTijd (1): De geplande aankomsttijd van deze ReisMogelijkheid volgens de dienstregeling.
  • ActueleAankomstTijd (1): De actuele aankomsttijd van deze ReisMogelijkheid volgens de beschikbare actuele informatie.
  • Status (0..1): De status van deze ReisMogelijkheid . Mogelijke waarden: VOLGENS-PLAN, GEWIJZIGD, VERTRAAGD, NIEUW, NIET-OPTIMAAL, NIET-MOGELIJK, PLAN-GEWIJZIGD.
  • ReisDeel (1..n): Deel van de ReisMogelijkheid die zonder overstap wordt gemaakt.

Een Melding kent de volgende structuur:

  • Id (1): Unieke identificatie van een storing. Hiermee kan worden doorgelinkt naar een (geplande of ongeplande) storing (zie API documentatie storingen en werkzaamheden).
  • Ernstig (1): Ernstig is "true" als de Melding betrekking heeft op een storing en "false" als de Melding betrekking heeft op werk aan het spoor. Zie www.ns.nl en mobiel.ns.nl voor voorbeelden hoe meldingen kunnen worden weergegeven bij een reisadvies: een rode link voor een storing en een blauwe link voor werk aan het spoor.
  • Text (1): Tekst van de Melding.

Een ReisDeel kent de volgende structuur:

  • Vervoerder (1): De vervoerder van dit ReisDeel.
  • VervoerType (1): Het vervoertype van dit ReisDeel (Intercity, Sprinter, etc.)
  • RitNummer (1): Een getal dat de treinrit van dit ReisDeel uniek identificeert.
  • Status (0..1): De status van dit ReisDeel. Mogelijke waarden: VOLGENS-PLAN, GEANNULEERD (=vervallen trein), GEWIJZIGD (=planaanpassing in de bijsturing op de dag zelf), OVERSTAP-NIET-MOGELIJK, VERTRAAGD, NIEUW (=extra trein).
  • ReisDetails (0..1): Detailinformatie over dit ReisDeel.
  • GeplandeStoringId (0..1): Unieke identificatie van een geplande storing. Hiermee kan worden doorgelinkt naar de detailinformatie over deze storing die opvraagbaar is via de ns-api-storingen (zie API documentatie storingen en werkzaamheden).
  • OngeplandeStoringId (0..1): Unieke identificatie van een ongeplande storing. Hiermee kan worden doorgelinkt naar de detailinformatie over deze storing die opvraagbaar is via de ns-api-storingen (zie API documentatie storingen en werkzaamheden).
  • ReisStop (1..n): Een stop van het ReisDeel.

Een ReisDetails-element kent de volgende structuur:

  • ReisDetail (1..n): Tekstregel die een ReisDetail uitdrukt. Dit kan bv. informatie zijn over bijzonderheden die gelden voor internationale treinen.

Een ReisStop kent de volgende structuur:

  • Naam (1): De naam van het station van de ReisStop.
  • Tijd (1): De geplande vertrektijd van de ReisStop volgens de dienstregeling.
  • VertrekVertraging (0..1): De actuele vertraging in minuten van het vertrek van de ReisStop, bepaald t.o.v. de dienstregeling.
  • Spoor (1): Het spoor van de ReisStop. Het attribuut "wijziging" geeft aan of er wel of geen sprake is van een spoorwijziging.

Voorbeelden

De volgende request:

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

levert de volgende 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> ...

Voorbeeld geplande werkzaamheden

Het onderstaande voorbeeld laat een reismogelijkheid zien die wordt geraakt door geplande werkzaamheden. Let op de Melding, de Status-elementen, het VervoerType, het GeplandeStoringId en de ReisDetails.
<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>

Voorbeeld ongeplande storing

Het onderstaande voorbeeld laat een reismogelijkheid zien die wordt geraakt door een ongeplande storing. Let op de Melding, de Status-elementen en het OngeplandeStoringId.
<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>

Voorbeeld vertraging

Het onderstaande voorbeeld laat zien een deel van een reismogelijkheid zien met vertraging.
<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>

Voorbeeld reisdetails

Het onderstaande voorbeeld laat reisdetails zien zoals die vaak zijn opgenomen bij internationale treinen.
<Reisdetails>
  <Reisdetail>Reserveren buitenl. aanbevolen