ns-api 0.0.2

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/Gemfile

@@ -0,0 +1,9 @@
+source 'http://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'rspec'
+  gem 'simplecov'
+  gem 'fakeweb'
+end

data/Gemfile.lock

@@ -0,0 +1,40 @@
+PATH
+  remote: .
+  specs:
+    ns (0.0.2)
+      httpi
+      nokogiri
+      nori
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    fakeweb (1.3.0)
+    httpi (2.0.2)
+      rack
+    multi_json (1.6.0)
+    nokogiri (1.5.6)
+    nori (2.0.3)
+    rack (1.5.2)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.2)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  fakeweb
+  ns!
+  rspec
+  simplecov

data/README.md

@@ -0,0 +1,82 @@
+Ruby implementation of the NS API
+=================================
+
+Ruby implementation of the NS (Dutch Railways) API
+
+## Request an API username and password from NS
+
+Before using this gem you should request a username and password from the
+NS API pages. This allows you to authenticate your API requests and will
+make sure you get actual data back.
+
+Head over to http://www.ns.nl/api/api to request your credentials.
+
+## Configuring the gem
+
+To configure the gem, place an <tt>Ns.configure</tt> block in your code:
+
+```
+Ns.configure do |config|
+  config.username = 'john@doe.com'
+  config.password = 'your-secret-password'
+end
+```
+
+## Using the gem
+
+Currently the gem implements the following API calls:
+
+- Requesting a travel advice from one station to another
+
+Each of these calls is explained below.
+
+### Requesting a travel advice
+
+To request a travel advice you need at least the names of the departure and
+the arrival station. You may use the full string name of the station, e.g.
+"Utrecht Centraal" or the abbreviated station code, e.g. "ut".
+
+Requesting travel advice is done by creating a new <tt>Ns::Trip</tt>. A
+trip has a <tt>travel_options</tt> method that returns a collection of
+<tt>Ns::TravelOption</tt> objects. See the code for the methods these objects
+expose.
+
+```
+trip = Ns::Trip.new(from: 'Amsterdam Centraal', to: 'Ede Centrum')
+trip.travel_options # <= returns Ns::TravelOption objects
+```
+
+Optionally you may supply a desired departure or arrival time to the trip:
+
+```
+trip = Ns::Trip.new(from: 'Amsterdam Centraal', to: 'Ede Centrum', arrival: Time.now)
+trip_2 = Ns::Trip.new(from: 'Amsterdam Centraal', to: 'Ede Centrum', departure: Time.now)
+```
+
+You may also specify a <tt>via</tt> station:
+
+```
+trip = Ns::Trip.new(from: 'Amsterdam Centraal', to: 'Ede Centrum', via: 'Utrecht Centraal', arrival: Time.now)
+```
+
+The returned <tt>Ns::TravelOption</tt> objects have a <tt>optimal</tt> attribute that tells you wether or not the
+travel option is regarded as the optimal option for your trip by the NS.
+
+**Note**: the times returned by an instance of <tt>Ns::TravelOption</tt> (e.g.
+trip durations, delays) are all in seconds.
+
+### Requesting a list of interruptions
+
+Requesting disruptions requires a station. Disruptions that affect the given station will be returned:
+
+```
+disruption_collection = Ns::DisruptionCollection.new(station: 'Amsterdam Centraal')
+```
+
+An instance of <tt>Ns::DisruptionCollection</tt> has a <tt>planned_disruptions</tt> method and a <tt>unplanned_disruptions</tt>
+method. The results of these methods are <tt>Ns::Disruption</tt> objects.
+
+## Development
+
+Pull requests are welcome! To add your feature: create a fork, implement the
+feature on a topic branch, add specs and create a pull request here on Github.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/ns.rb

@@ -0,0 +1,29 @@
+require 'time'
+require 'httpi'
+require 'nori'
+
+this = Pathname.new(__FILE__).realpath
+lib_path = File.expand_path("..", this)
+$:.unshift(lib_path)
+
+$ROOT = File.expand_path("../", lib_path)
+
+require 'ns/model'
+
+Dir.glob(File.join(lib_path, '/**/*.rb')).each do |file|
+  require file
+end
+
+module Ns
+  class << self
+
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Ns::Configuration.new
+    end
+
+  end
+end

data/lib/ns/api/request/base.rb

@@ -0,0 +1,58 @@
+module Ns
+  module Api
+    module Request
+      class Base
+
+        attr_reader :response, :parsed_response
+
+        def initialize(attributes = {})
+          HTTPI.log = false
+        end
+
+        def response
+          self.class.response_class.new(parsed_response: parsed_response)
+        end
+
+        private
+
+        def url_for_request
+          http_request_with_query_and_authentication
+        end
+
+        def http_request_with_query_and_authentication
+          http_request.query = query
+          http_request.auth.basic(Ns.configuration.username, Ns.configuration.password)
+
+          http_request
+        end
+
+        def http_request
+          @http_request ||= HTTPI::Request.new(self.class.base_uri)
+        end
+
+        def parsed_response
+          @parsed_response ||= response_parser.parsed_response
+        end
+
+        def response_parser
+          @response_parser ||= Ns::Api::Response::Parser.new(response_text: response_body)
+        end
+
+        def response_body
+          @response_body ||= plain_text_response.body
+          #@response_body ||= File.read(File.join($ROOT, 'spec/fixtures/ns_travel_advice_response.xml'))
+          #@response_body ||= File.read(File.join($ROOT, 'spec/fixtures/ns_disruptions_with_results.xml'))
+        end
+
+        def plain_text_response
+          @plain_text_response ||= HTTPI.get(url_for_request)
+        end
+
+        def self.base_uri; raise "Implement me in a subclass"; end
+        def self.response_class; raise "Implement me in a subclass"; end
+        def query; raise "Implement me in a subclass"; end
+
+      end
+    end
+  end
+end

data/lib/ns/api/request/disruption_collection.rb

@@ -0,0 +1,30 @@
+module Ns
+  module Api
+    module Request
+      class DisruptionCollection < Ns::Api::Request::Base
+        include Ns::Model
+
+        attr_accessor :disruption_collection
+
+        def self.base_uri
+          'http://webservices.ns.nl/ns-api-storingen'
+        end
+
+        def self.response_class
+          Ns::Api::Response::DisruptionCollection
+        end
+
+        private
+
+        def query
+          {
+            station:   disruption_collection.station,
+            actual:    disruption_collection.actual,
+            unplanned: disruption_collection.include_planned
+          }
+        end
+
+      end
+    end
+  end
+end

data/lib/ns/api/request/travel_advice.rb

@@ -0,0 +1,34 @@
+module Ns
+  module Api
+    module Request
+      class TravelAdvice < Ns::Api::Request::Base
+        include Ns::Model
+
+        attr_accessor :trip
+
+        def self.base_uri
+          'http://webservices.ns.nl/ns-api-treinplanner'
+        end
+
+        def self.response_class
+          Ns::Api::Response::TravelAdvice
+        end
+
+        private
+
+        def query
+          {
+            fromStation: trip.from.name,
+            toStation:   trip.to.name,
+            viaStation:  trip.via.name,
+            dateTime:    trip.formatted_time,
+            departure:   trip.departure?,
+            hslAllowed:  trip.allow_hsl,
+            yearCard:    trip.year_card
+          }
+        end
+
+      end
+    end
+  end
+end

data/lib/ns/api/response/disruption_collection.rb

@@ -0,0 +1,58 @@
+module Ns
+  module Api
+    module Response
+      class DisruptionCollection
+        include Ns::Model
+
+        attr_accessor :parsed_response
+
+        def planned_disruptions
+          ( raw_disruptions['Gepland'] || [] ).map do |raw_disruption|
+            new_disruption(raw_disruption)
+          end.flatten.compact
+        end
+
+        def unplanned_disruptions
+          ( raw_disruptions['Ongepland'] || [] ).map do |raw_disruption|
+            new_disruption(raw_disruption)
+          end.flatten.compact
+        end
+
+        private
+
+        #
+        # Each disruption looks like this:
+        #
+        # [ 'Storing', { id: '12345', 'Traject': ... } ]
+        #
+        # which is why we do a check for size, shift the array, and return
+        # the first element in the array which is the actual disruption
+        # Hash
+        #
+        def new_disruption(raw_disruption)
+          if raw_disruption.size >= 2
+            raw_disruption = raw_disruption[1]
+            raw_disruption = raw_disruption[0] if raw_disruption.is_a?(Array)
+
+            Ns::Disruption.new(
+              route:   raw_disruption['Traject'],
+              reason:  raw_disruption['Reason'],
+              message: raw_disruption['Bericht'],
+              advice:  raw_disruption['Advies'],
+              period:  raw_disruption['Periode']
+            )
+          end
+        end
+
+        def raw_disruptions
+          if parsed_response.has_key?('Storingen') && ( parsed_response['Storingen'].has_key?('Gepland') || parsed_response['Storingen'].has_key?('Ongepland') )
+            parsed_response['Storingen']
+          else
+            {}
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/ns/api/response/parser.rb

@@ -0,0 +1,22 @@
+module Ns
+  module Api
+    module Response
+      class Parser
+        include Ns::Model
+
+        attr_accessor :response_text
+
+        def parsed_response
+          @parsed_response ||= parser.parse(response_text)
+        end
+
+        private
+
+        def parser
+          @parser ||= Nori.new
+        end
+
+      end
+    end
+  end
+end

data/lib/ns/api/response/travel_advice.rb

@@ -0,0 +1,46 @@
+module Ns
+  module Api
+    module Response
+      class TravelAdvice
+        include Ns::Model
+
+        attr_accessor :parsed_response
+
+        def travel_options
+          raw_travel_options.map do |travel_option|
+            Ns::TravelOption.new(
+              planned_departure: travel_option['GeplandeVertrekTijd'],
+              actual_departure:  travel_option['ActueleVertrekTijd'],
+              planned_arrival:   travel_option['GeplandeAankomstTijd'],
+              actual_arrival:    travel_option['ActueleAankomstTijd'],
+              changes:           travel_option['AantalOverstappen'],
+              platform:          platform(travel_option),
+              optimal:           travel_option['Optimaal']
+            )
+          end
+        end
+
+        private
+
+        def raw_travel_options
+          if parsed_response.has_key?('ReisMogelijkheden') && parsed_response['ReisMogelijkheden'].has_key?('ReisMogelijkheid')
+            parsed_response['ReisMogelijkheden']['ReisMogelijkheid']
+          else
+            []
+          end
+        end
+
+        def platform(travel_option)
+          travel_part = travel_option['ReisDeel']
+
+          if travel_part.is_a?(Array)
+            travel_part.first['ReisStop'].first['Spoor']
+          else
+            travel_part['ReisStop'].first['Spoor']
+          end
+        end
+
+      end
+    end
+  end
+end