Class: GoogleMaps::Services::Places

Inherits:
Object
  • Object
show all
Defined in:
lib/googlemaps/services/places.rb

Overview

Performs requests to the Google Places API.

Since:

  • 1.0.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ Places

Returns a new instance of Places.

Since:

  • 1.0.0



11
12
13
 
# File 'lib/googlemaps/services/places.rb', line 11

def initialize(client)
  self.client = client
end

Instance Attribute Details

#client ⇒ Symbol

Returns The HTTP client.

Returns:

  • (Symbol) —

    The HTTP client.

Since:

  • 1.0.0



9
10
11
 
# File 'lib/googlemaps/services/places.rb', line 9

def client
  @client
end

Instance Method Details

#autocomplete(input_text:, offset: nil, location: nil, radius: nil, language: nil, types: nil, components: nil, strict_bounds: false) ⇒ Array, Nokogiri::XML::NodeSet

Returns Place predictions given a textual search string and optional geographic bounds.

Parameters:

  • input_text (String) —

    The text string on which to search.

  • offset (Integer) (defaults to: nil) —

    The position, in the input term, of the last character that the service uses to match predictions. For example, if the input is ‘Google’ and the offset is 3, the service will match on ‘Goo’.

  • location (String, Hash) (defaults to: nil) —

    The latitude/longitude value for which you wish to obtain the closest, human-readable address.

  • radius (Integer) (defaults to: nil) —

    Distance in meters within which to bias results.

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

    The language in which to return results.

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

    Restricts the results to places matching the specified type. The full list of supported types is available here: developers.google.com/places/web-service/autocomplete#place_types

  • components (Hash) (defaults to: nil) —

    A grouping of places to which you would like to restrict your results. Currently, you can use components to filter by up to 5 countries for example: [‘US’, ‘AU’]

  • strict_bounds (TrueClass, FalseClass) (defaults to: false) —

    Returns only those places that are strictly within the region defined by location and radius.

Returns:

  • (Array, Nokogiri::XML::NodeSet) —

    Array of predictions.

Since:

  • 1.0.0



195
196
197
198
199
 
# File 'lib/googlemaps/services/places.rb', line 195

def autocomplete(input_text:, offset: nil, location: nil, radius: nil, language: nil,
                 types: nil, components: nil, strict_bounds: false)
  _autocomplete(url_part: "", input_text: input_text, offset: offset, location: location, radius: radius,
                language: language, types: types, components: components, strict_bounds: strict_bounds)
end

#autocomplete_query(input_text:, offset: nil, location: nil, radius: nil, language: nil) ⇒ Array, Nokogiri::XML::NodeSet

Returns Place predictions given a textual search query, such as “pizza near Brussels”, and optional geographic bounds.

Parameters:

  • input_text (String) —

    The text query on which to search.

  • offset (Integer) (defaults to: nil) —

    The position, in the input term, of the last character that the service uses to match predictions. For example, if the input is ‘Google’ and the offset is 3, the service will match on ‘Goo’.

  • location (String, Hash) (defaults to: nil) —

    The latitude/longitude value for which you wish to obtain the closest, human-readable address.

  • radius (Integer) (defaults to: nil) —

    Distance in meters within which to bias results.

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

    The language in which to return results.

Returns:

  • (Array, Nokogiri::XML::NodeSet) —

    Array of predictions.

Since:

  • 1.0.0



210
211
212
213
 
# File 'lib/googlemaps/services/places.rb', line 210

def autocomplete_query(input_text:, offset: nil, location: nil, radius: nil, language: nil)
  _autocomplete(url_part: 'query', input_text: input_text, offset: offset,
                location: location, radius: radius, language: language)
end

#nearby(location: nil, radius: nil, keyword: nil, language: nil, min_price: nil, max_price: nil, name: nil, open_now: false, rank_by: nil, type: nil, page_token: nil) ⇒ Hash, Nokogiri::XML::Document

Performs nearby search for places.

Parameters:

  • location (String, Hash) (defaults to: nil) —

    The lat/lng value for which you wish to obtain the closest, human-readable address.

  • radius (Integer) (defaults to: nil) —

    Distance in meters within which to bias results.

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

    A term to be matched against all content that Google has indexed for this place.

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

    The language in which to return results.

  • min_price (Integer) (defaults to: nil) —

    Restricts results to only those places with no less than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).

  • max_price (Integer) (defaults to: nil) —

    Restricts results to only those places with no greater than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).

  • name (Array) (defaults to: nil) —

    One or more terms to be matched against the names of places.

  • open_now (TrueClass, FalseClass) (defaults to: false) —

    Return only those places that are open for business at the time the query is sent.

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

    Specifies the order in which results are listed. Possible values are: prominence (default), distance

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

    Restricts the results to places matching the specified type. The full list of supported types is available here: developers.google.com/places/supported_types

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

    Token from a previous search that when provided will returns the next page of results for the same search.

Returns:

  • (Hash, Nokogiri::XML::Document) —

    Valid JSON or XML response.

Since:

  • 1.0.0



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/googlemaps/services/places.rb', line 51

def nearby(location: nil, radius: nil, keyword: nil, language: nil, min_price: nil,
           max_price: nil, name: nil, open_now: false, rank_by: nil, type: nil, page_token: nil)
  if !location && !page_token
    raise StandardError, 'either a location or page_token is required.'
  end
  if rank_by == 'distance'
    if !(keyword || name || type)
      raise StandardError, 'either a keyword, name or type arg is required when rank_by is set to distance.'
    elsif radius
      raise StandardError, 'radius cannot be specified when rank_by is set to distance.'
    end
  end

  _places(url_part: 'nearby', location: location, radius: radius, keyword: keyword, language: language,
          min_price: min_price, max_price: max_price, name: name, open_now: open_now, rank_by: rank_by,
          type: type, page_token: page_token)
end

#place_details(place_id:, language: nil) ⇒ Hash, Nokogiri::XML::Document

Comprehensive details for an individual place.

Parameters:

  • place_id (String) —

    A textual identifier that uniquely identifies a place, returned from a Places search.

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

    The language in which to return results.

Returns:

  • (Hash, Nokogiri::XML::Document) —

    Valid JSON or XML response.

Since:

  • 1.0.0



151
152
153
154
155
156
157
158
 
# File 'lib/googlemaps/services/places.rb', line 151

def place_details(place_id:, language: nil)
  params = {'placeid' => place_id}
  if language
    params['language'] = language
  end

  self.client.request(url: "/maps/api/place/details/#{self.client.response_format}", params: params)
end

#place_photo(photo_reference:, max_width: nil, max_height: nil) ⇒ String

Downloads a photo from the Places API.

Parameters:

  • photo_reference (String) —

    A string identifier that uniquely identifies a photo, as provided by either a Places search or Places detail request.

  • max_width (Integer) (defaults to: nil) —

    Specifies the maximum desired width, in pixels.

  • max_height (Integer) (defaults to: nil) —

    Specifies the maximum desired height, in pixels.

Returns:

  • (String) —

    URL of the photo.

Raises:

  • (StandardError)

Since:

  • 1.0.0



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/googlemaps/services/places.rb', line 167

def place_photo(photo_reference:, max_width: nil, max_height: nil)
  raise StandardError, 'a max_width or max_height arg is required' unless (max_width || max_height)

  params = {'photoreference' => photo_reference}

  if max_width
    params['maxwidth'] = max_width
  end

  if max_height
    params['maxheight'] = max_height
  end

  self.client.request(url: '/maps/api/place/photo', params: params)
end

#radar(location:, radius:, keyword: nil, min_price: nil, max_price: nil, name: nil, open_now: false, type: nil) ⇒ Hash, Nokogiri::XML::Document

Performs radar search for places.

Parameters:

  • location (String, Hash) —

    The latitude/longitude value for which you wish to obtain the closest, human-readable address.

  • radius (Integer) —

    Distance in meters within which to bias results.

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

    A term to be matched against all content that Google has indexed for this place.

  • min_price (Integer) (defaults to: nil) —

    Restricts results to only those places with no less than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).

  • max_price (Integer) (defaults to: nil) —

    Restricts results to only those places with no greater than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).

  • name (Array) (defaults to: nil) —

    One or more terms to be matched against the names of places.

  • open_now (TrueClass, FalseClass) (defaults to: false) —

    Return only those places that are open for business at the time the query is sent.

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

    Restricts the results to places matching the specified type. The full list of supported types is available here: developers.google.com/places/supported_types

Returns:

  • (Hash, Nokogiri::XML::Document) —

    Valid JSON or XML response.

Raises:

  • (StandardError)

Since:

  • 1.0.0



81
82
83
84
85
86
87
88
89
 
# File 'lib/googlemaps/services/places.rb', line 81

def radar(location:, radius:, keyword: nil, min_price: nil,
          max_price: nil, name: nil, open_now: false, type: nil)
  warn '[DEPRECATION] Places Radar is deprecated as of June 30, 2018. After that time, this feature will no longer be available.'
  raise StandardError, 'either a keyword, name, or type arg is required.' unless (keyword || name || type)

  _places(url_part: 'radar', location: location, radius: radius,
          keyword: keyword, min_price: min_price, max_price: max_price,
          name: name, open_now: open_now, type: type)
end

#search(query:, location: nil, radius: nil, language: nil, min_price: nil, max_price: nil, open_now: false, type: nil, region: nil, page_token: nil) ⇒ Hash, Nokogiri::XML::Document

Performs places search.

Parameters:

  • query (String) —

    The text string on which to search. E.g. “restaurant”.

  • location (String, Hash) (defaults to: nil) —

    The lat/lng value for which you wish to obtain the closest, human-readable address.

  • radius (Integer) (defaults to: nil) —

    Distance in meters within which to bias results.

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

    The language in which to return results.

  • min_price (Integer) (defaults to: nil) —

    Restricts results to only those places with no less than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).

  • max_price (Integer) (defaults to: nil) —

    Restricts results to only those places with no greater than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).

  • open_now (TrueClass, FalseClass) (defaults to: false) —

    Return only those places that are open for business at the time the query is sent.

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

    Restricts the results to places matching the specified type. The full list of supported types is available here: developers.google.com/places/supported_types

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

    The region code, specified as a ccTLD (country code top-level domain) two-character value.

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

    Token from a previous search that when provided will returns the next page of results for the same search.

Returns:

  • (Hash, Nokogiri::XML::Document) —

    Valid JSON or XML response.

Since:

  • 1.0.0



29
30
31
32
33
34
 
# File 'lib/googlemaps/services/places.rb', line 29

def search(query:, location: nil, radius: nil, language: nil, min_price: nil,
           max_price: nil, open_now: false, type: nil, region: nil, page_token: nil)
  _places(url_part: 'text', query: query, location: location, radius: radius,
          language: language, min_price: min_price, max_price: max_price,
          open_now: open_now, type: type, region: region, page_token: page_token)
end