Module: Foursquare2::Venues

Included in:
Client
Defined in:
lib/foursquare2/venues.rb

Instance Method Summary collapse

Instance Method Details

#add_venue(options = {}) ⇒ Object

Add a venue

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • String (Object) —

    :name - Name of the venue (required)

  • String (Object) —

    :address

  • String (Object) —

    :crossStreet

  • String (Object) —

    :city

  • String (Object) —

    :state

  • String (Object) —

    :zip

  • String (Object) —

    :phone

  • String (Object) —

    :ll - Latitude and longitude in format LAT,LON

  • String (Object) —

    :primaryCategoryId - Main category for the venue, must be in the list of venue categories.



92
93
94
95
96
97
 
# File 'lib/foursquare2/venues.rb', line 92

def add_venue(options={})
  response = connection.post do |req|
    req.url "venues/add", options
  end
  return_error_or_body(response, response.body.response.venue)
end

#explore_venues(options = {}) ⇒ Object

Explore venues

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • String (Object) —

    :ll - Latitude and longitude in format LAT,LON

  • Integer (Object) —

    :llAcc - Accuracy of the lat/lon in meters.

  • Integer (Object) —

    :alt - Altitude in meters

  • Integer (Object) —

    :altAcc - Accuracy of the altitude in meters

  • Integer (Object) —

    :radius - Radius to search within, in meters

  • String (Object) —

    :section - One of food, drinks, coffee, shops, or arts. Choosing one of these limits results to venues with categories matching these terms.

  • String (Object) —

    :query - Query to match venues on.

  • Integer (Object) —

    :limit - The limit of results to return.

  • String (Object) —

    :intent - Limit results to venues with specials.

  • String (Object) —

    :novelty - Pass new or old to limit results to places the acting user hasn’t been or has been, respectively. Omitting this parameter returns a mixture.



159
160
161
162
163
164
 
# File 'lib/foursquare2/venues.rb', line 159

def explore_venues(options={})
  response = connection.get do |req|
    req.url "venues/explore", options
  end
  return_error_or_body(response, response.body.response)
end

#flag_venue(venue_id, options = {}) ⇒ Object

Flag a venue as having a problem

Parameters:

  • venue_id (String) —

    • Venue id to flag, required.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • String (Object) —

    :problem - Reason for flag, one of mislocated,closed, or duplicate. Required.



118
119
120
121
122
123
 
# File 'lib/foursquare2/venues.rb', line 118

def flag_venue(venue_id, options={})
  response = connection.post do |req|
    req.url "venues/#{venue_id}/flag", options
  end
  return_error_or_body(response, response.body.response)
end

#herenow(venue_id, options = {}) ⇒ Object

Returns a list of users that are currently checked into a venue

param [String] venue_id The ID of the venue managed by the current user

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • Integer (Object) —

    :limit - Number of results to return, up to 500.

  • Integer (Object) —

    :offset - Used to page through results.

  • Integer (Object) —

    :afterTimestamp - Retrieve the first results to follow these seconds since epoch.



200
201
202
203
204
205
 
# File 'lib/foursquare2/venues.rb', line 200

def herenow(venue_id, options={})
  response = connection.get do |req|
    req.url "venues/#{venue_id}/herenow", options
  end
  return_error_or_body(response, response.body.response)
end

#managed_venue_stats(venue_id, options = {}) ⇒ Object

Get venue stats over a given time range. Client instance should represent an OAuth user who is the venue owner. Note: returns more detailed statistics than the basic stats returned when calling venue(venue_id)

param [String] venue_id The ID of the venue managed by the current user

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • Integer (Object) —

    :startAt - The start of the time range to retrieve stats for (seconds since epoch). If omitted, all-time stats will be returned.

  • Integer (Object) —

    :endAt - The end of the time range to retrieve stats for (seconds since epoch). If omitted, the current time is assumed.



226
227
228
229
230
231
 
# File 'lib/foursquare2/venues.rb', line 226

def managed_venue_stats(venue_id, options={})
  response = connection.get do |req|
    req.url "venues/#{venue_id}/stats", options
  end
  return_error_or_body(response, response.body.response)
end

#managed_venues ⇒ Object

Returns a list of venues managed



211
212
213
214
215
216
 
# File 'lib/foursquare2/venues.rb', line 211

def managed_venues()
  response = connection.get do |req|
    req.url "venues/managed"
  end
  return_error_or_body(response, response.body.response.venues)
end

#mark_venue_todo(venue_id, options = {}) ⇒ Object

Mark a venue as todo for the authenticated user

Parameters:

  • venue_id (String) —

    • Venue id to mark todo, required.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • String (Object) —

    :text - Text for the tip/todo



105
106
107
108
109
110
 
# File 'lib/foursquare2/venues.rb', line 105

def mark_venue_todo(venue_id, options={})
  response = connection.post do |req|
    req.url "venues/#{venue_id}/marktodo", options
  end
  return_error_or_body(response, response.body.response)
end

#propose_venue_edit(venue_id, options = {}) ⇒ Object

Propose a venue edit

Parameters:

  • venue_id (String) —

    • Venue id to propose edit for, required.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • String (Object) —

    :name - Name of the venue (required)

  • String (Object) —

    :address

  • String (Object) —

    :crossStreet

  • String (Object) —

    :city

  • String (Object) —

    :state

  • String (Object) —

    :zip

  • String (Object) —

    :phone

  • String (Object) —

    :ll - Latitude and longitude in format LAT,LON

  • String (Object) —

    :primaryCategoryId - Main category for the venue, must be in the list of venue categories.



138
139
140
141
142
143
 
# File 'lib/foursquare2/venues.rb', line 138

def propose_venue_edit(venue_id, options={})
  response = connection.post do |req|
    req.url "venues/#{venue_id}/proposeedit", options
  end
  return_error_or_body(response, response.body.response)
end

#search_venues(options = {}) ⇒ Object

Search for venues

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • String (Object) —

    :ll - Latitude and longitude in format LAT,LON

  • Integer (Object) —

    :llAcc - Accuracy of the lat/lon in meters.

  • Integer (Object) —

    :alt - Altitude in meters

  • Integer (Object) —

    :altAcc - Accuracy of the altitude in meters

  • Integer (Object) —

    :limit - The limit of results to return.

  • String (Object) —

    :intent - One of checkin, match, or specials.

  • String (Object) —

    :query - Query to match venues on.



24
25
26
27
28
29
 
# File 'lib/foursquare2/venues.rb', line 24

def search_venues(options={})
  response = connection.get do |req|
    req.url "venues/search", options
  end
  return_error_or_body(response, response.body.response)
end

#search_venues_by_tip(options = {}) ⇒ Object

Search for venues by tip

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • String (Object) —

    :ll - Latitude and longitude in format LAT,LON

  • Integer (Object) —

    :limit - The limit of results to return.

  • Integer (Object) —

    :offset - Used to page through results.

  • String (Object) —

    :filter - Set to ‘friends’ to limit tips to those from friends.

  • String (Object) —

    :query - Only find tips matching this term.



55
56
57
58
59
60
61
62
 
# File 'lib/foursquare2/venues.rb', line 55

def search_venues_by_tip(options={})
  tips = search_tips(options)
  venues = []
  tips.each do |tip|
    venues << tip['venue']
  end
  venues
end

#suggest_completion_venues(options = {}) ⇒ Object

Suggest venue completions. Returns a list of mini-venues partially matching the search term, near the location.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • String (Object) —

    :ll - Latitude and longitude in format LAT,LON

  • Integer (Object) —

    :llAcc - Accuracy of the lat/lon in meters.

  • Integer (Object) —

    :alt - Altitude in meters

  • Integer (Object) —

    :altAcc - Accuracy of the altitude in meters

  • String (Object) —

    :query - Query to match venues on.

  • Integer (Object) —

    :limit - The limit of results to return.



176
177
178
179
180
181
 
# File 'lib/foursquare2/venues.rb', line 176

def suggest_completion_venues(options={})
  response = connection.get do |req|
    req.url "venues/suggestCompletion", options
  end
  return_error_or_body(response, response.body.response)
end

#trending_venues(ll, options = {}) ⇒ Object

Search for trending venues

Parameters:

  • :ll (String) —

    Latitude and longitude in format LAT,LON

  • options (Hash) (defaults to: {})

Options Hash (options):

  • Integer (Object) —

    :limit - Number of results to return, up to 50.

  • Integer (Object) —

    :radius - Radius in meters, up to approximately 2000 meters.



38
39
40
41
42
43
44
 
# File 'lib/foursquare2/venues.rb', line 38

def trending_venues(ll, options={})
  options[:ll] = ll    
  response = connection.get do |req|
    req.url "venues/trending", options
  end
  return_error_or_body(response, response.body.response)
end

#venue(venue_id) ⇒ Object

Retrieve information about a venue

param [String] venue_id The ID of the venue



8
9
10
11
 
# File 'lib/foursquare2/venues.rb', line 8

def venue(venue_id)
  response = connection.get("venues/#{venue_id}")
  return_error_or_body(response, response.body.response.venue)
end

#venue_categories ⇒ Object

Retrieve information about all venue categories.



66
67
68
69
 
# File 'lib/foursquare2/venues.rb', line 66

def venue_categories
  response = connection.get("venues/categories")
  return_error_or_body(response, response.body.response.categories)
end

#venue_events(venue_id) ⇒ Object

Get the events currently taking place at a venue.

param [String] venue_id The ID of the venue



263
264
265
266
 
# File 'lib/foursquare2/venues.rb', line 263

def venue_events(venue_id)
  response = connection.get("venues/#{venue_id}/events")
  return_error_or_body(response, response.body.response)
end

#venue_hours(venue_id) ⇒ Object

Get venue hours information.

param [String] venue_id The ID of the venue



254
255
256
257
 
# File 'lib/foursquare2/venues.rb', line 254

def venue_hours(venue_id)
  response = connection.get("venues/#{venue_id}/hours")
  return_error_or_body(response, response.body.response)
end

#venue_likes(venue_id) ⇒ Object

Returns friends and a total count of users who have liked this venue.

param [String] venue_id The ID of the venue to get likes for



272
273
274
275
 
# File 'lib/foursquare2/venues.rb', line 272

def venue_likes(venue_id)
  response = connection.get("venues/#{venue_id}/likes")
  return_error_or_body(response, response.body.response)
end

#venue_links(venue_id) ⇒ Object

Retrieve links for a venue.

param [String] venue_id The ID of the venue



75
76
77
78
 
# File 'lib/foursquare2/venues.rb', line 75

def venue_links(venue_id)
  response = connection.get("venues/#{venue_id}/links")
  return_error_or_body(response, response.body.response.links)
end

#venue_listed(venue_id, options = {}) ⇒ Object

Returns the lists that this venue appears on.

param [String] venue_id ID of a venue to get lists for.

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • String (Object) —

    :group - can be created, edited, followed, friends, other. If no acting user is present, only other is supported.

  • Integer (Object) —

    :limit - Number of results to return, up to 200.

  • Integer (Object) —

    :offset - Used to page through results. Must specify a group



284
285
286
287
288
289
 
# File 'lib/foursquare2/venues.rb', line 284

def venue_listed(venue_id, options={})
  response = connection.get do |req|
    req.url "venues/#{venue_id}/listed", options
  end
  return_error_or_body(response, response.body.response)
end

#venue_menus(venue_id) ⇒ Object

Retrieve menus for a venue.

param [String] venue_id The ID of the venue



187
188
189
190
 
# File 'lib/foursquare2/venues.rb', line 187

def venue_menus(venue_id)
  response = connection.get("venues/#{venue_id}/menu")
  return_error_or_body(response, response.body.response)
end

#venue_nextvenues(venue_id) ⇒ Object

Returns venues that people often check in to after the current venue. Up to 5 venues are returned in each query, and results are sorted by how many people have visited that venue after the current one. Homes are never returned in results.

param [String] venue_id Required. ID of the venue you want to see next venue information about



295
296
297
298
 
# File 'lib/foursquare2/venues.rb', line 295

def venue_nextvenues(venue_id)
  response = connection.get("venues/#{venue_id}/nextvenues")
  return_error_or_body(response, response.body.response)
end

#venue_similar(venue_id) ⇒ Object

Returns a list of venues similar to the specified venue.

param [String] venue_id The venue you want similar venues for.



304
305
306
307
 
# File 'lib/foursquare2/venues.rb', line 304

def venue_similar(venue_id)
  response = connection.get("venues/#{venue_id}/similar")
  return_error_or_body(response, response.body.response)
end

#venues_timeseries(options = {}) ⇒ Object

Get daily venue stats for a list of venues over a time range. Client instance should represent an OAuth user who is the venues owner.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • Array (String) —

    :venueId - A list of venue ids to retrieve series data for.

  • Integer (Object) —

    :startAt - Required. The start of the time range to retrieve stats for (seconds since epoch).

  • Integer (Object) —

    :endAt - The end of the time range to retrieve stats for (seconds since epoch). If omitted, the current time is assumed.

  • String (Object) —

    :fields - Specifies which fields to return. May be one or more of totalCheckins, newCheckins, uniqueVisitors, sharing, genders, ages, hours, separated by commas.



242
243
244
245
246
247
248
 
# File 'lib/foursquare2/venues.rb', line 242

def venues_timeseries(options={})
  options[:venueId] = options[:venueId].join(',') # Transforms the array into a 'comma-separated list' of ids.
  response = connection.get do |req|
    req.url "venues/timeseries", options
  end
  return_error_or_body(response, response.body.response)
end