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.



98
99
100
101
102
103
# File 'lib/foursquare2/venues.rb', line 98

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

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

Make changes to a venue

Parameters:

  • venue_id (String)
    • Venue id to edit, required. Acting user must be a venue manager or a superuser.

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

Options Hash (options):

  • String (Object)

    :name

  • 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)

    :categoryId - The IDs of the category or categories to which you want to assign this venue (separate multiple IDs with commas).

  • String (Object)

    :twitter – Twitter handle of the name.

  • String (Object)

    :description – A free-form venue description, up to 300 characters.

  • String (Object)

    :url – The url of the homepage of the venue.

  • String (Object)

    :storeId – An identifier used by the manager of the venue to distinguish between venues of the same name. Only visible to managers.

  • String (Object)

    :hours – The hours for the venue, as a semi-colon separated list of open segments and named segments.



169
170
171
172
173
174
175
# File 'lib/foursquare2/venues.rb', line 169

def edit_venue(venue_id, options={})
  response = connection.post do |req|
    req.body = options
    req.url "venues/#{venue_id}/proposeedit"
  end
  return_error_or_body(response, response.body.response)
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.

  • String (Object)

    :venuePhotos - true to bring out the photos



191
192
193
194
195
196
# File 'lib/foursquare2/venues.rb', line 191

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.



124
125
126
127
128
129
# File 'lib/foursquare2/venues.rb', line 124

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.



234
235
236
237
238
239
# File 'lib/foursquare2/venues.rb', line 234

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.



260
261
262
263
264
265
# File 'lib/foursquare2/venues.rb', line 260

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(options = {}) ⇒ Object

Returns a list of venues managed



245
246
247
248
249
250
# File 'lib/foursquare2/venues.rb', line 245

def managed_venues(options={})
  response = connection.get do |req|
    req.url "venues/managed", options
  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



111
112
113
114
115
116
# File 'lib/foursquare2/venues.rb', line 111

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.



144
145
146
147
148
149
# File 'lib/foursquare2/venues.rb', line 144

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.



26
27
28
29
30
31
# File 'lib/foursquare2/venues.rb', line 26

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.



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

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.



208
209
210
211
212
213
# File 'lib/foursquare2/venues.rb', line 208

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

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.



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

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, options = {}) ⇒ Object

Retrieve information about a venue

param [String] venue_id The ID of the venue



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

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

#venue_categories(options = {}) ⇒ Object

Retrieve information about all venue categories.



68
69
70
71
72
73
# File 'lib/foursquare2/venues.rb', line 68

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

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

Get the events currently taking place at a venue.

param [String] venue_id The ID of the venue



299
300
301
302
303
304
# File 'lib/foursquare2/venues.rb', line 299

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

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

Get venue hours information.

param [String] venue_id The ID of the venue



288
289
290
291
292
293
# File 'lib/foursquare2/venues.rb', line 288

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

#venue_likes(venue_id, options = {}) ⇒ 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



310
311
312
313
314
315
# File 'lib/foursquare2/venues.rb', line 310

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

Retrieve links for a venue.

param [String] venue_id The ID of the venue



79
80
81
82
83
84
# File 'lib/foursquare2/venues.rb', line 79

def venue_links(venue_id, options={})
  response = connection.get do |req|
    req.url "venues/#{venue_id}/links", options
  end
  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



324
325
326
327
328
329
# File 'lib/foursquare2/venues.rb', line 324

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, options = {}) ⇒ Object

Retrieve menus for a venue.

param [String] venue_id The ID of the venue



219
220
221
222
223
224
# File 'lib/foursquare2/venues.rb', line 219

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

#venue_nextvenues(venue_id, options = {}) ⇒ 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



335
336
337
338
339
340
# File 'lib/foursquare2/venues.rb', line 335

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

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

Returns a list of venues similar to the specified venue.

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



346
347
348
349
350
351
# File 'lib/foursquare2/venues.rb', line 346

def venue_similar(venue_id, options={})
  response = connection.get do |req|
    req.url "venues/#{venue_id}/similar", options
  end
  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.



276
277
278
279
280
281
282
# File 'lib/foursquare2/venues.rb', line 276

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