Ruby gem for Google Maps APIs

Build Status Coverage Status

This gem is ported from Python Client for Google Maps Services.

Description

Use Ruby? Want to geocode something? Looking for directions? Maybe matrices of directions? 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:

Keep in mind that the same terms and conditions 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 to authenticate. Free customers can use their API key, 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.

Contributing

If you find a bug please log an issue.

The goal of this gem is to follow the API and implementation of the python client as much as possible. If you would like to add support for an API please consider porting the python implementation.

To create a new pull request:

  1. Fork it (https://github.com/langsharpe/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.

Requirements

  • Ruby 2.7 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.
  2. Select an existing project, or create a new project.
  3. Select APIs and Services > Enables APIs and services.
  4. Click Enable APIs and services
  5. Browse for the API, and set its status to "On". The Ruby Client for Google Maps Services accesses the following APIs:
    • Directions API
    • Distance Matrix API
    • Elevation API
    • Geocoding API
    • Time Zone API
    • Roads API
  6. Once you've enabled the APIs, click Credentials from the left navigation of the Developer Console.
  7. In the "Public API access", click Create new Key.
  8. Choose Server Key.
  9. If you'd like to restrict requests to a specific IP address, do so now.
  10. 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_ruby'

And then execute:

bundle install

Or install it yourself as:

gem install google_maps_service_ruby

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.

Configure client

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.

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.

Latitude/longitude pairs format

Some APIs require latitude/longitude pair(s) as their parameter(s). This gem accept various format of latitude/longitude pairs:

# 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

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

[{
  :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, test script, and Google Maps Directions API documentation.

Distance Matrix API

# 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, test script, and Google Maps Distance Matrix API documentation.

Elevation API

# 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, test script, and Google Maps Elevation API documentation.

Geocoding API

# 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, test script, and Google Maps Geocoding API documentation.

Places API

# Search for places
results = gmaps.places(
  'Pizza Restaurant',
  location: {:lat=>37.4221114, :lng=>-122.0867443},
)

# Search for places nearby
results = gmaps.places_nearby(
  location: {:lat=>37.4221114, :lng=>-122.0867443},
  radius: 5000,
)

# Get the url for a photo returned by the places api
url = gmaps.places_photo(photo_reference, max_width: 400, max_height: 400)

For more usage examples and result format, check out gem documentation, test script, and Google Maps Places API documentation.

Roads API

# 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, test script, and Google Maps Roads API documentation.

Time Zone API

# 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, test script, and Google Maps Time Zone API documentation.

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:

To handle Google Encoded Polyline, this gem provides encoder/decoder:

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`@"