google_map_services 0.1.0.0

data/README.md

@@ -0,0 +1,377 @@
+# Ruby gem for Google Maps APIs
+
+[![Gem Version](https://badge.fury.io/rb/google_maps_service.svg)](http://badge.fury.io/rb/google_maps_service) [![Build Status](https://travis-ci.org/edwardsamuel/google-maps-services-ruby.svg?branch=master)](https://travis-ci.org/edwardsamuel/google-maps-services-ruby) [![Dependency Status](https://gemnasium.com/edwardsamuel/google-maps-services-ruby.svg)](https://gemnasium.com/edwardsamuel/google-maps-services-ruby) [![Code Climate](https://codeclimate.com/github/edwardsamuel/google-maps-services-ruby/badges/gpa.svg)](https://codeclimate.com/github/edwardsamuel/google-maps-services-ruby) [![Coverage Status](https://coveralls.io/repos/edwardsamuel/google-maps-services-ruby/badge.svg?branch=master&service=github)](https://coveralls.io/github/edwardsamuel/google-maps-services-ruby?branch=master) [![Inch CI](https://inch-ci.org/github/edwardsamuel/google-maps-services-ruby.svg?branch=master)](https://inch-ci.org/github/edwardsamuel/google-maps-services-ruby?branch=master)
+
+![Analytics](https://ga-beacon.appspot.com/UA-66926725-1/google-maps-services-ruby/readme?pixel)
+
+*This gem is ported from [Python Client for Google Maps Services](https://github.com/googlemaps/google-maps-services-python).*
+
+## Description
+
+Use Ruby? Want to [geocode][Geocoding API] something? Looking for [directions][Directions API]?
+Maybe [matrices of directions][Distance Matrix API]? This gem brings the [Google Maps API Web
+Services] to your Ruby application.
+
+The Ruby gem for Google Maps Web Service APIs is a gem for the following Google Maps APIs:
+
+ - [Google Maps Directions API][Directions API]
+ - [Google Maps Distance Matrix API][Distance Matrix API]
+ - [Google Maps Elevation API][Elevation API]
+ - [Google Maps Geocoding API][Geocoding API]
+ - [Google Maps Time Zone API][Time Zone API]
+ - [Google Maps Roads API][Roads API]
+
+Keep in mind that the same [terms and conditions](https://developers.google.com/maps/terms) apply
+to usage of the APIs when they're accessed through this gem.
+
+
+## Features
+
+### Rate Limiting
+
+Never sleep between requests again! By default, requests are sent at the expected rate limits for
+each web service, typically 10 queries per second for free users. If you want to speed up or slowdown requests, you can do that too, using `queries_per_second` options while initializing API client.
+
+### Retry on Failure
+
+Automatically retry when intermittent failures occur. That is, when any of the retriable 5xx errors
+are returned from the API.
+
+### Keys *and* Client IDs
+
+Maps API for Work customers can use their [client ID and secret][clientid] to authenticate. Free
+customers can use their [API key][apikey], too.
+
+Note: Currently, [Roads API] does not accept client ID. It requires API key to authenticate the request.
+
+### Ruby Hash/Array as API Result
+
+This gem return a Ruby Hash/Array object as the API result. The result format structure is same as in Google Maps API documentation.
+
+## Requirements
+
+ - Ruby 2.0 or later.
+ - A Google Maps API credentials (API keys or client IDs)
+
+### Obtain API keys
+
+Each Google Maps Web Service requires an API key or Client ID. API keys are
+freely available with a Google Account at https://developers.google.com/console.
+To generate a server key for your project:
+
+ 1. Visit https://developers.google.com/console and log in with
+    a Google Account.
+ 1. Select an existing project, or create a new project.
+ 1. Click **Enable an API**.
+ 1. Browse for the API, and set its status to "On". The Python Client for Google Maps Services
+    accesses the following APIs:
+    * Directions API
+    * Distance Matrix API
+    * Elevation API
+    * Geocoding API
+    * Time Zone API
+    * Roads API
+ 1. Once you've enabled the APIs, click **Credentials** from the left navigation of the Developer
+    Console.
+ 1. In the "Public API access", click **Create new Key**.
+ 1. Choose **Server Key**.
+ 1. If you'd like to restrict requests to a specific IP address, do so now.
+ 1. Click **Create**.
+
+Your API key should be 40 characters long, and begin with `AIza`.
+
+**Important:** This key should be kept secret on your server.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'google_maps_service'
+
+And then execute:
+
+    bundle install
+
+Or install it yourself as:
+
+    gem install google_maps_service
+
+In your Ruby code, add this line to load this gem:
+
+    require 'google_maps_service'
+
+## Usage
+
+Before you request Google Maps API, you must configure the client.
+
+You can view the [reference documentation](http://www.rubydoc.info/gems/google_maps_service).
+
+### Configure client
+
+```ruby
+require 'google_maps_service'
+
+# Setup API keys
+gmaps = GoogleMapsService::Client.new(key: 'Add your key here')
+
+# Setup client IDs
+gmaps = GoogleMapsService::Client.new(
+    client_id: 'Add your client id here',
+    client_secret: 'Add your client secret here'
+)
+
+# More complex setup
+gmaps = GoogleMapsService::Client.new(
+    key: 'Add your key here',
+    retry_timeout: 20,      # Timeout for retrying failed request
+    queries_per_second: 10  # Limit total request per second
+)
+```
+You can also set up the client globally.
+
+```ruby
+require 'google_maps_service'
+
+# Setup global parameters
+GoogleMapsService.configure do |config|
+  config.key = 'Add your key here'
+  config.retry_timeout = 20
+  config.queries_per_second = 10
+end
+
+# Initialize client using global parameters
+gmaps = GoogleMapsService::Client.new
+```
+
+For more examples and detail (setup **proxy**, **timeout**, **caching**, etc.) while initializing the client, check out [Client documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/Client#initialize-instance_method).
+
+### Latitude/longitude pairs format
+
+Some APIs require latitude/longitude pair(s) as their parameter(s). This gem accept various format of latitude/longitude pairs:
+
+```ruby
+# Array
+latlng = [40.714224, -73.961452]
+
+# Hash with symbolized keys
+latlng = {lat: 40.714224, lng: -73.961452}
+latlng = {latitude: 40.714224, longitude: -73.961452}
+
+# Hash with string keys
+latlng = {'lat' => 40.714224, 'lng' => -73.961452}
+latlng = {'latitude' => 40.714224, 'longitude' => -73.961452}
+```
+
+### Directions API
+
+```ruby
+# Simple directions
+routes = gmaps.directions(
+    '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA',
+    '2400 Amphitheatre Parkway, Mountain View, CA 94043, USA',
+    mode: 'walking',
+    alternatives: false)
+```
+
+Sample result:
+
+```ruby
+[{
+  :bounds=>{
+    :northeast=>{:lat=>37.4238004, :lng=>-122.084314},
+    :southwest=>{:lat=>37.42277989999999, :lng=>-122.0882019}
+  },
+  :copyrights=>"Map data ©2015 Google",
+  :legs=>[
+    {
+      :distance=>{:text=>"0.2 mi", :value=>393},
+      :duration=>{:text=>"5 mins", :value=>287},
+      :end_address=>"2400 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
+      :end_location=>{:lat=>37.4238004, :lng=>-122.0882019},
+      :start_address=>"1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
+      :start_location=>{:lat=>37.42277989999999, :lng=>-122.084314},
+      :steps=>[
+        {
+          :distance=>{:text=>"223 ft", :value=>68},
+          :duration=>{:text=>"1 min", :value=>49},
+          :end_location=>{:lat=>37.4228653, :lng=>-122.0850785},
+          :html_instructions=>"Head <b>west</b>",
+          :polyline=>{:points=>"kclcF|qchVEdAGx@ALAJ"},
+          :start_location=>{:lat=>37.42277989999999, :lng=>-122.084314},
+          :travel_mode=>"WALKING"
+        }, {
+          :distance=>{:text=>"108 ft", :value=>33},
+          :duration=>{:text=>"1 min", :value=>23},
+          :end_location=>{:lat=>37.423161, :lng=>-122.0850102},
+          :html_instructions=>"Turn <b>right</b> toward <b>Amphitheatre Pkwy</b>",
+          :maneuver=>"turn-right",
+          :polyline=>{:points=>"}clcFvvchVg@IQC"},
+          :start_location=>{:lat=>37.4228653, :lng=>-122.0850785},
+          :travel_mode=>"WALKING"
+        }, {
+          :distance=>{:text=>"407 ft", :value=>124},
+          :duration=>{:text=>"2 mins", :value=>90},
+          :end_location=>{:lat=>37.423396, :lng=>-122.0863768},
+          :html_instructions=>"Turn <b>left</b> onto <b>Amphitheatre Pkwy</b>",
+          :maneuver=>"turn-left",
+          :polyline=>{:points=>"welcFhvchVEf@Eb@C\\EZGp@Il@CRAJAJ"},
+          :start_location=>{:lat=>37.423161, :lng=>-122.0850102},
+          :travel_mode=>"WALKING"
+        }, {
+          :distance=>{:text=>"0.1 mi", :value=>168},
+          :duration=>{:text=>"2 mins", :value=>125},
+          :end_location=>{:lat=>37.4238004, :lng=>-122.0882019},
+          :html_instructions=>
+            "Slight <b>right</b> to stay on <b>Amphitheatre Pkwy</b><div style=\"font-size:0.9em\">Destination will be on the right</div>",
+          :maneuver=>"turn-slight-right",
+          :polyline=>{:points=>"gglcFz~chVGJADAD?DIh@MhAWhBOxACT"},
+          :start_location=>{:lat=>37.423396, :lng=>-122.0863768},
+          :travel_mode=>"WALKING"
+        }
+      ],
+      :via_waypoint=>[]
+    }
+  ],
+  :overview_polyline=>{:points=>"kclcF|qchVQxCy@MKjA[xCE^IVMz@y@bH"},
+  :summary=>"Amphitheatre Pkwy",
+  :warnings=>["Walking directions are in beta.    Use caution – This route may be missing sidewalks or pedestrian paths."],
+  :waypoint_order=>[]
+}]
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/Directions), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/directions_spec.rb), and [Google Maps Directions API documentation][Directions API].
+
+### Distance Matrix API
+
+```ruby
+# Multiple parameters distance matrix
+origins = ["Bobcaygeon ON", [41.43206, -81.38992]]
+destinations = [[43.012486, -83.6964149], {lat: 42.8863855, lng: -78.8781627}]
+matrix = gmaps.distance_matrix(origins, destinations,
+    mode: 'driving',
+    language: 'en-AU',
+    avoid: 'tolls',
+    units: 'imperial')
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/DistanceMatrix), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/distance_matrix_spec.rb), and [Google Maps Distance Matrix API documentation][Distance Matrix API].
+
+### Elevation API
+
+```ruby
+# Elevation of some locations
+locations = [[40.714728, -73.998672], [-34.397, 150.644]]
+results = gmaps.elevation(locations)
+
+# Elevation along path
+locations = [[40.714728, -73.998672], [-34.397, 150.644]]
+results = gmaps.elevation_along_path(locations, 5)
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/Elevation), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/elevation_spec.rb), and [Google Maps Elevation API documentation][Elevation API].
+
+### Geocoding API
+
+```ruby
+# Geocoding an address
+results = gmaps.geocode('1600 Amphitheatre Parkway, Mountain View, CA')
+
+# Look up an address with reverse geocoding
+results = gmaps.reverse_geocode([40.714224, -73.961452])
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/Geocoding), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/geocoding_spec.rb), and [Google Maps Geocoding API documentation][Geocoding API].
+
+### Roads API
+
+```ruby
+# Snap to roads
+path = [
+    [-33.8671, 151.20714],
+    [-33.86708, 151.20683000000002],
+    [-33.867070000000005, 151.20674000000002],
+    [-33.86703, 151.20625]
+]
+results = gmaps.snap_to_roads(path, interpolate: true)
+
+# Snapped speed limits
+path = [
+    [-33.8671, 151.20714],
+    [-33.86708, 151.20683000000002],
+    [-33.867070000000005, 151.20674000000002],
+    [-33.86703, 151.20625]
+]
+results = gmaps.snapped_speed_limits(path)
+
+# Speed limits
+place_ids = [
+  'ChIJ0wawjUCuEmsRgfqC5Wd9ARM',
+  'ChIJ6cs2kkCuEmsRUfqC5Wd9ARM'
+]
+results = gmaps.speed_limits(place_ids)
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/Roads), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/roads_spec.rb), and [Google Maps Roads API documentation][Roads API].
+
+### Time Zone API
+
+```ruby
+# Current time zone
+timezone = gmaps.timezone([39.603481, -119.682251])
+
+# Time zone at certain time
+timezone = gmaps.timezone([39.603481, -119.682251], timestamp: Time.at(1608))
+```
+
+For more usage examples and result format, check out [gem documentation](http://www.rubydoc.info/gems/google_maps_service/GoogleMapsService/Apis/TimeZone), [test script](https://github.com/edwardsamuel/google-maps-services-ruby/tree/master/spec/google_maps_service/apis/time_zone_spec.rb), and [Google Maps Time Zone API documentation][Time Zone API].
+
+### Polyline encoder/decoder
+
+[Google Encoded Polyline] is a lossy compression algorithm that allows you to store a series of coordinates as a single string. This format is used in some APIs:
+
+  - [Directions API] encodes the result path.
+  - [Elevation API] also accepts the encoded polyline as request parameter.
+
+To handle Google Encoded Polyline, this gem provides encoder/decoder:
+
+```ruby
+require 'google_maps_service/polyline' # Or, require 'google_maps_service' is enough
+
+# Decode polyline
+encoded_path = '_p~iF~ps|U_ulLnnqC_mqNvxq`@'
+path = GoogleMapsService::Polyline.decode(encoded_path)
+#=> [{:lat=>38.5, :lng=>-120.2}, {:lat=>40.7, :lng=>-120.95}, {:lat=>43.252, :lng=>-126.45300000000002}]
+
+# Encode polyline
+path = [[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]]
+encoded_path = GoogleMapsService::Polyline.encode(path)
+#=> "_p~iF~ps|U_ulLnnqC_mqNvxq`@"
+```
+
+## Issues and feature suggestions
+
+If you find a bug, or have a feature suggestion, please [log an issue][issues]. If you'd like to
+contribute, please read [How to Contribute](#contributing).
+
+## Contributing
+
+1. Fork it (https://github.com/edwardsamuel/google-maps-services-ruby/fork).
+2. Create your feature branch (`git checkout -b my-new-feature`).
+3. Commit your changes (`git commit -am 'Add some feature'`).
+4. Push to the branch (`git push origin my-new-feature`).
+5. Create a new Pull Request.
+
+[apikey]: https://developers.google.com/maps/faq#keysystem
+[clientid]: https://developers.google.com/maps/documentation/business/webservices/auth
+
+[Google Maps API Web Services]: https://developers.google.com/maps/web-services/overview/
+[Directions API]: https://developers.google.com/maps/documentation/directions/
+[Distance Matrix API]: https://developers.google.com/maps/documentation/distancematrix/
+[Elevation API]: https://developers.google.com/maps/documentation/elevation/
+[Geocoding API]: https://developers.google.com/maps/documentation/geocoding/
+[Time Zone API]: https://developers.google.com/maps/documentation/timezone/
+[Roads API]: https://developers.google.com/maps/documentation/roads/
+
+[Google Encoded Polyline]: https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+
+[issues]: https://github.com/edwardsamuel/google-maps-services-ruby/issues

data/Rakefile

@@ -0,0 +1,15 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec
+
+unless defined?(JRUBY_VERSION)
+  require 'yard'
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/**/*.rb']
+  end
+end

data/bin/console

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "google_maps_service"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)
+

data/google_maps_service.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'google_maps_service/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'google_map_services'
+  spec.version       = GoogleMapsService::VERSION
+  spec.authors       = ['Edward Samuel Pasaribu', 'Ahmed Abdelhamid']
+  spec.email         = ['edwardsamuel92@gmail.com', 'eng.a.abdelhamid@outlook.com']
+
+  spec.summary       = %q{Ruby gem for Google Maps Web Service APIs }
+  spec.homepage      = %q{https://github.com/go-illa/google-maps-services-ruby}
+  spec.license       = 'Apache-2.0'
+  spec.required_ruby_version = '>= 2.0.0'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.require_paths = ['lib']
+  # spec.has_rdoc      = 'yard'
+
+  spec.add_runtime_dependency 'multi_json', '~> 1.12'
+  spec.add_runtime_dependency 'faraday', '>= 1'
+  spec.add_runtime_dependency 'retriable', '~> 3.0'
+end

data/lib/google_maps_service/apis/directions.rb

@@ -0,0 +1,101 @@
+require_relative '../validator'
+
+module GoogleMapsService::Apis
+
+  # Performs requests to the Google Maps Directions API.
+  module Directions
+
+    # Get directions between an origin point and a destination point.
+    #
+    # @example Simple directions
+    #   routes = client.directions('Sydney', 'Melbourne')
+    #
+    # @example Complex bicycling directions
+    #   routes = client.directions('Sydney', 'Melbourne',
+    #       mode: 'bicycling',
+    #       avoid: ['highways', 'tolls', 'ferries'],
+    #       units: 'metric',
+    #       region: 'au')
+    #
+    # @example 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)
+    #
+    # @example Walking with alternative routes
+    #    routes = client.directions('Sydney Town Hall', 'Parramatta, NSW',
+    #       mode: 'walking',
+    #       alternatives: true)
+    #
+    # @param [String, Hash, Array] origin The address or latitude/longitude value from which you wish
+    #         to calculate directions.
+    # @param [String, Hash, Array] destination The address or latitude/longitude value from which
+    #     you wish to calculate directions.
+    # @param [String] mode Specifies the mode of transport to use when calculating
+    #     directions. One of `driving`, `walking`, `bicycling` or `transit`.
+    # @param [Array<String>, Array<Hash>, Array<Array>] waypoints Specifies an array of waypoints. Waypoints alter a
+    #     route by routing it through the specified location(s).
+    # @param [Boolean] alternatives If True, more than one route may be returned in the
+    #     response.
+    # @param [Array, String] avoid Indicates that the calculated route(s) should avoid the
+    #     indicated features.
+    # @param [String] language The language in which to return results.
+    # @param [String] units Specifies the unit system to use when displaying results.
+    #     `metric` or `imperial`.
+    # @param [String] region The region code, specified as a ccTLD (_top-level domain_)
+    #     two-character value.
+    # @param [Integer, DateTime] departure_time Specifies the desired time of departure.
+    # @param [Integer, DateTime] arrival_time Specifies the desired time of arrival for transit
+    #     directions. Note: you can not specify both `departure_time` and
+    #     `arrival_time`.
+    # @param [Boolean] optimize_waypoints Optimize the provided route by rearranging the
+    #     waypoints in a more efficient order.
+    # @param [String, Array<String>] transit_mode 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"]`.
+    # @param [String] transit_routing_preference Specifies preferences for transit
+    #     requests. Valid values are `less_walking` or `fewer_transfers`.
+    #
+    # @return [Array] Array of routes.
+    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: GoogleMapsService::Convert.waypoint(origin),
+        destination: GoogleMapsService::Convert.waypoint(destination)
+      }
+
+      params[:mode] = GoogleMapsService::Validator.travel_mode(mode) if mode
+
+      if waypoints = 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 and 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
+
+      return get('/maps/api/directions/json', params)[:routes]
+    end
+  end
+end

data/lib/google_maps_service/apis/distance_matrix.rb

@@ -0,0 +1,85 @@
+require_relative '../validator'
+
+module GoogleMapsService::Apis
+
+  # Performs requests to the Google Maps Distance Matrix API.
+  module DistanceMatrix
+
+    # Gets travel distance and time for a matrix of origins and destinations.
+    #
+    # @example 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)
+    #
+    # @example 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')
+    #
+    # @param [Array] origins 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.
+    # @param [Array] destinations 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.
+    # @param [String] mode Specifies the mode of transport to use when calculating
+    #         directions. Valid values are `driving`, `walking`, `transit` or `bicycling`.
+    # @param [String] language The language in which to return results.
+    # @param [String] avoid Indicates that the calculated route(s) should avoid the
+    #     indicated features. Valid values are `tolls`, `highways` or `ferries`.
+    # @param [String] units Specifies the unit system to use when displaying results.
+    #     Valid values are `metric` or `imperial`.
+    # @param [Integer, DateTime] departure_time Specifies the desired time of departure.
+    # @param [Integer, DateTime] arrival_time Specifies the desired time of arrival for transit
+    #     directions. Note: you can not specify both `departure_time` and `arrival_time`.
+    # @param [String, Array<String>] transit_mode 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"]`.
+    # @param [String] transit_routing_preference Specifies preferences for transit
+    #     requests. Valid values are `less_walking` or `fewer_transfers`.
+    #
+    # @return [Hash] Matrix of distances. Results are returned in rows, each row
+    #     containing one origin paired with each destination.
+    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 and 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
+
+      return get('/maps/api/distancematrix/json', params)
+    end
+  end
+end

data/lib/google_maps_service/apis/elevation.rb

@@ -0,0 +1,58 @@
+module GoogleMapsService::Apis
+
+  # Performs requests to the Google Maps Elevation API.
+  module Elevation
+
+    # Provides elevation data for locations provided on the surface of the
+    # earth, including depth locations on the ocean floor (which return negative
+    # values).
+    #
+    # @example Single point elevation
+    #   results = client.elevation({latitude: 40.714728, longitude: -73.998672})
+    #
+    # @example Multiple points elevation
+    #   locations = [[40.714728, -73.998672], [-34.397, 150.644]]
+    #   results = client.elevation(locations)
+    #
+    # @param [Array] locations A single latitude/longitude hash, or an array of
+    #         latitude/longitude hash from which you wish to calculate
+    #         elevation data.
+    #
+    # @return [Array] Array of elevation data responses
+    def elevation(locations)
+      params = {
+        locations: GoogleMapsService::Convert.waypoints(locations)
+      }
+
+      return get('/maps/api/elevation/json', params)[:results]
+    end
+
+    # Provides elevation data sampled along a path on the surface of the earth.
+    #
+    # @example Elevation along path
+    #   locations = [[40.714728, -73.998672], [-34.397, 150.644]]
+    #   results = client.elevation_along_path(locations, 5)
+    #
+    # @param [String, Array] path A encoded polyline string, or a list of
+    #         latitude/longitude pairs from which you wish to calculate
+    #         elevation data.
+    # @param [Integer] samples The number of sample points along a path for which to
+    #         return elevation data.
+    #
+    # @return [Array] Array of elevation data responses
+    def elevation_along_path(path, samples)
+      if path.kind_of?(String)
+        path = "enc:%s" % path
+      else
+        path = GoogleMapsService::Convert.waypoints(path)
+      end
+
+      params = {
+        path: path,
+        samples: samples
+      }
+
+      return get('/maps/api/elevation/json', params)[:results]
+    end
+  end
+end