Module: GoogleMapsApis::Services::Directions

Included in:
Client
Defined in:
lib/google_maps_apis/services/directions.rb

Overview

Performs requests to the Google Maps Directions API.

Instance Method Summary collapse

Instance Method Details

#directions(origin, destination, mode: nil, waypoints: nil, alternatives: false, avoid: nil, language: nil, units: nil, region: nil, departure_time: nil, arrival_time: nil, optimize_waypoints: false, transit_mode: nil, transit_routing_preference: nil) ⇒ Array

Get directions between an origin point and a destination point.

Examples:

Simple directions

routes = client.directions('Sydney', 'Melbourne')

Complex bicycling directions

routes = client.directions('Sydney', 'Melbourne',
    mode: 'bicycling',
    avoid: ['highways', 'tolls', 'ferries'],
    units: 'metric',
    region: 'au')

Public transportation directions

an_hour_from_now = Time.now - (1.0/24)
routes = client.directions('Sydney Town Hall', 'Parramatta, NSW',
    mode: 'transit',
    arrival_time: an_hour_from_now)

Walking with alternative routes

routes = client.directions('Sydney Town Hall', 'Parramatta, NSW',
   mode: 'walking',
   alternatives: true)

Parameters:

  • origin (String, Hash, Array) —

    The address or latitude/longitude value from which you wish to calculate directions.

  • destination (String, Hash, Array) —

    The address or latitude/longitude value from which you wish to calculate directions.

  • mode (String) (defaults to: nil) —

    Specifies the mode of transport to use when calculating directions. One of driving, walking, bicycling or transit.

  • waypoints (Array<String>, Array<Hash>, Array<Array>) (defaults to: nil) —

    Specifies an array of waypoints. Waypoints alter a route by routing it through the specified location(s).

  • alternatives (Boolean) (defaults to: false) —

    If True, more than one route may be returned in the response.

  • avoid (Array, String) (defaults to: nil) —

    Indicates that the calculated route(s) should avoid the indicated features.

  • language (String) (defaults to: nil) —

    The language in which to return results.

  • units (String) (defaults to: nil) —

    Specifies the unit system to use when displaying results. metric or imperial.

  • region (String) (defaults to: nil) —

    The region code, specified as a ccTLD (top-level domain) two-character value.

  • departure_time (Integer, DateTime) (defaults to: nil) —

    Specifies the desired time of departure.

  • arrival_time (Integer, DateTime) (defaults to: nil) —

    Specifies the desired time of arrival for transit directions. Note: you can not specify both departure_time and arrival_time.

  • optimize_waypoints (Boolean) (defaults to: false) —

    Optimize the provided route by rearranging the waypoints in a more efficient order.

  • transit_mode (String, Array<String>) (defaults to: nil) —

    Specifies one or more preferred modes of transit. This parameter may only be specified for requests where the mode is transit. Valid values are bus, subway, train, tram or rail. rail is equivalent to ["train", "tram", "subway"].

  • transit_routing_preference (String) (defaults to: nil) —

    Specifies preferences for transit requests. Valid values are less_walking or fewer_transfers.

Returns:

  • (Array) —

    Array of routes.



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/google_maps_apis/services/directions.rb', line 62

def directions(origin, destination,
    mode: nil, waypoints: nil, alternatives: false, avoid: nil,
    language: nil, units: nil, region: nil, departure_time: nil,
    arrival_time: nil, optimize_waypoints: false, transit_mode: nil,
    transit_routing_preference: nil)

  params = {
    origin: GoogleMapsApis::Convert.waypoint(origin),
    destination: GoogleMapsApis::Convert.waypoint(destination)
  }

  params[:mode] = GoogleMapsApis::Validator.travel_mode(mode) if mode

  if waypoints = waypoints
    waypoints = GoogleMapsApis::Convert.as_list(waypoints)
    waypoints = waypoints.map { |waypoint| GoogleMapsApis::Convert.waypoint(waypoint) }
    waypoints = ['optimize:true'] + waypoints if optimize_waypoints

    params[:waypoints] = GoogleMapsApis::Convert.join_list("|", waypoints)
  end

  params[:alternatives] = 'true' if alternatives
  params[:avoid] = GoogleMapsApis::Convert.join_list('|', avoid) if avoid
  params[:language] = language if language
  params[:units] = units if units
  params[:region] = region if region
  params[:departure_time] = GoogleMapsApis::Convert.time(departure_time) if departure_time
  params[:arrival_time] = GoogleMapsApis::Convert.time(arrival_time) if arrival_time

  if departure_time and arrival_time
    raise ArgumentError, 'Should not specify both departure_time and arrival_time.'
  end

  params[:transit_mode] = GoogleMapsApis::Convert.join_list("|", transit_mode) if transit_mode
  params[:transit_routing_preference] = transit_routing_preference if transit_routing_preference

  return get('/maps/api/directions/json', params)[:routes]
end