/google_places

A Ruby wrapper around the Google Places API

Primary LanguageRubyMIT LicenseMIT

Google Places ↑

This gem provides a Ruby wrapper around the Google Places API, using HTTParty. At this moment the gem does not support OAuth authentication and will only work with an API key.

Obtaining an API key ↑

To be able to use this gem, you’ll need a Google Places API key. To request an API key, point your browser to code.google.com/apis/console and follow the instructions there. You’ll find your API key on the *API Access* tab under *Simple API Access*.

Installing the gem ↑

To use this gem, install it with gem install google_places or add it to your Gemfile:

gem 'google_places'

And install it with bundle install

Usage ↑

The spot ↑

Each of the API methods below returns a GooglePlaces::Spot or a collection of those. Each of these objects has these attributes:

  • reference: a token to query the Google Places API for more details about the spot

  • vicinity: the street or neighborhood of the spot

  • lat: the latitude of the spot

  • lng: the longitude of the spot

  • name: the name of the spot

  • icon: a URL to the icon of this spot

  • types: array of feature types describing the spot, see list of supported types

  • formatted_phone_number: formatted phone number of the spot (eg (555)555-555)

  • formatted_address: the full address of the spot formatted with commas

  • address_components: the components (eg street address, city, state) of the spot’s address in an array

  • rating: the rating of this spot on Google Places

  • url: the url of this spot on Google Places

However address_components, city, country, formatted_address, region and url are nil.

  • To get these values: You can use @client.spot(place_id). This returns the complete information for the spot by making an extra API call per returned spot.

  • To get a collection of these detailed spots: You can use @client.spots(lat, lng, detail: true). This makes an extra call per each spot and returns a collection of the detailed spots.

Retrieving a list of spots ↑

First register a new Client:

@client = GooglePlaces::Client.new(API_KEY)

Then retrieve a list of spots:

@client.spots(-33.8670522, 151.1957362)

Search by a specific type:

@client.spots(-33.8670522, 151.1957362, :types => 'restaurant')

Search by multiple types:

@client.spots(-33.8670522, 151.1957362, :types => ['restaurant','food'])

Search by multiple types but exclude one type:

@client.spots(-33.8670522, 151.1957362, :types => ['restaurant','food'], :exclude => 'cafe')

Search by multiple types but exclude multiple types:

@client.spots(-33.8670522, 151.1957362, :types => ['restaurant','food'], :exclude => ['cafe', 'establishment'])

Search by name:

@client.spots(-33.8670522, 151.1957362, :name => 'italian')

Search by name and type:

@client.spots(-33.8670522, 151.1957362, :name => 'italian', :types => 'restaurant')

Search in a radius (in meters):

@client.spots(-33.8670522, 151.1957362, :radius => 100)

Get results in specific language:

@client.spots(-33.8670522, 151.1957362, :language => 'en')

Get detailed spots (this makes an extra call for each spot and returns a collection of the detailed spots):

@client.spots(-33.8670522, 151.1957362, :detail => true)

Retrieving spots based on query ↑

@client.spots_by_query('Pizza near Miami Florida')

Search by multiple types and exclude multiple types

@client.spots_by_query('Pizza near Miami Florida', :types => ['restaurant', 'food'], :exclude => ['cafe', 'establishment'])

Retrieving a collection of spots with complete details ↑

Google limits the details that are returned in any API calls for a collection, so you’ll often find that details such as phone numbers are missing in a collection of spots, but are filled in when retrieving a single spot.

If you require these extra details to be completed when retrieving a number of results, you can pass in the detail: true option to any method that returns a collection of spots.

This option should be used with care, as it adds an additional API call for EACH spot in the collection. E.g. a spots collection of 100 spots will use 101 API calls when the detail: true option is set.

Retrieving a single spot ↑

First register a new Client:

@client = GooglePlaces::Client.new(API_KEY)

Then retrieve the spot:

@client.spot('CmRYAAA...upoTH3g')

Retrieving a single photo’s url ↑

First register a new Client:

@client = GooglePlaces::Client.new(API_KEY)

Then retrieve the spot:

@spot = @client.spot('CmRYAAA...upoTH3g')

Then request one of the photos url with a max width:

url = @spot.photos[0].fetch_url(800)

Places Autocomplete ↑

developers.google.com/places/documentation/autocomplete

Note: Autocomplete is often used and better suited on client side (browser/javascript). The Autocomplete API is rate limited, so make sure you check the usage limits before deciding on whether to call the API server/client side.

developers.google.com/maps/documentation/business/articles/usage_limits

Example usage ↑

Register a new Client:

@client = GooglePlaces::Client.new(API_KEY)

Then request a prediction based on partial match:

@client.predictions_by_input(
    'San F',
    lat: 0.0,
    lng: 0.0,
    radius: 20000000,
    types: 'geocode',
    language: I18n.locale,
)

The response will be an array of predictions.

Development ↑

You’re very welcome to add functionality to this gem. To do so, follow these steps:

  1. Fork the project on Github

  2. Clone your own fork on your development machine

  3. Install the dependencies with bundle install

  4. Copy spec/api_key.sample.rb to spec/api_key.rb

  5. Insert your own Google Places API key in spec/api_key.rb

  6. Run the specs with rspec spec

  7. Hackety hack

  8. ???

  9. PROFIT

Feel free to send me a pull request but please make sure your changes are sufficiently covered by RSpec.

Important Note ↑

Concerning the reference field, the Google Places API documentation states:

"You can store this token and use it at any time in future to refresh cached data about this Place,
but the same token is not guaranteed to be returned for any given Place across different searches."

Please be aware that the reference field in spot details may differ from the reference used to retrieve that spot.