Travel Time Ruby SDK

Travel Time Ruby SDK helps users find locations by journey time rather than using ‘as the crow flies’ distance. Time-based searching gives users more opportunities for personalisation and delivers a more relevant search.

Installation

Add this line to your application's Gemfile:

gem 'travel_time'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install travel_time

Usage

In order to be able to call the API, you'll first need to set your Application ID and API Key:

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end

After that, you can instantiate a client to initiate the API connection:

client = TravelTime::Client.new

You can then use the client to call API endpoints:

response = client.map_info
#=> #<TravelTime::Response:0x00000001452e94b0 @status=200, @headers={...}, @body={...}

A note on Time

If you're calling an API endpoint that expects a time in "extended ISO-8601 format" ( e.g. departure_searches.departure_time), you can use the standard Ruby Time serializer:

# This require will add the #iso8601 method to Time objects
require 'time'

departure_search = {
  id: "departure search example",
  departure_location_id: "London center",
  arrival_location_ids: ["Hyde Park", "ZSL London Zoo"],
  transportation: { type: "bus" },
  departure_time: Time.now.iso8601,
  travel_time: 1800,
  properties: ["travel_time"],
  range: { enabled: true, max_results: 3, width: 600 }
}

client.time_map(departure_searches: [departure_search])

Rate Limiting

You may specify an optional rate limit when initializing your client. The rate_limit parameter sets a cap on the number of requests that can be made to the API in 60 seconds. Requests are balanced at equal intervals.

client = TravelTime::Client.new(rate_limit = 60)

Isochrones (Time Map)

Given origin coordinates, find shapes of zones reachable within corresponding travel time. Find unions/intersections between different searches.

Body attributes:

departure_searches: Searches based on departure times. Leave departure location at no earlier than given time. You can define a maximum of 10 searches
arrival_searches: Searches based on arrival times. Arrive at destination location at no later than given time. You can define a maximum of 10 searches
unions: Define unions of shapes that are results of previously defined searches.
intersections: Define intersections of shapes that are results of previously defined searches.

require 'time'
require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

departure_search1 = {
  id: "public transport from Trafalgar Square",
  coords: {
    lat: 51.506756,
    lng: -0.128050
  },
  departure_time: Time.now.iso8601,
  travel_time: 1800,
  transportation: { type: "public_transport" },
}

departure_search2 = {
  id: "driving from Trafalgar Square",
  coords: {
    lat: 51.506756,
    lng: -0.128050
  },
  departure_time: Time.now.iso8601,
  travel_time: 1800,
  transportation: { type: "driving" },
}

arrival_search = {
  id: "public transport to Trafalgar Square",
  coords: {
    lat: 51.506756,
    lng: -0.128050
  },
  arrival_time: Time.now.iso8601,
  travel_time: 1800,
  transportation: { type: "public_transport" },
  range: { enabled: true, width: 3600 }
}

union = {
  id: 'union of driving and public transport',
  search_ids: ['public transport from Trafalgar Square', 'driving from Trafalgar Square']
}

intersection = {
  id: 'intersection of driving and public transport',
  search_ids: ['public transport from Trafalgar Square', 'driving from Trafalgar Square']
}

response = client.time_map(
  departure_searches: [departure_search1, departure_search2], 
  arrival_searches: [arrival_search], 
  unions: [union], 
  intersections: [intersection]
)

puts response.body

Isochrones (Time Map) Fast

A very fast version of Isochrone API. However, the request parameters are much more limited.

require 'time'
require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

arrival_search = {
  id: "public transport to Trafalgar Square",
  coords: {
    lat: 51.506756,
    lng: -0.128050
  },
  arrival_time_period: 'weekday_morning',
  transportation: { type: "public_transport" },
  travel_time: 1800,
}

response = client.time_map_fast(
  arrival_searches: {
    one_to_many: [arrival_search]
  },
)

puts response.body

Distance Matrix (Time Filter)

Given origin and destination points filter out points that cannot be reached within specified time limit. Find out travel times, distances and costs between an origin and up to 2,000 destination points.

Body attributes:

locations: Locations to use. Each location requires an id and lat/lng values
departure_searches: Searches based on departure times. Leave departure location at no earlier than given time. You can define a maximum of 10 searches
arrival_searches: Searches based on arrival times. Arrive at destination location at no later than given time. You can define a maximum of 10 searches

require 'time'
require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

locations = [
  {
    id: 'London center',
    coords: {
      lat: 51.508930,
      lng: -0.131387
    }
  },
  {
    id: 'Hyde Park',
    coords: {
      lat: 51.508824,
      lng: -0.167093
    }
  },
  {
    id: 'ZSL London Zoo',
    coords: {
      lat: 51.536067,
      lng: -0.153596
    }
  }
]

departure_search = {
  id: 'departure search example',
  departure_location_id: 'London center',
  arrival_location_ids: ['Hyde Park', 'ZSL London Zoo'],
  transportation: { type: 'bus' },
  departure_time: Time.now.iso8601,
  travel_time: 3600,
  properties: ['travel_time'],
  range: { enabled: true, max_results: 3, width: 600 }
}

arrival_search = {
  id: 'arrival search example',
  departure_location_ids: ['Hyde Park', 'ZSL London Zoo'],
  arrival_location_id: 'London center',
  transportation: { type: 'public_transport' },
  arrival_time: Time.now.iso8601,
  travel_time: 3600,
  properties: ['travel_time', 'distance', 'distance_breakdown', 'fares']
}

response = client.time_filter(
  locations: locations, 
  departure_searches: [departure_search],
  arrival_searches: [arrival_search]
)

puts response.body

Time Filter (Fast)

A very fast version of time_filter(). However, the request parameters are much more limited. Currently only supports UK and Ireland.

require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

locations = [
  {
    id: 'London center',
    coords: {
      lat: 51.508930,
      lng: -0.131387
    }
  },
  {
    id: 'Hyde Park',
    coords: {
      lat: 51.508824,
      lng: -0.167093
    }
  },
  {
    id: 'ZSL London Zoo',
    coords: {
      lat: 51.536067,
      lng: -0.153596
    }
  }
]

arrival_many_to_one = {
  id: 'arrive-at many-to-one search example',
  departure_location_ids: ['Hyde Park', 'ZSL London Zoo'],
  arrival_location_id: 'London center',
  transportation: { type: 'public_transport' },
  arrival_time_period: 'weekday_morning',
  travel_time: 1900,
  properties: ['travel_time', 'fares']
}

arrival_one_to_many = {
  id: 'arrive-at one-to-many search example',
  arrival_location_ids: ['Hyde Park', 'ZSL London Zoo'],
  departure_location_id: 'London center',
  transportation: { type: 'public_transport' },
  arrival_time_period: 'weekday_morning',
  travel_time: 1900,
  properties: ['travel_time', 'fares']
}

arrival_searches = {
  many_to_one: [arrival_many_to_one],
  one_to_many: [arrival_one_to_many]
}

response = client.time_filter_fast(
  locations: locations,
  arrival_searches: arrival_searches
)

puts response.body

Time Filter Fast (Proto)

A fast version of time filter communicating using protocol buffers.

The request parameters are much more limited and only travel time is returned. In addition, the results are only approximately correct (95% of the results are guaranteed to be within 5% of the routes returned by regular time filter).

This inflexibility comes with a benefit of faster response times (Over 5x faster compared to regular time filter) and larger limits on the amount of destination points.

Body attributes:

origin: Origin point.
destinations: Destination points. Cannot be more than 200,000.
country: Return the results that are within the specified country.
transport: Transportation type.
traveltime: Time limit.

require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

origin = {
  lat: 51.508930,
  lng: -0.131387,
}

destinations = [{
  lat: 51.508824,
  lng: -0.167093,
}]

response = client.time_filter_fast_proto(
  country: 'UK',
  origin: origin,
  destinations: destinations,
  transport: 'driving+ferry',
  traveltime: 7200
)
puts(response.body)

The responses are in the form of a list where each position denotes either a travel time (in seconds) of a journey, or if negative that the journey from the origin to the destination point is impossible.

Routes

Returns routing information between source and destinations.

Body attributes:

locations: Locations to use. Each location requires an id and lat/lng values
departure_searches: Searches based on departure times. Leave departure location at no earlier than given time. You can define a maximum of 10 searches
arrival_searches: Searches based on arrival times. Arrive at destination location at no later than given time. You can define a maximum of 10 searches

require 'time'
require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

locations = [{
  id: 'London center',
  coords: {
    lat: 51.508930,
    lng: -0.131387
  }
},
{
  id: 'Hyde Park',
  coords: {
    lat: 51.508824,
    lng: -0.167093
  }
},
{
  id: 'ZSL London Zoo',
  coords: {
    lat: 51.536067,
    lng: -0.153596
  }
}]

departure_search = {
  id: 'departure search example',
  departure_location_id: 'London center',
  arrival_location_ids: ['Hyde Park', 'ZSL London Zoo'],
  transportation: {
    type: 'bus'
  },
  departure_time: Time.now.iso8601,
  travel_time: 1800,
  properties: ['travel_time'],
  range: {
    enabled: true,
    max_results: 3,
    width: 600
  }
}

arrival_search = {
  id: 'arrival search example',
  departure_location_ids: ['Hyde Park', 'ZSL London Zoo'],
  arrival_location_id: 'London center',
  transportation: {
    type: 'public_transport'
  },
  arrival_time: Time.now.iso8601,
  travel_time: 1800,
  properties: ['travel_time', 'distance', 'fares', 'route']
}

response = client.routes(
  locations: locations,
  departure_searches: [departure_search],
  arrival_searches: [arrival_search]
)

puts response.body

Geocoding (Search)

Match a query string to geographic coordinates.

require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

response = client.geocoding(query: 'London', within_country: 'GB')
puts response.body

Reverse Geocoding

Match a latitude, longitude pair to an address.

require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

response = client.reverse_geocoding(lat: 51.506756, lng: -0.128050)
puts response.body

Time Filter (Postcodes)

Find reachable postcodes from origin (or to destination) and get statistics about such postcodes. Currently only supports United Kingdom.

require 'time'
require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

departure_search = {
  id: 'public transport from Trafalgar Square',
  departure_time: Time.now.iso8601,
  travel_time: 1800,
  coords: { lat: 51.507609, lng: -0.128315 },
  transportation: { type: 'public_transport' },
  properties: ['travel_time', 'distance']
}

arrival_search = {
  id: 'public transport to Trafalgar Square',
  arrival_time: Time.now.iso8601,
  travel_time: 1800,
  coords: { lat: 51.507609, lng: -0.128315 },
  transportation: { type: 'public_transport' },
  properties: ['travel_time', 'distance']
}

response = client.time_filter_postcodes(
  departure_searches: [departure_search], 
  arrival_searches: [arrival_search]
)

puts response.body

Time Filter (Postcode Districts)

Find reachable postcodes from origin (or to destination) and get statistics about such postcodes. Currently only supports United Kingdom.

require 'time'
require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

departure_search = {
  id: 'public transport from Trafalgar Square',
  departure_time: Time.now.iso8601,
  travel_time: 1800,
  coords: { lat: 51.507609, lng: -0.128315 },
  transportation: { type: 'public_transport' },
  properties: ['coverage', 'travel_time_reachable', 'travel_time_all'],
  reachable_postcodes_threshold: 0.1
}

arrival_search = {
  id: 'public transport to Trafalgar Square',
  arrival_time: Time.now.iso8601,
  travel_time: 1800,
  coords: { lat: 51.507609, lng: -0.128315 },
  transportation: { type: 'public_transport' },
  properties: ['coverage', 'travel_time_reachable', 'travel_time_all'],
  reachable_postcodes_threshold: 0.1
}

response = client.time_filter_postcode_districts(
  departure_searches: [departure_search],
  arrival_searches: [arrival_search]
)

puts response.body

Time Filter (Postcode Sectors)

Find sectors that have a certain coverage from origin (or to destination) and get statistics about postcodes within such sectors. Currently only supports United Kingdom.

require 'time'
require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

departure_search = {
  id: 'public transport from Trafalgar Square',
  departure_time: Time.now.iso8601,
  travel_time: 1800,
  coords: { lat: 51.507609, lng: -0.128315 },
  transportation: { type: 'public_transport' },
  properties: ['coverage', 'travel_time_reachable', 'travel_time_all'],
  reachable_postcodes_threshold: 0.1
}

arrival_search = {
  id: 'public transport to Trafalgar Square',
  arrival_time: Time.now.iso8601,
  travel_time: 1800,
  coords: { lat: 51.507609, lng: -0.128315 },
  transportation: { type: 'public_transport' },
  properties: ['coverage', 'travel_time_reachable', 'travel_time_all'],
  reachable_postcodes_threshold: 0.1
}

response = client.time_filter_postcode_sectors(
  departure_searches: [departure_search],
  arrival_searches: [arrival_search]
)

puts response.body

Map Info

Get information about currently supported countries.

require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

response = client.map_info
puts response.body

Supported Locations

Find out what points are supported by the api.

require 'travel_time'

TravelTime.configure do |config|
  config.application_id = 'YOUR_APP_ID'
  config.api_key = 'YOUR_APP_KEY'
end
client = TravelTime::Client.new

locations = [{
  id: "Kaunas",
  coords: {
    lat: 54.900008,
    lng: 23.957734
  }
},
{
  id: "London",
  coords: {
    lat: 51.506756,
    lng: -0.128050
  }
},
{
  id: "Bangkok",
  coords: {
    lat: 13.761866,
    lng: 100.544818
  }
},
{
  id: "Tbilisi",
  coords: {
    lat: 41.716667,
    lng: 44.783333
  }
}]

response = client.supported_locations(locations: locations)

puts response.body