Module: GoogleMapsService::Apis::DistanceMatrix

Included in:
Client
Defined in:
lib/google_maps_service/apis/distance_matrix.rb

Overview

Performs requests to the Google Maps Distance Matrix API.

Instance Method Summary collapse

Instance Method Details

#distance_matrix(origins, destinations, mode: nil, language: nil, avoid: nil, units: nil, departure_time: nil, arrival_time: nil, transit_mode: nil, transit_routing_preference: nil) ⇒ Hash

Gets travel distance and time for a matrix of origins and destinations.

Examples:

Simple distance matrix

origins = ["Perth, Australia", "Sydney, Australia",
           "Melbourne, Australia", "Adelaide, Australia",
           "Brisbane, Australia", "Darwin, Australia",
           "Hobart, Australia", "Canberra, Australia"]
destinations = ["Uluru, Australia",
                "Kakadu, Australia",
                "Blue Mountains, Australia",
                "Bungle Bungles, Australia",
                "The Pinnacles, Australia"]
matrix = client.distance_matrix(origins, destinations)

Complex distance matrix

origins = ["Bobcaygeon ON", [41.43206, -81.38992]]
destinations = [[43.012486, -83.6964149], {lat: 42.8863855, lng: -78.8781627}]
matrix = client.distance_matrix(origins, destinations,
    mode: 'driving',
    language: 'en-AU',
    avoid: 'tolls',
    units: 'imperial')

Parameters:

  • origins (Array) —

    One or more addresses and/or lat/lon pairs, from which to calculate distance and time. If you pass an address as a string, the service will geocode the string and convert it to a lat/lon coordinate to calculate directions.

  • destinations (Array) —

    One or more addresses and/or lat/lon pairs, to which to calculate distance and time. If you pass an address as a string, the service will geocode the string and convert it to a lat/lon coordinate to calculate directions.

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

    Specifies the mode of transport to use when calculating directions. Valid values are ‘driving`, `walking`, `transit` or `bicycling`.

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

    The language in which to return results.

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

    Indicates that the calculated route(s) should avoid the indicated features. Valid values are ‘tolls`, `highways` or `ferries`.

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

    Specifies the unit system to use when displaying results. Valid values are ‘metric` or `imperial`.

  • 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`.

  • 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:

  • (Hash) —

    Matrix of distances. Results are returned in rows, each row containing one origin paired with each destination.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/google_maps_service/apis/distance_matrix.rb', line 56

def distance_matrix(origins, destinations,
  mode: nil, language: nil, avoid: nil, units: nil,
  departure_time: nil, arrival_time: nil, transit_mode: nil,
  transit_routing_preference: nil)
  params = {
    origins: GoogleMapsService::Convert.waypoints(origins),
    destinations: GoogleMapsService::Convert.waypoints(destinations)
  }

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

  params[:units] = units if units
  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

  get("/maps/api/distancematrix/json", params)
end