Module: GoogleMapsService::Apis::Directions

Included in:
Client
Defined in:
lib/google_maps_service/apis/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, response_slice: :routes) ⇒ 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`.

  • response_slice (Symbol) (defaults to: :routes) —

    Specify subset of response to return. Defaults to :routes for backwards compatibility. Use :all to get complete response.

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
100
101
102
103
 
# File 'lib/google_maps_service/apis/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, response_slice: :routes)

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

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

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

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

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

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

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

  if response_slice == :all
    get("/maps/api/directions/json", params)
  else
    get("/maps/api/directions/json", params)[response_slice]
  end
end