oisin / ierail

Ruby wrapper for the Irish Rail real-time train information API

Irish Rail API Ruby Wrapper

I wrote most of this on the train, as is appropriate.

It's a trivial wrapper for the Irish Rail real time (whut?) train times system, in Ruby. It uses the HTTP GET API that was thankfully supplied along with the more interesting SOAP API, so a tiddly simple set up with RestClient and Nokogiri (two of my favourite things ever) to pull and process the XML data into Hashes for great value.

Usage

Grab the IERail gem

$ gem install ierail

require 'ierail'

ir = IERail.new

Find all Southbound trains serving Clongriffin station

trains = ir.southbound_from('clongriffin')

Find all trains serving Clongriffin in the next 30 minutes

trains = ir.station_times('clongriffin', 30)

trains.each { |t| p t.inspect }

Find all Northbound trains serving Clongriffin before / after a certain time

trains = ir.northbound_from('clongriffin').after('HH:MM')
trains = ir.northbound_from('clongriffin').before('HH:MM')

NB: "HH:MM" must be soon, as the API, by default, returns upcoming arrivals

Find all Southbound trains from Malahide in the next N minutes

trains = ir.southbound_from('malahide').in(N)

Find out information for a specific train

trains = ir.station_times('clongriffin', 60)

trains.first.last_location # "Arrived Harmonstown"

trains.first.origin # {:name=>"Greystones", :time=>2013-05-13 22:10:00 +0100}

trains.first.destination # {:name=>"Malahide", :time=>2013-05-13 22:10:00 +0100}

trains.first.arrival # {:scheduled=>2013-05-13 22:09:00 +0100, :expected=>2013-05-13 22:10:00 +0100}

trains.first.departure # {:scheduled=>2013-05-13 22:09:00 +0100, :expected=>2013-05-13 22:10:00 +0100}

trains.first.duein # "2"

trains.first.late? # 0 || 1

Find out the movements of a specific train

trains = ir.station_times('clongriffin', 60)

train_code = trains.first.code

train_movements = ir.train_movements(train_code) # Gets the movements of the train for today
train_movements = ir.train_movements(train_code, date) # Gets the movements of train for some date

fourth_stop = train_movements.at(4)

fourth_stop.location #{:code => "GRGD", :location_full_name => "Clongriffin", :stop_number => 4, :location_type => "S"}

fourth_stop.arrival # {:scheduled=>2013-05-13 22:09:00 +0100, :expected=>2013-05-13 22:10:00 +0100, :actual=2013-05-13 22:10:00 +0100}

fourth_stop.departure # {:scheduled=>2013-05-13 22:09:00 +0100, :expected=>2013-05-13 22:10:00 +0100, :actual=2013-05-13 22:10:00 +0100}

fourth_stop.train #{:code => "E808", :date => 2013-05-13 22:09:00 +0100, :origin => "Malahide"}

Check the main.rb for additional usage.

Development

Testing

Rather than having the test suite hit the API, this project is using VCR alongside Timecop to use stubbed responses.
These responses are stored in the fixtures/vcr_cassettes directory and can be updated by running

1. rm -r fixtures
2. rake test

As the API functionality is highly time dependent, Timecop is used to set/freeze time so that we can run time based queries on the older fixture data.

---

Pull requests welcome, because there's damn all in it at the moment. Please accompany the pull request with an appropriate test, and if you can, an example here in the README.

ierail's Issues

Difference between station(station_name).in(mins) and station_times(station_name, mins)

We have a very occasional bug stemming from a difference in the results of these two calls:

require 'ierail'
ie = IERail.new
t1 = ie.station_times('Dublin Connolly', 30)
t2 = ie.station('Dublin Connolly').in(30)
t1.count.eql?(t2.count) # should be the same, but occasionally not

Occasionally t2 is a larger set of trains than t1, but as t1 is the one that's returned via the API w/o our filtering, I feel we should respect that, i.e. t1 should be equivalent to t2.

This appears to be solved by changing the 'in' filter to work off the trains due_in time, however it's a very intermittent failure, with a very short duration, so I'm still working on a fix.

If working off the due_in time isn't suitable, let me know what's appropriate.

API supports querying trains within the next X minutes

We used to filter trains based on parsing the time attribute, but the API now appears to support passing in the minutes as a parameter.

http://api.irishrail.ie/realtime/realtime.asmx/getStationDataByNameXML?StationDesc=Bayside&NumMins=20

More sample code please

There's not enough sample code here on how to use the API.

Test suite hits the API

This makes for a slow rake test and will probably return weird results after midnight (or whenever the last trains are).

Will lob in some stubbed responses or VCR when I get a few minutes :)

Times do not have timezone data associated with them

Look at the data that's the results for trains - no sign of a timezone anywhere. This is an issue if you are running the Gem globally, but worse it means that the damn tests won't pass in Travis - because it's running in a different TZ.

[#<StationData:0x007fc18ba51618
  @destination="Dublin Pearse",
  @destination_time="10:38",
  @direction="Southbound",
  @duein="24",
  @exparrival="10:20",
  @expdepart="10:20",
  @last_location="Departed Balbriggan",
  @late="2",
  @origin="Drogheda",
  @origin_time="09:35",
  @query_time="09:56:02",
  @scharrival="10:18",
  @schdepart="10:18",
  @servertime="2013-05-11T09:56:02.613",
  @station_code="GRGRD",
  @station_name="Clongriffin",
  @status="En Route",
  @train_date="11 May 2013",
  @train_type="Train",
  @traincode="P608">,
 #<StationData:0x007fc18ba51280
  @destination="Bray",
  @destination_time="11:39",
  @direction="Southbound",
  @duein="41",
  @exparrival="10:36",
  @expdepart="10:37",
  @last_location=nil,
  @late="0",
  @origin="Malahide",
  @origin_time="10:30",
  @query_time="09:56:02",
  @scharrival="10:36",
  @schdepart="10:37",
  @servertime="2013-05-11T09:56:02.613",
  @station_code="GRGRD",
  @station_name="Clongriffin",
  @status="No Information",
  @train_date="11 May 2013",
  @train_type="DART",
  @traincode="E243">,
 #<StationData:0x007fc18ba50e70
  @destination="Dublin Connolly",
  @destination_time="11:30",
  @direction="Southbound",
  @duein="82",
  @exparrival="11:17",
  @expdepart="11:18",
  @last_location=nil,
  @late="0",
  @origin="Dundalk",
  @origin_time="10:10",
  @query_time="09:56:02",
  @scharrival="11:17",
  @schdepart="11:18",
  @servertime="2013-05-11T09:56:02.613",
  @station_code="GRGRD",
  @station_name="Clongriffin",
  @status="No Information",
  @train_date="11 May 2013",
  @train_type="Train",
  @traincode="P703">]

URI encode station names

Station names need to be URI encoded before sending the req.

Calls like ir.southbound_from('Howth Junction') break, but 'Howth%20Junction' works.

Fail in test potentially due to Irish Rail API Change

Irish Rail API has changed, somewhere, so the test suite is throwing an error. Not sure what the change is at this point in time, but an iOS app I have for DART times has stopped functioning correctly when filtering northbound from southbound.

Review and standardize API attribute names for 0.4

We've got some mixed naming of attributes that should be made consistent across the API surface before we jump to the next minor API number. Some attributes have awkward or non-describing names that should be clarified.

For example

traincode should be train_code to gibe with the other attributes.

schdepart should be scheduled_departure

Some WS messages not covered

Still to be done.

Need to find out what the train and station types are

• getAllStationsXML_WithStationType
• getCurrentTrainsXML_WithTrainType

Probably don't need support for these methods directly - just use them internally, or alternatively supply the codes as constants

• getStationDataByCodeXML
• getStationDataByCodeXML_WithNumMins

This one does a partial string match on the station name and returns the results as station name and code, useful

• getStationsFilterXML

Gets the times and details of a train's route - uses the train code, which you can get from one of the getCurrentTrainsXML methods

• getTrainMovementsXML