Module: Skittles::Client::Venue

Included in:
Skittles::Client
Defined in:
lib/skittles/client/venue.rb

Overview

Defines methods related to venues.

Instance Method Summary collapse

Instance Method Details

#add_venue(name, options = {}) ⇒ Hashie::Mash

Adds a new venue.

All fields are optional, but one of either a valid address or a geolat/geolong pair must be provided. It is recommended that a geolat/geolong pair is provided in every case.

Optionally, a category(primarycategoryid) may be passed in to which this venue is to be assigned. A full list of categories using the /categories method.

Parameters:

  • name (String)

    The name of the venue.

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

    A customizable set of options.

Options Hash (options):

  • address (String)

    The address of the venue.

  • crossStreen (String)

    The nearest intersecting street or streets.

  • city (String)

    The city name where this venue is.

  • state (String)

    The nearest state or province to the venue.

  • zip (String)

    The zip or postal code for the venue.

  • phone (String)

    The phone number of the venue.

  • ll (String)

    Latitude and longitude of the venue, as accurate as is known.

  • primaryCategoryId (String)

    The id of the category to which you want to assign this venue.

Returns:

  • (Hashie::Mash)

    Details about the venue that was just added.

See Also:

Requires Acting User:

  • Yes


30
31
32
# File 'lib/skittles/client/venue.rb', line 30

def add_venue(name, options = {})
  post('venues/add', { :name => name }.merge(options)).venue
end

#categoriesHashie::Mash

that top-level categories do not have ids because they cannot be assigned to a venue.

Category images that come down through the API are available in three sizes:

  • 32 x 32 (default)

  • 64 x 64

  • 256 x 256

Returns:

  • (Hashie::Mash)

    A heirarchical list of categories applied to venues.

See Also:

Requires Acting User:

  • No


46
47
48
# File 'lib/skittles/client/venue.rb', line 46

def categories
  get('venues/categories').categories
end

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

Allows changes to be made to a venue. Any blank parameter deletes an an old value, any unspecified parameter does nothing.

Parameters:

  • id (String)

    id of the venue to edit.

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

    A customizable set of options.

Options Hash (options):

  • name (String)
  • address (String)
  • crossStreet (String)
  • city (String)
  • state (String)
  • zip (String)
  • phone (String)
  • ll (String)
  • categoryId (String)
  • url (String)
  • hours (String)

See Also:

Requires Acting User:

  • Yes


68
69
70
# File 'lib/skittles/client/venue.rb', line 68

def edit_venue(id, options = {})
  post("venues/#{id}/edit", options)
end

#explore(ll, options = {}) ⇒ Hashie::Mash

Note:

This is an experimental API.

Returns a list of recommended venues near the current location.

Parameters:

  • ll (String)

    Latitude and longitude of the user's location.

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

    A customizable set of options.

Options Hash (options):

  • llAcc (Decimal)

    Accuracy of latitude and longitude, in meters.

  • alt (Decimal)

    Altitude of the user's location, in meters.

  • altAcc (Decimal)

    Accuracy of the user's altitude, in meters.

  • radius (Integer)

    Radius to search within, in meters.

  • section (String)

    One of food, drinks, coffee, shops, or arts. Limits results to venues with categories matching these terms.

  • query (String)

    A search term to be applies against tips, category tips, etc. at a venue.

  • limit (Integer)

    Number of results to return, up to 50.

  • basis (String)

    If present and set to friends or me, limits results to only places where friends have visited or user has visited, respectively.

  • novelty (String)

    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.

Returns:

  • (Hashie::Mash)

    Response fields keywords, warnings and groups.

See Also:

Requires Acting User:

  • No


89
90
91
# File 'lib/skittles/client/venue.rb', line 89

def explore(ll, options = {})
  get('venues/explore', { :ll => ll }.merge(options)).groups
end

#flag_venue(id, problem) ⇒ Object

Allows a user to indicated a venue is incorrect in some way.

Parameters:

  • id (String)

    The venue id for which an edit is being proposed.

  • problem (String)

    One of mislocated, closed, duplicate.

See Also:


99
100
101
102
# File 'lib/skittles/client/venue.rb', line 99

def flag_venue(id, problem)
  post("venues/#{id}/flag", { :problem => problem })
  nil
end

#herenow(id, options = {}) ⇒ Hashie::Mash

Note:

This is an experimental API.

Provides a count of how many people are at a given venue, plus the first page of the users there, friends-first, and if the current user is authenticated.

Parameters:

  • id (String)

    Id of a venue to retrieve.

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

    A customizable set of options.

Options Hash (options):

  • limit (Integer)

    Number of results to return, up to 500.

  • offset (Integer)

    Used to page through results.

  • afterTimestamp (Integer)

    Retrieve the first results to follow these seconds since epoch.

Returns:

  • (Hashie::Mash)

    A count of items where items are checkins.

See Also:

Requires Acting User:

  • No


117
118
119
# File 'lib/skittles/client/venue.rb', line 117

def herenow(id, options = {})
  get("venues/#{id}/herenow", options).hereNow
end

#like_venue(id, set = 1) ⇒ Hashie::Mash

Allows the acting user to like or unlike a venue.

Parameters:

  • id (String)

    Id of the venue to like or unlike.

  • set (Integer) (defaults to: 1)

    If 1, like this venue. If 0 unlike this venue. Default is 1.

Returns:

  • (Hashie::Mash)

    Updated count and groups of users who like this venue.

See Also:

Requires Acting User:

  • Yes


128
129
130
# File 'lib/skittles/client/venue.rb', line 128

def like_venue(id, set = 1)
  post("venues/#{id}/like", { :set => set }).likes
end

#managed_venuesHashie::Mash

Get a list of venues the current user manages.

Returns:

  • (Hashie::Mash)

    An array of compact venues the user manages.

See Also:


137
138
139
# File 'lib/skittles/client/venue.rb', line 137

def managed_venues
  get('venues/managed').venues
end
Note:

In some cases, menu information is provided by a partner. When displaying information from a partner, you must attribute them as specified on the Foursquare Developers site.

Returns menu information for a venue.

Parameters:

  • id (String)

    The venue id for which menu is being requested.

Returns:

  • (Hashie::Mash)

    Name of the provider of the menu information and a count and items of menu.

See Also:


148
149
150
# File 'lib/skittles/client/venue.rb', line 148

def menu(id)
  get("venues/#{id}/menu")
end

#photos(id, group = 'checkin', options = {}) ⇒ Hashie::Mash

Returns A count of items of photo.

Parameters:

  • id (String)

    The venue you want photos for.

  • group (String) (defaults to: 'checkin')

    One of checkin, venue or multi (for both).

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

    A customizable set of options.

Options Hash (options):

  • limit (Integer)

    Number of results to return, up to 500.

  • offset (Integer)

    Used to page through results.

Returns:

  • (Hashie::Mash)

    A count of items of photo.

See Also:

Requires Acting User:

  • No


162
163
164
# File 'lib/skittles/client/venue.rb', line 162

def photos(id, group = 'checkin', options = {})
  get("venues/#{id}/photos", {:group => group }.merge(options)).photos
end

#proposeedit(id, name, address, city, state, zip, ll, options = {}) ⇒ Object

Allows you to propose a change to a venue.

Parameters:

  • id (String)

    The venue id for which an edit is being proposed.

  • name (String)

    The name of the venue.

  • address (String)

    The address of the venue.

  • city (String)

    The city name where the venue is.

  • state (String)

    The nearest state or province to the venue.

  • zip (String)

    The zip or postal code for the venue.

  • ll (String)

    Latitude and longitude of the venue's location, as accurate as is known.

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

    A customizable set of options.

Options Hash (options):

  • crossStreet (String)

    The nearest intersecting street or streets.

  • phone (String)

    The phone number of the venue.

  • primaryCategoryId (String)

    The id of the category to which you want to assign this venue.

See Also:

Requires Acting User:

  • Yes


181
182
183
184
185
186
187
188
189
190
191
# File 'lib/skittles/client/venue.rb', line 181

def proposeedit(id, name, address, city, state, zip, ll, options = {})
  post("venues/#{id}/proposeedit", {
    :name => name,
    :address => address,
    :city => city,
    :state => state,
    :zip => zip,
    :ll => ll
  }.merge(options))
  nil
end

#similar_venues(id) ⇒ Hashie::Mash

Returns a list of venues similar to the specified venue.

Parameters:

  • id (String)

    The venue you want similar venues for.

Returns:

  • (Hashie::Mash)

    A count and items of similar venues.

See Also:

Requires Acting User:

  • Yes


199
200
201
# File 'lib/skittles/client/venue.rb', line 199

def similar_venues(id)
  get("venues/#{id}/similar").similarVenues
end

#timeseries(ids, start_at, options = {}) ⇒ Hashie::Mash

Get daily venue stats for a list of venues over a time range.

Parameters:

  • ids (Array)

    A string array of venue ids to retrieve series data for.

  • start_at (Integer)

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

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

    A customizable set of options.

Returns:

  • (Hashie::Mash)

    An array of venue time series data objects, one for each venue.

See Also:


212
213
214
215
# File 'lib/skittles/client/venue.rb', line 212

def timeseries(ids, start_at, options = {})
  ids = ids.joing(',') if ids.kind_of? Array
  get('venues/timeseries', { :venueId => ids, :startAt => start_at }.merge(options))
end
Note:

This is an experimental API.

Returns a list of venues near the current location with the most people currently checked in.

Parameters:

  • ll (String)

    Latitude and longitude of the user's location.

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

    A customizable set of options.

Options Hash (options):

  • limit (Integer)

    Number of results to return, up to 50.

  • radius (Integer)

    Radius in meters, up to approximately 2000 meters.

Returns:

  • An array of venues that are currently trending, with their hereNow populated.

See Also:

Requires Acting User:

  • No


228
229
230
# File 'lib/skittles/client/venue.rb', line 228

def trending(ll, options = {})
  get('venues/trending', { :ll => ll }.merge(options)).venues
end

#venue(id) ⇒ Hashie::Mash

specials and category.

Authenticated users will also receive information about who is here now.

If the venue id given is one that has been merged into another “master” venue, the response will show data about the “master” instead of giving you an error.

Parameters:

  • id (String)

    Id of a venue to retrieve.

Returns:

  • (Hashie::Mash)

    Details about a venue, including location, mayorship, tags, tips, specials, and category.

See Also:

Requires Acting User:

  • No


245
246
247
# File 'lib/skittles/client/venue.rb', line 245

def venue(id)
  get("venues/#{id}").venue
end

#venue_events(id) ⇒ Object

Allows access to information about the current events at a place.

At this time we are only able to distrubute Music events and limited information about Movie events via this endpoint due to partner restrictions.

Parameters:

  • id

    Id of the venue to return event information for.

Returns:

  • A count and items of event items.

See Also:

Requires Acting User:

  • No


257
258
259
# File 'lib/skittles/client/venue.rb', line 257

def venue_events(id)
  get("venues/#{id}/events").events
end

#venue_hours(id) ⇒ Object

Returns hours for a venue

Returns:

  • An array of timeframes for hours.

See Also:

Requires Acting User:

  • No


267
268
269
# File 'lib/skittles/client/venue.rb', line 267

def venue_hours(id)
  get("venues/#{id}/hours").hours
end

#venue_likes(id) ⇒ Object

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

Parameters:

  • id

    Id of the venue to return likes for.

Returns:

  • A count and groups of users who like this venue.

See Also:

Requires Acting User:

  • No


277
278
279
# File 'lib/skittles/client/venue.rb', line 277

def venue_likes(id)
  get("venues/#{id}/likes").likes
end
Note:

This is an experimental API.

Returns URLs or identifier from third parties that have been applied to this venue.

Parameters:

  • id (String)

    The venue you want annotations for.

Returns:

  • (Hashie::Mash)

    A count and items of links.

See Also:

Requires Acting User:

  • No


289
290
291
# File 'lib/skittles/client/venue.rb', line 289

def venue_links(id)
  get("venues/#{id}/links").links
end

#venue_listed(id, options = {}) ⇒ Hashie::Mash

The lists that a venue appears on.

Parameters:

  • id (String)

    The venue to get lists for.

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

    A customizable set of options.

Options Hash (options):

  • group (String)

    Either created, edited, followed, friends or suggested.

Returns:

  • (Hashie::Mash)

    The lists a venue appears on.

See Also:


301
302
303
# File 'lib/skittles/client/venue.rb', line 301

def venue_listed(id, options = {})
  get("venues/#{id}/listed", options).lists
end

#venue_marktodo(id, options = {}) ⇒ Hashie::Mash

Deprecated.

Allows a user to mark a venue to-do, with optional text.

Parameters:

  • id

    The venue you want to mark to-do.

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

    A customizable set of options.

Options Hash (options):

  • text (String)

    The text of the tip.

Returns:

  • (Hashie::Mash)

    The newly-added to-do, which contains a tip created implicitly.

See Also:

Requires Acting User:

  • Yes


314
315
316
# File 'lib/skittles/client/venue.rb', line 314

def venue_marktodo(id, options = {})
  post("venues/#{id}/marktodo").todo
end

#venue_photos(id, group = 'checkin', options = {}) ⇒ Hashie::Mash

Returns photos for a venue.

Parameters:

  • id (String)

    The venue you want photos for.

  • group (String) (defaults to: 'checkin')

    One of checkin, venue or multi (for both).

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

    A customizable set of options.

Options Hash (options):

  • limit (Integer)

    Number of results to return, up to 500.

  • offset (Integer)

    Used to page through results.

Returns:

  • (Hashie::Mash)

    A count of items of photo.

See Also:

Requires Acting User:

  • No


328
329
330
# File 'lib/skittles/client/venue.rb', line 328

def venue_photos(id, group = 'checkin', options = {})
  get("venues/#{id}/photos", {:group => group }.merge(options)).photos
end

#venue_search(ll, options = {}) ⇒ Hashie::Mash

Returns a list of venues near the current location, optionally matching the search term.

If lat and long is provided, each venue includes a distance. If authenticated, the method will return venue metadata related to you and your friends. If you do not authenticate, you will not get this data.

Parameters:

  • ll (String)

    Latitude and longitude of the user's location, so response can include distance.

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

    A customizable set of options.

Options Hash (options):

  • llAcc (Decimal)

    Accuracy of latitude and longitude, in meters.

  • alt (Decimal)

    Altitude of the user's location, in meters.

  • altAcc (Decimal)

    Accuracy of the user's altitude, in meters.

  • query (String)

    A search term to be applied against titles.

  • limit (Integer)

    Number of results to return, up to 50.

  • intent (String)

    Indicates your intent in performing the search.

  • radius (Integer)

    Limit results to venues within this many meters of the specified location.

  • sw (Decimal)

    With ne, limits results to the bounding quadrangle defined by the latitude and longitude given by sw as its south-west corner, and ne as its north-east corner.

  • ne (Decimal)

    See sw

  • categoryId (String)

    A category to limit the results to. (experimental)

  • url (String)

    A third-party URL which is attempted to match against a map of venues to URLs. (experimental)

  • providerId (String)

    Identifier for a known third party that is part of a map of venues to URLs, used in conjunction with linkedId. (experimental)

  • linkedId (Integer)

    Identifier used by third party specified in providerId, which will be attempted to match against a map of venues to URLs. (experimental)

Returns:

  • (Hashie::Mash)

    An array of objects representing groups of venues.

See Also:

Requires Acting User:

  • No


357
358
359
# File 'lib/skittles/client/venue.rb', line 357

def venue_search(ll, options = {})
  get('venues/search', { :ll => ll }.merge(options)).venues
end

#venue_stats(id, options = {}) ⇒ Hashie::Mash

Get venue stats over a given time range.

Parameters:

  • ids (String)

    The venue id to retrieve stats for.

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

    A customizable set of options.

Returns:

  • (Hashie::Mash)

    A venue stats object.

See Also:


370
371
372
# File 'lib/skittles/client/venue.rb', line 370

def venue_stats(id, options = {})
  get("venues/#{id}/stats", options)
end

#venue_suggestcompletion(ll, query, options = {}) ⇒ Hashie::Mash

Note:

This is an experimental API.

Returns a list of mini-venues matching the search term, near the location.

Parameters:

  • ll (String)

    Latitude and longitude of the user's location. (Required for query searches)

  • query (String)

    A search term to be applied against titles. Must be at least 3 characters long.

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

    A customizable set of options.

Options Hash (options):

  • llAcc (Decimal)

    Accuracy of latitude and longitude, in meters. (Does not currently affect search results)

  • alt (Decimal)

    Altitude of the user's location, in meters. (Does not currently affect search results.)

  • altAcc (Decimal)

    Accuracy of the user's altitude, in meters. (Does not currently affect search results.)

  • limit (Integer)

    Number of results to return, up to 100.

Returns:

  • (Hashie::Mash)

    An array of venue objects.

See Also:


387
388
389
# File 'lib/skittles/client/venue.rb', line 387

def venue_suggestcompletion(ll, query, options = {})
  get('venues/suggestcompletion', { :ll => ll, :query => query }.merge(options)).minivenues
end

#venue_tips(id, options = {}) ⇒ Hashie::Mash

Returns tips for a venue.

Parameters:

  • id (String)

    The venue you want tips for.

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

    A customizable set of options.

Options Hash (options):

  • sort (String)

    One of recent or popular.

  • limit (Integer)

    Number of results to return, up to 500.

  • offset (Integer)

    Used to page through results.

Returns:

  • (Hashie::Mash)

    A count of items of tips.

See Also:

Requires Acting User:

  • No


401
402
403
# File 'lib/skittles/client/venue.rb', line 401

def venue_tips(id, options = {})
  get("venues/#{id}/tips", options).tips
end