Goal

I'd like to write a comprehensive, yet very thin implementation of the NS API.

Currently this gem supports

fetching all stations
fetching disruptions
fetching prices (you need to have a contract with NS for this)

Usage

First, make sure you have a username and password from the NS API website. (at: http://www.ns.nl/api)

You can use the NSYAPI singleton, you can configure it by using a configuration block:

require 'ns_client'

NSYapi::configure do |config|
  config.username = "some-username"
  config.password = "some-password"
end

client = NSYapi::client

client.stations

or, you can instantiate the NSClient yourself, providing a username and password. You can then regulate the instance yourself.

require 'ns_client'

# get username/password from NS site
client = NSClient.new("my-username", "my-password")

After you have created a client, you can use it for several operations

Retrieve all stations

# get all known stations
stations = client.stations
station = stations.first
station.name # 's-Hertogenbosch
station.lat # 51.69048
station.long # 5.29362

If you find it too tedious ploughing through all objects in the array, you can also use the stations_short method. This will return a hash with the station code as key, the value is an array with the name and country of the station.

client.stations_short
 => {"HT"=>["'s-Hertogenbosch", "NL"], "HTO"=>["Hertogenbosch O.", "NL"], "HDE"=>["'t Harde", "NL"], "AHBF"=>["Aachen", "D"], "ARE"=>["Aachen R. Erde", "D"], "ASCH"=>["Aachen Schanz", "D"], "AW"=>["Aachen-West", "D"], "ATN"=>["Aalten", "NL"], "AC"=>["Abcoude", "NL"], "EAHS"=>["Ahaus", "D"], "AIME"=>["Aime-la-Plagne", "F"], "AIXTGV"=>["Aix-en-Provence", "F"], "AKM"=>["Akkrum", "NL"], "ALBERT"=>["Albertville", "F"], "ALESS"=>["Alessandria", "I"], "AMR"=>["Alkmaar", "NL"], "AMRN"=>["Alkmaar Noord", "NL"], "AML"=>["Almelo", "NL"], "AMRI"=>["Almelo de Riet", "NL"], "ALMB"=>["Almere Buiten", "NL"], "ALM"=>["Almere C.", "NL"], "ALMM"=>["Muziekwijk", "NL"], "ALMO"=>["Oostvaarders", "NL"], "ALMP"=>["Parkwijk", "NL"], "AMPO"=>["Poort", "NL"], "APN"=>["Alphen a/d Rijn", "NL"], "EABG"=>["Altenberge", "D"], "AMF"=>["Amersfoort", "NL"], "AMFS"=>["Schothorst", "NL"]....

Retrieve disruptions

# get all known disruptions
disruptions = client.disruptions

# get planned disruptions
planned = disruptions[:planned]

# get unplanned disruptions
unplanned = disruptions[:unplanned]

# get disruptions from specific station, ie Amsterdam (case insensitive)
disruptions = client.disruptions "Amsterdam"

# will raise an NSClient::InvalidStationNameError error when station name is invalid
client.disruptions "bla" # NSClient::InvalidStationNameError: Could not find a station with name 'bla'

Retrieve prices

Prices can be retrieved by using a valid from,to,via parameter. You can use the name of the station or the code. (as you can see above with the stations calls)

# retrieving prices requires a from and to at minimum. Which assumes prices for today
prices = client.prices from: "Amsterdam Centraal", to: "Purmerend"

# if you'd rather retrieve prices for a specific date, this is an optional parameter. If not given, today is assumed.
tomorrow = Date.today + 1.day
prices_tomorrow = client.prices from: "Amsterdam Centraal", to: "Purmerend", date: tomorrow

# you can specify a via option, this is also optional
prices_via = client.prices from: "Amsterdam Centraal", to: "Purmerend", via: "Zaandam"

# retrieve prices for tomorrow, via specific station
prices_via_tomorrow = client.prices from: "Amsterdam Centraal", to: "Purmerend", via: "Zaandam", date: tomorrow

# Using an invalid station name will result in a...
# NSClient::InvalidStationNameError: 'Amsterdam' is not a valid station name
prices = client.prices from: "Amsterdam", to "Purmerend"

Prices Response data

A prices response is an object PricesResponse, which contains tariffunits (a measurement for cost-distance) and a hash with prices.

Each key in this hash is the type of prices (ie 'Dagretour', or 'Enkele reis').

In case different types would be added by the NS, than this API will simply add them to the hash, which makes it quite flexible.

prices = client.prices from: "Amsterdam Centraal", to: "Purmerend"

# show tarif units (tariefeenheden)
prices.tariff_units # 10

# show prices for "Dagretour", easy method
dagretour_prices = prices.dagretour # is same as prices.products["Dagretour"]

# first price for "Dagretour", contains three values
dagretour_prices[0].type # vol tarief
dagretour_prices[0].train_class # "2"
dagretour_prices[0].amount # 2.40

# show prices for "Enkele reis", easy method
enkelereis_prices = prices.enkelereis

ns-yapi