Module: Foursquared::Venues

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

Overview

Venues module

Instance Method Summary collapse

Instance Method Details

#add_venue(options = {}) ⇒ Object

Add a venue

Parameters:

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

Options Hash (options):

  • :name (String) —

    required The name of the venue

  • :address (String) —

    The address of the venue

  • :crossStreet (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.

  • :twitter (String) —

    The twitter handle of the venue.

  • :ll (String) —

    required 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.

  • :description (String) —

    A freeform description of the venue, up to 300 characters.

  • :url (String) —

    The url of the homepage of the venue.

  • :ignoreDuplicates (Boolean) —

    A boolean flag telling the server to ignore duplicates and force the addition of this venue.

  • :ignoreDuplicatesKey (String) —

    Required if ignoreDuplicates is true. This key will be available in the response of the HTTP 409 error of the first (failed) attempt to add venue.



30
31
32
33
 
# File 'lib/foursquared/venues.rb', line 30

def add_venue options={}
  response = post("/venues/add", options)["response"]
  Foursquared::Response::Venue.new(self, response["venue"])
end

#explore_venues(options = {}) ⇒ Object

Explore Recommended and Popular Venues

Parameters:

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

Options Hash (options):

  • :ll (String) —

    required unless :near is provided. Latitude and longitude of the user’s location.

  • :near (String) —

    required unless :ll is provided. A string naming a place in the world

  • :llAcc (String) —

    Accuracy of latitude and longitude, in meters.

  • :alt (String) —

    Altitude of the user’s location, in meters.

  • :altAcc (String) —

    Accuracy of the user’s altitude, in meters.

  • :radius (String) —

    Radius to search within, in meters.

  • :section (String) —

    One of food, drinks, coffee, shops, arts, outdoors, sights, trending or specials, nextVenues or topPicks

  • :query (String) —

    A term to be searched against a venue’s tips, category, etc.

  • :limit (Integer) —

    Number of results to return, up to 50.

  • :offset (Integer) —

    Used to page through results.

  • :novelty (String) —

    Pass new or old to limit results to places the acting user hasn’t been or has been, respectively.

  • :friendVisits (String) —

    Pass visited or notvisited to limit results to places the acting user’s friends have or haven’t been, respectively.

  • :venuePhotos (String) —

    Boolean flag to include a photo in the response for each venue, if one is available (1/0)

  • :lastVenue (String) —

    A venue ID to use in combination with the intent=nextVenues parameter, which returns venues users often visit after a given venue.



58
59
60
61
62
63
64
65
66
67
 
# File 'lib/foursquared/venues.rb', line 58

def explore_venues options={}
  response = get("/venues/explore", options)["response"]
  response["groups"].each do |group|
    response["items"].each do |item|
      item["venue"] = Foursquared::Response::Venue.new(self, item["venue"])
      item["tips"].map!{|tip| Foursquared::Response::List.new(self, tip)}
    end
  end
  response
end

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

Flag a Venue

Parameters:

  • venue_id (String) —

    required The venue id for which hours are being requested.

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

Options Hash (options):

  • :problem (String) —

    required One of mislocated, closed, duplicate, inappropriate, doesnt_exist, event_over

  • :venueId (String) —

    ID of the duplicated venue (for problem duplicate)



184
185
186
 
# File 'lib/foursquared/venues.rb', line 184

def flag_venue venue_id, options={}
  response = post("/venues/#{venue_id}/flag", options)
end

#like_venue(venue_id, options = {}) ⇒ Hash

Like or unlike a venue

Parameters:

  • venue_id (String) —

    required The venue id for which hours are being requested.

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

Options Hash (options):

  • :set (Integer) —

    If 1, like this venue. If 0 unlike (un-do a previous like) it. Default value is 1.

Returns:

  • (Hash) —

    Updated count and groups of users who like this venue



193
194
195
196
197
198
199
 
# File 'lib/foursquared/venues.rb', line 193

def like_venue venue_id, options={}
  response = post("/venues/#{venue_id}/like", options)["response"]["likes"]
  response["groups"].each do |group|
    response["items"].map!{|item| Foursquared::Response::User.new(self, item)}
  end
  response
end

#managed_venues ⇒ Array<Foursquared::Response::Venue>

Get a list of venues the current user manages.

Returns:



71
72
73
74
 
# File 'lib/foursquared/venues.rb', line 71

def managed_venues
  response = get("/venues/managed")["response"]
  @venues = response["venues"].collect{|venue| Foursquared::Response::Venue.new(self, venue)}
end

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

Propose an Edit to a Venue

Parameters:

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

Options Hash (options):

  • :name (String) —

    The name of the venue

  • :address (String) —

    The address of the venue

  • :crossStreet (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.

  • :hours (String) —

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



213
214
215
 
# File 'lib/foursquared/venues.rb', line 213

def propose_venue_edit venue_id, options={}
  response = post("/venues/#{venue_id}", options)
end

#search_venues(options = {}) ⇒ Array

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

Parameters:

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

Options Hash (options):

  • :ll (String) —

    required unless :near is provided. Latitude and longitude of the user’s location.

  • :near (String) —

    required unless :ll is provided. A string naming a place in the world

  • :llAcc (String) —

    Accuracy of latitude and longitude, in meters.

  • :alt (String) —

    Altitude of the user’s location, in meters.

  • :altAcc (String) —

    Accuracy of the user’s altitude, in meters.

  • :radius (String) —

    Radius to search within, in meters.

  • :query (String) —

    A search term to be applied against venue names.

  • :limit (Integer) —

    Number of results to return, up to 50.

  • :intent (String) —

    Checkout developer.foursquare.com/docs/venues/search for the possible values

  • :sw (String) —

    Checkout developer.foursquare.com/docs/venues/search for details

  • :ne (String) —

    Checkout developer.foursquare.com/docs/venues/search for details

  • :categoryId (String) —

    A comma separated list of categories to limit results to

  • :url (String) —

    A third-party URL which we will attempt to match against our map of venues to URLs

  • :providerId (String) —

    Identifier for a known third party that is part of our map of venues to URLs

  • :linkedId (String) —

    Identifier used by third party specified in providerId, which we will attempt to match against our map of venues to URLs

Returns:

  • (Array) —

    An array of compact venues.



94
95
96
97
 
# File 'lib/foursquared/venues.rb', line 94

def search_venues options={}
  response = get("/venues/search", options)["response"]
  @venues = response["venues"].collect{|venue| Foursquared::Response::Venue.new(self, venue)}
end

#trending_venues(options = {}) ⇒ Array

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

Parameters:

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

Options Hash (options):

  • :ll (String) —

    required Latitude and longitude of the user’s location.

  • :limit (Integer) —

    Number of results to return, up to 50.

  • :radius (Integer) —

    Radius in meters, up to approximately 2000 meters.

Returns:

  • (Array) —

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



105
106
107
108
 
# File 'lib/foursquared/venues.rb', line 105

def trending_venues options={}
  response = get("/venues/trending", options)["response"]
  @venues = response["venues"].collect{|venue| Foursquared::Response::Venue.new(self, venue)}
end

#venue(venue_id) ⇒ Foursquared::Response::Venue

Venue detail

Parameters:

  • venue_id (String) —

    ID of venue to retrieve

Returns:



9
10
11
12
 
# File 'lib/foursquared/venues.rb', line 9

def venue venue_id
  response = get("/venues/#{venue_id}")["response"]
  @venue = Foursquared::Response::Venue.new(self, response["venue"])
end

#venue_categories ⇒ Array<Foursquared::Response::Category>

Returns a hierarchical list of categories applied to venues.

Returns:



37
38
39
40
 
# File 'lib/foursquared/venues.rb', line 37

def venue_categories
  response = get("/venues/categories")["response"]
  response["categories"].collect{|category| Foursquared::Response::Category.new(self, category) }
end

#venue_events(venue_id) ⇒ Hash

Gives information about the current events at a place.

Parameters:

  • venue_id (String) —

    required The venue id for which events are being requested.

Returns:

  • (Hash) —

    A count and items of event items. Also includes a “summary” string describing the set of events at the venue.



113
114
115
116
117
118
 
# File 'lib/foursquared/venues.rb', line 113

def venue_events venue_id
  response = get("/venues/#{venue_id}/events")["response"]
  @events = response["events"]
  @events["items"].map!{|item| Foursquared::Response::Event.new(self, item)}
  @events
end

#venue_hours(venue_id) ⇒ Array

Returns hours for a venue.

Parameters:

  • venue_id (String) —

    required The venue id for which hours are being requested.

Returns:

  • (Array) —

    An array of timeframes of hours.



123
124
125
 
# File 'lib/foursquared/venues.rb', line 123

def venue_hours venue_id
  response = get("/venues/#{venue_id}/hours")["response"]["hours"]
end

#venue_likes(venue_id) ⇒ Hash

Returns a list of venues similar to the specified venue.

Parameters:

  • venue_id (String) —

    required The venue you want similar venues for.

Returns:

  • (Hash) —

    A count and items of similar venues.



130
131
132
133
134
135
136
 
# File 'lib/foursquared/venues.rb', line 130

def venue_likes venue_id
  response = get("/venues/#{venue_id}/likes")["response"]["likes"]
  response["groups"].each do |group|
    response["items"].map!{|item| Foursquared::Response::User.new(self, item)}
  end
  response
end

#venue_lists(venue_id, options = {}) ⇒ Hash

The lists that this venue appears on.

Parameters:

  • venue_id (String) —

    required The venue id for which hours are being requested.

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

Options Hash (options):

  • :group (String) —

    Can be created, edited, followed, friends, other.

  • :limit (Integer) —

    Number of results to return, up to 200.

  • :offset (Integer) —

    Used to page through results. Must specify a group

Returns:

  • (Hash) 


145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/foursquared/venues.rb', line 145

def venue_lists venue_id, options={}
  response = get("/venues/#{venue_id}/lists", options)["response"]["lists"]
  if response["groups"]
    response["groups"].each do |group|
      group["items"].map!{|item| Foursquared::Response::Lists.new(self, item)} if group["items"]
    end
  else
    response["items"].map!{|item| Foursquared::Response::Lists.new(self, item)}
  end
  response
end

#venue_photos(venue_id, options = {}) ⇒ Hash

Returns photos for a venue.

Parameters:

  • venue_id (String) —

    required The venue id for which hours are being requested.

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

Options Hash (options):

  • :group (String) —

    required Pass checkin for photos added by friends (including on their recent checkins). Pass venue for public photos added to the venue by non-friends. Use multi to fetch both.

  • :limit (Integer) —

    Number of results to return, up to 200.

  • :offset (Integer) —

    Used to page through results

Returns:

  • (Hash) —

    A count and items of photos



164
165
166
167
168
 
# File 'lib/foursquared/venues.rb', line 164

def venue_photos venue_id, options={}
  response = get("/venues/#{venue_id}/photos", options)["response"]["photos"]
  response["items"].map!{|item| Foursquared::Response::Photo.new(self, item)}
  response
end