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.

Actuele vertrektijden

Actuele vertrekinformatie kan worden opgehaald via de url:

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

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 (waarvan de laatste 5 uur in de toekomst ligt). Zie de volgende (omwille van beknoptheid niet volledige) response:

<actuelevertrektijden>
  <vertrekkendetrein>
    <vertrektijd>2011-01-31T10:03:00+0200</vertrektijd>
    <vertrekvertraging>PT2M</vertrekvertraging>
    <vertrekvertragingtekst>+2 min</vertrekvertragingtekst>
    <eindbestemming>Zwolle</eindbestemming>
    <treinsoort>Stoptrein</treinsoort>
    <vertrekspoor wijziging="false">1</vertrekspoor>
    <opmerkingen>
      <opmerking>Niet instappen</opmerking>
    </opmerkingen>
  </vertrekkendetrein>
  <vertrekkendetrein>
    <vertrektijd>2011-01-31T10:33:00+0200</vertrektijd>
    <vertrekvertraging>PT2M</vertrekvertraging>
    <vertrekvertragingtekst>+2 min</vertrekvertragingtekst>
    <eindbestemming>Zwolle</eindbestemming>
    <treinsoort>Stoptrein</treinsoort>
    <vertrekspoor wijziging="false">1</vertrekspoor>
  </vertrekkendetrein>
</actuelevertrektijden>

Prijsinformatie kan worden opgehaald via versie 2 van de prijzenservice de 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 ISO8601 formaat}

Daarnaast is ook nog versie 1 van de prijzenservice beschikbaar op:

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

U wordt echter aangeraden om versie 2 te gebruiken.

De from, to en via parameters ondersteunen zowel stationsafkortingen als volledige stationsnamen. Het is momenteel niet mogelijk om aan te geven welke prijzen worden geretourneerd; er worden altijd precies 12 prijzen teruggegeven. Een voorbeeld request:

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

Levert de volgende response:

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

Reisadviezen

Het opvragen van een reisadvies kan middels de volgende url (zie de parameter tabel voor een overzicht van de beschikbare parameters):

http://webservices.ns.nl/ns-api-treinplanner?...

De volgende aanroep:

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:28</geplandereistijd>
    <actuelereistijd>1:28</actuelereistijd>
    <optimaal>false</optimaal>
    <geplandevertrektijd>2010-12-03T10:51:00+0100</geplandevertrektijd>
    <actuelevertrektijd>2010-12-03T10:51:00+0100</actuelevertrektijd>
    <geplandeaankomsttijd>2010-12-03T12:19:00+0100</geplandeaankomsttijd>
    <actueleaankomsttijd>2010-12-03T12:19:00+0100</actueleaankomsttijd>
    <reisdeel reissoort="TRAIN">
      <vervoertype>Intercity</vervoertype>
      <reisstop>
        <naam>Utrecht Centraal</naam>
        <tijd>2010-12-03T10:51:00+0100</tijd>
        <spoor wijziging="false">12</spoor>
      </reisstop>
      <reisstop>
        <naam>Amersfoort</naam>
        <tijd>2010-12-03T11:07:00+0100</tijd>
      </reisstop>
      <reisstop>
        <naam>Apeldoorn</naam>
        <tijd>2010-12-03T11:32:00+0100</tijd>
        <spoor wijziging="false">4</spoor>
      </reisstop>
    </reisdeel>
    <reisdeel reissoort="TRAIN"> ... </reisdeel>
  </reismogelijkheid>
  <reismogelijkheid>
    <aantaloverstappen>2</aantaloverstappen>
    ...
  </reismogelijkheid>
  ...
</reismogelijkheden>

Reisadviezen kunnen vertragingsinformatie bevatten. Het volgende response bevat een melding:

<reismogelijkheden>
  <reismogelijkheid>
    <melding>
      <id>prio-12273</id>
      <ernstig>true</ernstig>
      <text>Let op, verstoring Amsterdam Centraal - Haarlem</text>
    </melding>
    ........
    ........ 

Een Melding kan ernstig zijn (rode balk) dan wel niet ernstig (blauwe balk) en kan een id bevatten waarmee kan worden doorgelinkt naar de storingen. Indien een reis vertraging heeft dan wordt dit op de volgende manier aangegeven:

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

Stations

De station-service kan worden gebruikt om alle stationsnamen op te vragen.

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

Er zijn geen parameters want 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.

Het request:

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

Retourneert als response (omwille van beknoptheid niet volledig weergegeven) een lijst van stations gesorteerd op alfabet:

<stations>
  <station>
    <naam>'s-Gravenhage</naam>
    <code>gvc</code>
    <land>NL</land>
    <lat>52.081261</lat>
    <long>4.323973</long>
    <alias>true</alias>
  </station>
  <station>
    <naam>'s-Hertogenbosch</naam>
    <code>ht</code>
    <land>NL</land>
    <lat>51.690536</lat>
    <long>5.294790</long>
    <alias>true</alias>
  </station>
  <station>
    <naam>Almere Centrum</naam>
    <code>alm</code>
    <land>NL</land>
    <lat>52.375163</lat>
    <long>5.218921</long>
    <alias>false</alias>
  </station>
  <station>
    <naam>Almere Buiten</naam>
    <code>almb</code>
    <land>NL</land>
    <lat>52.394463</lat>
    <long>5.278339</long>
    <alias>false</alias>
  </station>
</stations>

Het attribuut alias geeft aan of het een station betreft dat met zijn officiële naam al in de lijst voorkomt, maar additioneel is opgenomen als alias (Den Bosch, Den Haag, Spoorwegmuseum etc).

Storingen en werkzaamheden

Informatie over storingen (=ongeplande storingen) en werkzaamheden (=geplande storingen) wordt opgehaald met dezelfde service. Deze service kan ook worden gebruikt voor het opvragen van de actuele storingen (zowel ongepland als gepland) voor een bepaald station. Hiervoor geldt de volgende url:

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

De meeste afnemers van de service zullen ofwel geplande of ongeplande storingen opvragen, ofwel een combinatie van de parameters gebruiken. 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.

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>

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.