Class: TravelTimeAPI

Inherits:
Object
  • Object
show all
Defined in:
lib/traveltime_api.rb

Overview

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.

Defined Under Namespace

Classes: Auth, BadRequest, NoData, OutOfReach, RoutesResult, ServerError, TimeFilterResult, TimeMapResult

Constant Summary collapse

DEFAULT_URL = 
"http://api.traveltimeapp.com"
OUT_OF_REACH_CODE = 
"out-of-reach"
NO_DATA_CODE = 
"no-data"

Instance Method Summary collapse

Constructor Details

#initialize(auth, url = DEFAULT_URL) ⇒ TravelTimeAPI

Initializes API. You need to specify your auth here.

Example:

api = TravelTimeAPI.new(TravelTimeAPI::Auth.new(app_id, app_key))



110
111
112
113
 
# File 'lib/traveltime_api.rb', line 110

def initialize(auth, url=DEFAULT_URL)
  @auth = auth
  @url = url
end

Instance Method Details

#has_data?(lat, lng) ⇒ Symbol

Given latitude and longtitude of a point return whether TravelTime has data for those coordinates or not.

WARNING: even though ending in ? this method does not return a boolean value and you cannot use it directly in boolean expressions!

This is due to the fact that is needs to return 3 possible outcomes:

  • :data - we have data for this point

  • :out_of_reach - we have a data set for this point but we couldn’t attach

that point exactly to any significant roads or routes.

  • :no_data - we do not have any data for this point.

Parameters:

  • lat (Float)
  • lng (Float)

Returns:

  • (Symbol) 


130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/traveltime_api.rb', line 130

def has_data?(lat, lng)
  request = {:coords => [lat, lng]}
  response = raw_post("/has_data", request)
  if response["has"] == true
    :data
  elsif response["code"] == OUT_OF_REACH_CODE
    :out_of_reach
  elsif response["code"] == NO_DATA_CODE
    :no_data
  else
    json_error(response)
  end
end

#routes(start_time, travel_time, mode, origin, points) ⇒ TravelTimeAPI::RoutesResult

Takes input parameters and returns routes to each of the points within travel_time.

Input parameters are the same as #travel_time.

Returns:



211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/traveltime_api.rb', line 211

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

#time_filter(start_time, travel_time, modes, origin, points, properties = [:time]) ⇒ Hash

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.

Parameters:

  • start_time (Time) —

    Time moment when we start our search.

  • travel_time (Int) —

    Max time in seconds to the point.

  • modes (Array) —

    Array of transportation modes you want calculated. See class documentation for transportation mode info.

  • origin (Array) —
    latitude, longtitude
  • points (Hash) —

    Points th=> [latitude, longtitude], …

  • properties (Array) (defaults to: [:time]) —

    array of requested point properties. Valid values: :time, :distance. :distance cannot be used with any mode that involves public transport as the results will be 0.

Returns:

  • (Hash) —

    => TravelTimeAPI::TimeFilterResult, …



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/traveltime_api.rb', line 160

def time_filter(start_time, travel_time, modes, origin, points, properties=[:time])
  modes = Array(modes)
  request = {
    :start_time => format_time(start_time),
    :travel_time => travel_time,
    :modes => modes,
    :origin => origin,
    :points => points,
    :properties => properties
  }

  response = post("/v2/time_filter", request)
  response.inject({}) do |hash, (mode, ranked)|
    hash[mode] = TimeFilterResult.new(ranked["times"], ranked["accuracy"].to_sym)
    hash
  end
end

#time_map(start_time, travel_time, mode, origin, smooth, max_points = nil) ⇒ TravelTimeAPI::TimeMapResult

Takes input parameters and returns polylines for each cluster that you can reach by given time.

for no limit, Fixnum for limit. Minimum of 4 points required!

Parameters:

  • start_time (Time) —

    Time moment when we start our search.

  • travel_time (Int) —

    Max time in seconds to the point.

  • mode (String) —

    Transportation mode. See class documentation for info.

  • origin (Array) —
    latitude, longtitude
  • smooth (Boolean) —

    Shall the returned shaped be smoothed?

  • max_points (Fixnum) (defaults to: nil) —

    Maximum number of points in returned polygons. nil

Returns:

Raises:

  • (ArgumentError) 


189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/traveltime_api.rb', line 189

def time_map(start_time, travel_time, mode, origin, smooth, max_points=nil)
  raise ArgumentError.new("At least 4 points are required in max_points!") \
    unless max_points.nil? || max_points >= 4

  request = {
    :start_time => format_time(start_time),
    :travel_time => travel_time,
    :mode => mode,
    :origin => origin,
    :smooth => smooth,
    :max_points => max_points
  }

  response = post("/v2/time_map", request)
  TimeMapResult.new(response["shape"], response["accuracy"].to_sym)
end