Module: GoogleMapsService::DistanceMatrix

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

Overview

Performs requests to the Google Maps Distance Matrix API.

Instance Method Summary collapse

Instance Method Details

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

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

Parameters:

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

    One or more addresses and/or latitude/longitude values, 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 latitude/longitude coordinate to calculate directions.

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

    One or more addresses and/or lat/lng values, 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 latitude/longitude 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’t 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”, “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:

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



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/google_maps_service/distance_matrix.rb', line 37

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

  if mode
    # NOTE(broady): the mode parameter is not validated by the Maps API
    # server. Check here to prevent silent failures.
    unless ["driving", "walking", "bicycling", "transit"].include?(mode)
      raise ArgumentError, "Invalid travel mode."
    end
    params[:mode] = mode
  end

  params[:language] = language if language

  if avoid
    unless ["tolls", "highways", "ferries"].include?(avoid)
      raise ArgumentError, "Invalid route restriction."
    end
    params[:avoid] = avoid
  end


  params[:units] = units if units
  params[:departure_time] = convert.time(departure_time) if departure_time
  params[:arrival_time] = 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] = convert.join_list("|", transit_mode) if transit_mode
  params[:transit_routing_preference] = transit_routing_preference if transit_routing_preference

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