Klik op http://m.ns.nl voor de mobiele versie van de NS site.

De NS API

De NS API

NS beschikt over een grote hoeveelheid data met informatie over de geplande en actuele dienstregeling. Wij stellen deze gegevens graag ter beschikking aan ontwikkelaars met een REST API.
De NS API beschikt op dit moment over de volgende services:
• Prijzen
• Actuele vertrektijden
• Storingen en werkzaamheden
• De stationslijst met alle stations in Nederland inclusief Geodata
• Reisadviezen van station naar station

Per service mogen maximaal 50.000 requests per dag geplaatst worden. De service stopt met functioneren na 50.000 requests.

Beta-stadium
De API is op dit moment nog in een beta-stadium. Dat betekent dat NS op ieder moment de inhoud en werking van de services kan aanpassen. Wij proberen ontwikkelaars hiervan tijdig op de hoogte te brengen.
Het beta-stadium betekent ook dat de dienstverlening ieder moment beëindigd kan worden. Meer informatie vindt u bij de voorwaarden .

Ondersteuning door NS
De API wordt zonder ondersteuning aangeboden. Wel is er een ontwikkelaarsplatform http://groups.google.com/group/ns-api/topics beschikbaar waar regelmatig NS-medewerkers aanwezig zijn.


Opties

Documentatie actuele vertrektijden

Overzicht

De webservice voor de actuele vertrektijden maakt het mogelijk voor een station een actueel overzicht op te vragen van alle vertrekkende treinen voor het komende uur.

Request

Actuele vertrekinformatie kan worden opgehaald met behulp van de volgende url:

http://webservices.ns.nl/ns-api-avt?station=${Naam of afkorting Station}

Parameter naam

Omschrijving

Verplicht

station

De code (afkorting) of korte naam of middellange naam of volledige naam of synoniem van de stationsnaam

Ja

Er zullen minimaal 10 vertrektijden worden geretourneerd en minimaal de vertrektijden voor het komende uur. Een voorbeeld request voor de actuele vertrektijden van station Utrecht Centraal:

http://webservices.ns.nl/ns-api-avt?station=ut

Omdat vanaf Utrecht Centraal meer dan 10 treinen per uur vertrekken, bevat de response alle vertrekinformatie voor het komende uur.

Een voorbeeld request voor de actuele vertrektijden van station Kampen:

http://webservices.ns.nl/ns-api-avt?station=Kampen

Omdat vanaf Kampen 2 treinen per uur vertrekken, worden er 10 vertrektijden geretourneerd.

Response

De response bestaat uit het element ActueleVertrekTijden dat per vertrekkende trein een element VertrekkendeTrein bevat.

Een VertrekkendeTrein kan de volgende elementen hebben:

  • RitNummer (1): Identificerend nummer van de trein
  • VertrekTijd (1): Vertrektijd van de trein in minuten
  • VertrekVertraging (0..1): Vertraging in minuten
  • VertrekVertragingTekst (0..1): Vertraging presentatietekst
  • EindBestemming (1): Geplande eindbestemming van de trein
  • TreinSoort (1): Treinsoort (Intercity, Sprinter etc.)
  • RouteTekst (0..1): Verkorte weergave van de route die de trein rijdt. Er worden maximaal 4 stopstations opgenomen, waardoor het meestal een samenvatting is van de volledige route.
  • Vervoerder (1): Vervoerder van de trein.
  • VertrekSpoor (1): Vertrekspoor van de trein. Het attribuut "wijziging" geeft aan of er wel of niet sprake is van een spoorwijziging.
  • ReisTip (0..1): Tekstregel die een tip geeft over de reis. Hiermee wordt de aandacht gevestigd op mogelijk onverwachte kenmerken. Bv. een Intercity die stopt op alle tussengelegen stations.
  • Opmerkingen (0..1). Tekstuele opmerkingen bij de vertrekkende trein. Bestaat uit 0 of meer Opmerking-elementen, die de afzonderlijke tekstregels bevatten. Bevat vrijwel altijd actuele ritwijzigingen, zoals "Rijdt vandaag niet".

Voorbeeld

Zie het volgende voorbeeld van een (deel van een) response:

<ActueleVertrekTijden>
  <VertrekkendeTrein>
    <RitNummer>7478</RitNummer>
    <VertrekTijd>2012-02-19T22:47:00+0100</VertrekTijd>
    <VertrekVertraging>PT2M</VertrekVertraging>
    <VertrekVertragingTekst>+2 min</VertrekVertragingTekst>
    <EindBestemming>Breukelen</EindBestemming>
    <TreinSoort>Sprinter</TreinSoort>
    <Vervoerder>NS</Vervoerder>
    <VertrekSpoor wijziging="true">7</VertrekSpoor>
  </VertrekkendeTrein>
  <VertrekkendeTrein>
    <RitNummer>20578</RitNummer>
    <VertrekTijd>2012-02-19T22:47:00+0100</VertrekTijd>
    <EindBestemming>Rotterdam Centraal</EindBestemming>
    <TreinSoort>Intercity</TreinSoort>
    <RouteTekst>Gouda, R'dam Alexander</RouteTekst>
    <Vervoerder>NS</Vervoerder>
    <VertrekSpoor wijziging="false">9b</VertrekSpoor>
  </VertrekkendeTrein>
  <VertrekkendeTrein>
    <RitNummer>5683</RitNummer>
    <VertrekTijd>2012-02-19T22:50:00+0100</VertrekTijd>
    <EindBestemming>Zwolle</EindBestemming>
    <TreinSoort>Sprinter</TreinSoort>
    <RouteTekst>Utrecht Overv, Den Dolder, Amersfoort</RouteTekst>
    <Vervoerder>NS</Vervoerder>
    <VertrekSpoor wijziging="false">3</VertrekSpoor>
  </VertrekkendeTrein>

Voorbeeld ReisTip

Onderstaand voorbeeld toont hoe een reistip bij een vertrekkende trein is opgenomen.

<VertrekkendeTrein>
  <RitNummer>31156</RitNummer>
  <VertrekTijd>2012-02-22T15:32:00+0100</VertrekTijd>
  <EindBestemming>Tiel</EindBestemming>
  <TreinSoort>Stoptrein</TreinSoort>
  <RouteTekst>Elst</RouteTekst>
  <Vervoerder>Syntus</Vervoerder>
  <VertrekSpoor wijziging="false">4</VertrekSpoor>
  <ReisTip>Stopt niet in Arnhem Zuid</ReisTip>
</VertrekkendeTrein>

Voorbeelden Opmerkingen

Onderstaand voorbeeld toont hoe een opmerking is opgenomen bij een vertrekkende trein om aan te geven dat deze niet rijdt.

<VertrekkendeTrein>
  <RitNummer>669</RitNummer>
  <VertrekTijd>2012-02-22T17:13:00+0100</VertrekTijd>
  <EindBestemming>Rotterdam Centraal</EindBestemming>
  <TreinSoort>Intercity</TreinSoort>
  <RouteTekst>Schiphol, Den Haag HS</RouteTekst>
  <Vervoerder>NS</Vervoerder>
  <VertrekSpoor wijziging="false">15a</VertrekSpoor>
  <Opmerkingen>
    <Opmerking>Rijdt vandaag niet</Opmerking>
  </Opmerkingen>
</VertrekkendeTrein>

Onderstaand voorbeeld toont hoe een opmerking is opgenomen bij een vertrekkende trein om aan te geven dat instappen niet is toegestaan. Inhoudelijke toelichting: de Thalys stopt op Schiphol t.b.v. het laten uitstappen van reizigers, het is niet de bedoeling dat reizigers hier instappen.

<VertrekkendeTrein>
  <RitNummer>9339</RitNummer>
  <VertrekTijd>2012-02-21T15:30:00+0100</VertrekTijd>
  <VertrekVertraging>PT1M</VertrekVertraging>
  <VertrekVertragingTekst>+1 min</VertrekVertragingTekst>
  <EindBestemming>Amsterdam Centraal</EindBestemming>
  <TreinSoort>Thalys</TreinSoort>
  <Vervoerder>NS Hispeed</Vervoerder>
  <VertrekSpoor wijziging="false">1-2</VertrekSpoor>
  <Opmerkingen>
    <Opmerking>Niet instappen</Opmerking>
  </Opmerkingen>
</VertrekkendeTrein>


Opties

Documentatie reisadviezen

Overzicht

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 op www.ns.nl en 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.

Release-notes

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

Request

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:

Parameter naam

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

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</Reisdetail>
  <Reisdetail>Bar/Buffet</Reisdetail>
  <Reisdetail>Rolstoel plaatsen</Reisdetail>
  <Reisdetail>Geen fietsen tot 1 april 2012</Reisdetail>
</Reisdetails>


Opties

Documentatie stationslijst

Overzicht

De webservice voor de stationslijst maakt het mogelijk om alle stationsnamen op te vragen. Het is uitdrukkelijk de bedoeling dat afnemers van deze service de reponse zelf voor bepaalde tijd cachen om op een performante manier autoaanvullen te realiseren.

Request

Er zijn twee versies van de stationslijst. Per mei 2012 is v2 de aanbevolen versie. Versie 1 zal worden uitgefaseerd, nadere aankondiging hierover volgt.

De stationslijst versie 1 kan worden opgevraagd met de volgende url:

http://webservices.ns.nl/ns-api-stations

Er zijn geen parameters.

De stationslijst versie 2 kan worden opgevraagd met de volgende url:

http://webservices.ns.nl/ns-api-stations-v2

Er zijn geen parameters.

Response Stationslijst versie 1

De response (versie 1) bestaat uit het element stations dat per station een element station bevat.

Een station kent de volgende structuur:

  • name (1): Lange naam van het station, bestaande uit maximaal 25 karakters.
  • code (1): Afkorting van het station. Deze afkorting is identificerend voor het station, maar in de stationslijst kan de afkorting meerdere malen voorkomen in het geval van aliassen. Zie hieronder bij alias.
  • country (1): Landcode van het station.
  • lat (1): Breedtegraad (latitude) van het station.
  • long (1): Lengtegraad (longitude) van het station.
  • alias (1): Geeft aan of dit station een alias is van een ander station. Dit houdt in dat 1 fysiek station meer dan 1 schrijfwijze voor de naam heeft. Bijvoorbeeld 's Hertogenbosch en Den Bosch, 's Gravenhage en Den Haag, Utrecht Maliebaan en Spoorwegmuseum.

Voorbeeld Stationslijst versie 1

Zie het volgende voorbeeld voor een deel van de reponse (eerste 3 stations):

<stations>
  <station>
    <name>'s-Gravenhage</name>
    <code>GVC</code>
    <country>NL</country>
    <lat>52.080276</lat>
    <long>4.325</long>
    <alias>true</alias>
  </station>
  <station>
    <name>'s-Hertogenbosch</name>
    <code>HT</code>
    <country>NL</country>
    <lat>51.690556</lat>
    <long>5.293611</long>
    <alias>false</alias>
  </station>
  <station>
    <name>'s-Hertogenbosch Oost</name>
    <code>HTO</code>
    <country>NL</country>
    <lat>51.700554</lat>
    <long>5.318333</long>
    <alias>false</alias>
  </station>

Response Stationslijst versie 2

De response (versie 2) bestaat uit het element Stations dat per station een element Station bevat.

Een Station kent de volgende structuur:

  • Code (1): Identificerende afkorting van het station.
  • Type (1): Typering van het station.
  • Namen (1): Namen van het station.
  • Land (1): Landcode van het station:
  • UICCode (1): UIC-code van het station, identificerende code volgens de standaard van de Internationale Spoorwegunie, de UIC: Union Internationale des Chemins de fer.
  • Lat (1): Breedtegraad (latitude) van het station.
  • Lon (1): Lengtegraad (longitude) van het station.
  • Synoniemen (1): Synoniemen van het station.

Het element Namen kent de volgende structuur:

  • Kort (1): Korte naam van het station, bestaande uit maximaal 10  karakters.
  • Middel (1): Middellange naam van het station, bestaande uit maximaal 16 karakters.
  • Lang (1): Lange naam van het station, bestaande uit maximaal 25 karakters.

Het element Synoniemen kent de volgende structuur:

  • Synoniem (0..n): Naam die als synoniem wordt gebruikt voor de lange stationsnaam.

Voorbeeld Stationslijst versie 2

Zie het volgende voorbeeld voor een deel van de reponse (eerste 3 stations):

<Stations>
  <Station>
    <Code>HT</Code>
    <Type>knooppuntIntercitystation</Type>
    <Namen>
      <Kort>H'bosch</Kort>
      <Middel>'s-Hertogenbosch</Middel>
      <Lang>'s-Hertogenbosch</Lang>
    </Namen>
    <Land>NL</Land>
    <UICCode>8400319</UICCode>
    <Lat>51.690556</Lat>
    <Lon>5.293611</Lon>
    <Synoniemen>
      <Synoniem>Hertogenbosch ('s)</Synoniem>
      <Synoniem>Den Bosch</Synoniem>
    </Synoniemen>
  </Station>
  <Station>
    <Code>HTO</Code>
    <Type>stoptreinstation</Type>
    <Namen>
      <Kort>H'bosch O</Kort>
      <Middel>Hertogenbosch O</Middel>
      <Lang>'s-Hertogenbosch Oost</Lang>
    </Namen>
    <Land>NL</Land>
    <UICCode>8400320</UICCode>
    <Lat>51.700554</Lat>
    <Lon>5.318333</Lon>
    <Synoniemen>
      <Synoniem>Hertogenbosch Oost ('s)</Synoniem>
      <Synoniem>Den Bosch Oost</Synoniem>
    </Synoniemen>
  </Station>
  <Station>
    <Code>HDE</Code>
    <Type>stoptreinstation</Type>
    <Namen>
      <Kort>'t Harde</Kort>
      <Middel>'t Harde</Middel>
      <Lang>'t Harde</Lang>
    </Namen>
    <Land>NL</Land>
    <UICCode>8400388</UICCode>
    <Lat>52.40917</Lat>
    <Lon>5.893611</Lon>
    <Synoniemen>
      <Synoniem>Harde ('t)</Synoniem>
    </Synoniemen>
  </Station>
</Stations>


Opties

Voorwaarden

NS stelt enkele voorwaarden voor het gebruik van de API. Een korte samenvatting van de voorwaarden:

  • Respecteer de servercapaciteit van NS; probeer goed om te gaan met de capaciteit die u geboden wordt. Als NS misbruik vermoedt, kunt u direct worden afgesloten.
  • De API is een beta-dienst. NS kan te allen tijde de service (technisch) aanpassen of beëindigen.
  • De ontwikkelaar die toegang gekregen heeft tot de API is verantwoordelijk voor wat er gebeurt met zijn/haar aansluiting.
  • Het is niet toegestaan het logo van NS te gebruiken in de applicatie die u ontwikkelt.
  • Het is niet toegestaan om de gegevens van de API zo te manipuleren dat onjuiste informatie wordt verspreid.


Opties

Documentatie prijzen

Overzicht

De webservice voor de prijzen maakt het mogelijk voor een treinreis de bijbehorende prijsinformatie op te vragen.

N.B. Voor gebruik van de webservice is aparte autorisatie vereist. Deze autorisatie wordt verleend na ontvangst van een getekend contract. Dit contract is op te vragen via nsr.api@ns.nl. Deze procedure is erop gericht om gebruikers van de NS-API bewust te maken van een juiste interpretatie van de prijzen-service in combinatie met de corresponderende treinreisadviezen, om zodoende foutieve prijsinformatie voor NS-klanten te voorkomen.

Release-notes

05-03-2012: Uitbreiding in versie 2 met nieuw element Producten/Tariefeenheden.

26-07-2012: Autorisatie-vereiste toegevoegd.

Request

Prijsinformatie kan worden opgehaald met behulp van de volgende url:

http://webservices.ns.nl/ns-api-prijzen-v2?from=${Naam of afkorting Station}&to=${Naam of afkorting Station}&via=${Naam of afkorting Station}&date=${Datum in ddMMyyyy formaat}

Bovenstaande url betreft versie 2 van deze webservice. Versie 1 is nog wel beschikbaar, maar het wordt afgeraden om deze versie te gebruiken.

Parameter naam

Omschrijving

Verplicht

from

De code (afkorting) of korte naam of middellange naam of volledige naam of synoniem van het vertrekstation

Ja

to

De code (afkorting) of korte naam of middellange naam of volledige naam of synoniem van het aankomststation

Ja

via

De code (afkorting) of korte naam of middellange naam of volledige naam of synoniem van het vertrekstation

Nee

dateTime

De datum in ddMMyyyy formaat

Nee

Het is momenteel niet mogelijk om aan te geven welke prijzen worden geretourneerd; er worden altijd precies 12 prijzen teruggegeven.

Response

Een voorbeeld request:

http://webservices.ns.nl/ns-api-prijzen-v2?from=Eindhoven&to=Best

Levert de volgende response:

<?xml version="1.0" encoding="UTF-8" ?>
  <Producten>
    <Tariefeenheden>10</Tariefeenheden>
    <Product naam="Enkele reis">
      <Prijs korting="vol tarief" klasse="2">2,40</Prijs>
      <Prijs korting="reductie_20" klasse="2">1,90</Prijs>
      <Prijs korting="reductie_40" klasse="2">1,40</Prijs>
      <Prijs korting="vol tarief" klasse="1">4,10</Prijs>
      <Prijs korting="reductie_20" klasse="1">3,30</Prijs>
      <Prijs korting="reductie_40" klasse="1">2,50</Prijs>
    </Product>
    <Product naam="Dagretour">
      <Prijs korting="vol tarief" klasse="2">4,80</Prijs>
      <Prijs korting="reductie_20" klasse="2">3,80</Prijs>
      <Prijs korting="reductie_40" klasse="2">2,80</Prijs>
      <Prijs korting="vol tarief" klasse="1">8,20</Prijs>
      <Prijs korting="reductie_20" klasse="1">6,60</Prijs>
      <Prijs korting="reductie_40" klasse="1">5,00</Prijs>
    </Product>
  </Producten>


Opties

Documentatie storingen en werkzaamheden

Overzicht

De webservice voor de storingen en werkzaamheden maakt het  mogelijk informatie op te vragen over storingen en/of werkzaamheden.

De volgende informatie kan worden opgevraagd:

  1. actuele storingen  (=ongeplande storingen + actuele werkzaamheden)
  2. geplande werkzaamheden (=geplande werkzaamheden) 
  3. actuele storingen voor een gespecificeerd station (=ongeplande storingen + actuele werkzaamheden)

 Request

De storingsinformatie kan worden opgehaald met behulp van de volgende url:

 http://webservices.ns.nl/ns-api-storingen?station=${Stationsnaam}&actual=${true or false}&unplanned=${true or false}

Parameter naam

Omschrijving

Verplicht

station

De code (afkorting) of korte naam of middellange naam of volledige naam of synoniem van de stationsnaam.

Deze parameter levert de informatie zoals hierboven beschreven in punt 3.

Nee

actual

Boolean (true or false) indicator of de actuele storingen moeten worden geretourneerd. Dit betreft zowel de ongeplande storingen die op het moment van de request actueel zijn, als de geplande werkzaamheden die binnen twee uur van het request plaatsvinden. 

Deze parameter levert de informatie zoals hierboven beschreven in punt 1.

Nee

unplanned

Boolean (true or false) indicator of de geplande werkzaamheden voor de komende 2 weken moeten worden geretourneerd.

Deze parameter levert de informatie zoals hierboven beschreven in punt 2.

Let op: bij unplanned=true worden de geplande werkzaamheden geretourneerd. Dit is dus net andersom dan wat de parameternaam doet vermoeden.

Nee

Geen van de parameters is verplicht, echter als er geen enkele parameter wordt ingevuld dan worden er 0 storingen geretourneerd, wat niet de bedoeling kan zijn.

Let op: De parameters kunnen vrij gecombineerd worden maar dit zal in de regel geen logisch resultaat opleveren. De meeste afnemers van de service zullen ofwel actuele storingen of geplande werkzaamheden of actuele storingen voor een bepaald station opvragen

Response

De volgende twee requests leveren dezelfde resultaten:

http://webservices.ns.nl/ns-api-storingen?station=ut
http://webservices.ns.nl/ns-api-storingen?station=Utrecht+Centraal

De response staat binnen NS bekend als stationsbericht. Het retourneert alle relevante storingen (gepland en ongepland) voor het station Utrecht Centraal (code=ut). De response is als volgt:

<Storingen>
  <Ongepland>
    <Storing>
      <id>prio-13345</id>
      <Traject>'s-Hertogenbosch-Nijmegen</Traject>
      <Reden>beperkingen op last van de politie</Reden>
      <Bericht></Bericht>
      <Datum>2010-12-16T11:16:00+0100</Datum>
    </Storing>
  </ongepland>
  <Gepland>
    <Storing>
      <id>2010_almo_wp_18_19dec</id>
      <Traject>Almere Oostvaarders-Weesp/Naarden-Bussum</Traject>
      <Periode>zaterdag 18 en zondag 19 december</Periode>
      <Reden>Beperkt treinverkeer, businzet en/of omreizen, extra reistijd 15-30 min.</Reden>
      <Advies>Maak gebruik van de overige treinen of de bussen:                 reis tussen Weesp en Almere Centrum met de NS-bus in                 plaats van de trein tussen Almere Centrum en Lelystad                 Centrum rijden vier Sprinters per uur reis tussen Almere                 Muziekwijk en Naarden-Bussum via Weesp</Advies>
      <Bericht></Bericht>
    </Storing>
  </Gepland>
</Storingen>


Opties

NS APIBeta

NS stelt haar actuele reisinformatie in de vorm van een API beschikbaar aan ontwikkelaars.

Vraag toegang aan

Printen

Sluit dit menu