traveltime-api-ruby 1.0.0

data/lib/traveltime_api.rb

@@ -0,0 +1,190 @@
+require 'rest-client'
+require 'json'
+
+# Class for using TravelTime API service. Learn more about TravelTime at
+# www.traveltimeapp.com
+#
+# ## Defined types ##
+#
+# * TransportationMode - string with one of following values:
+# "walking", "driving", "walking_train", "walking_bus", "public_transport"
+#
+# * EdgeType - describes type of the edge. String with one of following values:
+# "car", "walk", "train", "bus", "cable_car", "plane", "ship"
+#
+# ## Thrown errors ##
+#
+# Each method that does a call to the server can raise TravelTimeAPI::BadRequest 
+# or TravelTimeAPI::ServerError errors.
+#
+class TravelTimeAPI
+  DEFAULT_URL = "http://api.traveltimeapp.com"
+
+  # Raised if API user made bad request.
+  class BadRequest < RuntimeError
+    # Server provided String code for this error.
+    attr_reader :code
+    # Server provided String explanation of error.
+    attr_reader :details
+
+    def initialize(code, details)
+      @code = code
+      @details = details
+    end
+
+    def to_s
+      "TravelTimeAPI::BadRequest[#{@code}: #{details}]"
+    end
+  end
+
+  # Raised if API server has encountered an error.
+  class ServerError < RuntimeError
+    # Human readable error message.
+    attr_reader :error
+
+    def initialize(error)
+      @error = error
+    end
+
+    def to_s
+      "TravelTimeAPI::ServerError[#{@error}]"
+    end
+  end
+
+  # Represents that API does not have data for this point/region.
+  class NoData < RuntimeError; end
+
+  # Result of #time_filter method.
+  #
+  # @param points [Hash] {"id1" => time_in_seconds, ...}
+  # @param accuracy [Symbol] :exact or :approx. Decrease travel time to switch
+  # from approximate to exact accuracy.
+  class TimeFilterResult < Struct.new(:points, :accuracy); end
+
+  # Result of #time_map method.
+  #
+  # @param shape [Array] array of polylines that represent areas reachable by given time.
+  # [Cluster, Cluster, ...], where Cluster is [[lat, lon], [lat, lon], ...]
+  # @param accuracy [Symbol] :exact or :approx. Decrease travel time to switch
+  # from approximate to exact accuracy.
+  class TimeMapResult < Struct.new(:shape, :accuracy); end
+
+  # Result of #routes method.
+  #
+  # * RouteDescriptionPart is a structure describing one part of the route:
+  # {
+  #   "mode": EdgeType,
+  #   # Array of coordinates for this route part. Can be used to draw a polyline
+  #   # on a map.
+  #   "coords": [[lat, lon], [lat, lon], [lat, lon], ...],
+  #   "directions: String, # textual description in english of this route part
+  #   "distance": Int, # distance covered in metres for this route part
+  #   "time": Int # time taken to travel through this route part in seconds
+  # }
+  #
+  # @param routes [Hash] {"id1" -> [RouteDescriptionPart, RouteDescriptionPart, ...], ...}
+  class RoutesResult < Struct.new(:routes); end
+
+  # Initializes API. You need to specify your API key here.
+  def initialize(api_key, url=DEFAULT_URL)
+    @api_key = api_key
+    @url = url
+  end
+
+  # Takes input parameters and returns how long does it take to reach each point
+  # in chosen mode of transportation (in seconds).
+  #
+  # Points whose travel times which exceed _travel_time_ are not included in the
+  # result.
+  #
+  # @param start_time [Time] Time moment when we start our search.
+  # @param travel_time [Int] Max time in seconds to the point.
+  # @param mode [String] Transportation mode. See class documentation for info.
+  # @param origin [Array] [latitude, longtitude]
+  # @param points [Hash] Points th{"id1" => [latitude, longtitude], ...}
+  # @return [TravelTimeAPI::TimeFilterResult]
+  def time_filter(start_time, travel_time, mode, origin, points)
+    request = {
+      :start_time => format_time(start_time),
+      :travel_time => travel_time,
+      :mode => mode,
+      :origin => origin,
+      :points => points
+    }
+
+    response = post("/v2/time_filter", request)
+    TimeFilterResult.new(response["times"], response["accuracy"].to_sym)
+  end
+
+  # Takes input parameters and returns polylines for each cluster that you can
+  # reach by given time.
+  #
+  # @param start_time [Time] Time moment when we start our search.
+  # @param travel_time [Int] Max time in seconds to the point.
+  # @param mode [String] Transportation mode. See class documentation for info.
+  # @param origin [Array] [latitude, longtitude]
+  # @param smooth [Boolean] Shall the returned shaped be smoothed?
+  # @return [TravelTimeAPI::TimeMapResult]
+  def time_map(start_time, travel_time, mode, origin, smooth)
+    request = {
+      :start_time => format_time(start_time),
+      :travel_time => travel_time,
+      :mode => mode,
+      :origin => origin,
+      :smooth => smooth
+    }
+
+    response = post("/v2/time_map", request)
+    TimeMapResult.new(response["shape"], response["accuracy"].to_sym)
+  end
+
+  # Takes input parameters and returns routes to each of the points within 
+  # travel_time.
+  #
+  # Input parameters are the same as #travel_time.
+  # @return [TravelTimeAPI::RoutesResult]
+  def routes(start_time, travel_time, mode, origin, points)
+    request = {
+      :start_time => format_time(start_time),
+      :travel_time => travel_time,
+      :mode => mode,
+      :origin => origin,
+      :points => points
+    }
+
+    response = post("/v2/routes", request)
+    RoutesResult.new(response)
+  end
+
+private
+
+  def format_time(time)
+    time.strftime("%FT%T%:z")
+  end
+
+  def post(action, request)
+    response = RestClient.post(
+      @url + action,
+      request.merge(:api_key => @api_key).to_json,
+      :content_type => :json
+    )
+    json = JSON.parse(response)
+    case json["code"]
+    when "no-data"
+      raise NoData
+    when nil
+      json
+    else
+      raise ServerError.new(
+        "code: #{json["code"]}, details: #{json["details"]}"
+      )
+    end
+  rescue RestClient::ExceptionWithResponse => e
+    raise ServerError.new(
+      "server error, http_status: #{e.http_code}, http_body: #{e.http_body}"
+    )
+  rescue JSON::ParserError => e
+    raise ServerError.new("Cannot parse server response as JSON", response)
+  end
+
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: traveltime-api-ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Artūras Šlajus
+- IGeolise
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.6.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.6.7
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+description: ''
+email:
+- arturas@igeolise.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/traveltime_api.rb
+homepage: http://traveltimeapp.com
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Simple wrapper for TravelTime REST API.
+test_files: []