foursquare 0.1.0 → 0.2.0

data/History

@@ -1,3 +1,9 @@
+== 0.2.0 February 7th, 2010
+* updated methods to reflect updates to Foursquare API
+* added validations
+* deprecated cities, check_city, switch_city, and friend_checkins calls in line with updates to the Foursquare API
+* updated readme to reflect code changes
+
 == 0.1.0 November 8th, 2009
 * added website
 * added defaults for optional method variables

data/README.rdoc

@@ -10,24 +10,41 @@ A simple Ruby Gem wrapper for the Foursquare API.
 	
 	require 'rubygems'
 	require 'foursquare'
-
+  
+  # foursquare's site uses email as the user name
 	fq = Foursquare.new('username_or_phone','password')
 
 	fq.test
-	fq.cities
-	fq.venues(lat,long,radius,limit,query)
-	fq.tips(lat,long,limit)
-	fq.check_city(lat, long)
-	fq.switch_city(city_id)
-	fq.friend_checkins
-	fq.checkin(vid,venue,shout,private_checkin,tweetThis,geolat,geolong)
-	fq.history(limit)
-	fq.user_details(user_id,badges,mayor)
-	fq.friends
+
+	fq.venues(geolat, geolong, {:limit=>10,:q=>'pizza'})
+	fq.tips(geolat,geolong,{:limit=>10})
+	fq.checkins({:geolat=>'',:geolong=>''})
+	fq.checkin(vid,venue,shout,{:private=>0,:twitter=>0,:facebook=>1,:geolat=>'12.03',:geolong=>'-123.33'})
+	fq.history({:limit=>10})
+	fq.user_details(user_id,{:badges=>0,:mayor=>0})
+	fq.friends({:uid=>99999})
 	fq.venue_details(venue_id)
-	fq.add_venue(city_id,name,address,cross_street,city,state,zip,phone)
-	fq.add_tip(venue_id,text,type)
-	
+	fq.add_venue(name,address,cross_street,city,state,options)
+	fq.propose_edit(venue_id,name,address,cross_street,city,state,options)
+	fq.flag_venue_as_closed(venue_id)
+	fq.add_tip(venue_id,text,{:type=type})
+	fq.mark_tip_as_todo(tid)
+	fq.mark_tip_as_done(tid)
+	fq.friend_requests
+	fq.friend_approve(uid)
+	fq.friend_deny(uid)
+	fq.request_friend(uid)
+	fq.find_friends_by_name('Bugs Bunny')
+	fq.find_friends_by_phone('8675309')
+	fq.find_friends_by_twitter('github')
+	fq.set_pings('self','goodnight')
+
+
+  # Foursquare is moving the API to geolat/geolong and removing the concept of cities
+	fq.cities	
+	fq.check_city(geolat, geolong)
+	fq.switch_city(city_id)	
+	fq.friend_checkins({:geolat=>'',:geolong=>''})
 	
 == license 
 

data/Rakefile

@@ -6,8 +6,8 @@ require 'spec/rake/spectask'
 
 spec = Gem::Specification.new do |s|
   s.name = "foursquare"
-  s.version = "0.1.0"
-  s.author = "Jeremy Welch"
+  s.version = "0.2.0"
+  s.authors = ['Jeremy Welch', 'Thomas Hanley']
   s.email = "hello@jeremyrwelch.com"
   s.homepage = "http://foursquare.rubyforge.org"
   s.description = s.summary = "A simple Ruby wrapper for the Foursquare API"

data/lib/foursquare.rb

@@ -2,76 +2,196 @@ require 'rubygems'
 require 'httparty'
 
 class Foursquare
+  # Current Version of the Foursquare API: http://groups.google.com/group/foursquare-api/web/api-documentation
   
   include HTTParty
   base_uri 'api.foursquare.com'
   format :xml
-  
 
-# auth user    
-  def initialize(user="",pass="")
+  # auth user
+  # TODO: add OAuth support (follow Twitter gem from jnunemaker http://github.com/jnunemaker/twitter)
+  def initialize(user="",pass="", options={})
     self.class.basic_auth user, pass
+    self.class.headers(options[:headers]) if options.has_key?(:headers)
   end
-  
-  
-# test for response from Foursquare
+
+  # =========================
+  # = No Auth Required Methods =
+  # =========================
+  # test for response from Foursquare
   def test 
-    self.class.get("/v1/test") 
+      self.class.get("/v1/test") 
   end
 
-# no auth required 
-  def cities
-    self.class.get("/v1/cities")
-  end
-  
-  def venues(geolat,geolong,radius="",limit="",query="")
-    self.class.get("/v1/venues?geolat=#{geolat}&geolong=#{geolong}&r=#{radius}&l=#{limit}&q=#{query}")
+  def venues(geolat, geolong, options={})
+      options.merge!({:geolat=>geolat, :geolong=>geolong})
+      self.class.get("/v1/venues", :query=>options)
   end
-  
-  def tips(geolat,geolong,limit="")
-    self.class.get("/v1/tips?geolat=#{geolat}&geolong=#{geolong}&l=#{limit}")
+
+  def tips(geolat,geolong,options={})
+      options.merge!({:geolat=>geolat, :geolong=>geolong})
+      self.class.get("/v1/tips", :query=>options)
   end
 
+  # =========================
+  # = Auth Required Methods =
+  # =========================
+  def checkins(options={})
+    self.class.get("/v1/checkins",:query=>options)
+  end 
 
-# auth required
-  def check_city(geolat, geolong) 
-    self.class.get("/v1/checkcity?geolat=#{geolat}&geolong=#{geolong}")
+  def checkin(vid=nil,venue=nil,shout=nil,options={})
+    unless vid || venue || shout
+      raise ArgumentError, "A vid or venue or shout is required to checkin", caller
+    end
+    options.merge!({:vid=>vid, :venue=>venue, :shout=>shout})    
+    self.class.post("/v1/checkin", :body => options)       
   end
-
-  def switch_city(city_id)
-    self.class.post("/v1/switchcity", :body => {:cityid => city_id})
+  
+  def history(options={})
+    limit = options.delete(:limit) || 10
+    uri = "/v1/history?l=#{limit}"
+    sinceid = options.delete(:sinceid)
+    uri << "&sinceid=#{sinceid}" unless sinceid.nil?
+    self.class.get(uri)
   end
-
-  def friend_checkins
-    self.class.get("/v1/checkins")
+  
+  def user_details(user_id,options={})
+    unless user_id
+      raise ArgumentError, "A user_id is required to get details about a user", caller
+    end    
+    self.class.get("/v1/user",:query=>options)
   end
   
-  def checkin(vid,venue,shout,private_checkin,tweetThis,geolat,geolong)
-    self.class.get("/v1/checkin?vid=#{vid}&venue=#{venue}&shout=#{shout}&private=#{private_checkin}&twitter=#{tweetThis}&geolat=#{geolat}&geolong=#{geolong}")
+  def friends(options={})
+    self.class.get("/v1/friends",:query=>options)
   end
   
-  def history(limit="10")
-    self.class.get("/v1/history?l=#{limit}")
+  def venue_details(venue_id)                        
+    self.class.get("/v1/venue?vid=#{venue_id}")
+  end
+
+  # city_id has been removed from API
+  def add_venue(name,address,cross_street,city,state,options={})
+    unless name && address && cross_street && city && state
+      raise ArgumentError, "A venue's name, address, cross_street, city, state are required to add_venue", caller
+    end                            
+    options.merge!({:name=>name, :address=>address, :cross_street=>cross_street, :city=>city, :state=>state})
+    self.class.post("/v1/addvenue", :body => options)
   end
   
-  def user_details(user_id,badges="0",mayor="0")
-    self.class.get("/v1/user?uid=#{user_id}&badges=#{badges}&mayor=#{mayor}")
+  def propose_edit(venue_id,name,address,cross_street,city,state,options={})
+    unless venue_id && name && address && cross_street && city && state
+      raise ArgumentError, "A venue's venue_id, name, address, cross_street, city, state are required to propose_edit", caller
+    end
+    options.merge!({:venue_id=>venue_id,:name=>name, :address=>address, :cross_street=>cross_street, :city=>city, :state=>state})
+    self.class.post("/v1/venue/proposeedit", :body => options)
+  end
+     
+  def flag_venue_as_closed(venue_id)
+    unless venue_id
+      raise ArgumentError, "A venue's venue_id is required to flag as closed", caller
+    end
+    self.class.post("/v1/venue/flagclosed?vid=#{venue_id}")
   end
   
-  def friends
-    self.class.get("/v1/friends")
+  # ===============
+  # = TIP methods =
+  # ===============
+  def add_tip(venue_id,text,options={})
+    unless venue_id && text
+      raise ArgumentError, "venue_id and text are required to add_tip", caller
+    end                      
+    options.merge!({:vid=>venue_id, :text=>text})
+    self.class.post("/v1/addtip", :body => options)
   end
   
-  def venue_details(venue_id)
-    self.class.get("/v1/venue?vid=#{venue_id}")
+  def mark_tip_as_todo(tid)
+    unless tid 
+      raise ArgumentError, "tip_id is required to mark tip as todo", caller
+    end
+    self.class.post("/v1/tip/marktodo", :body => {:tip=>tip})
+  end 
+     
+  def mark_tip_as_done(tid)
+    unless tid 
+      raise ArgumentError, "tid is required to mark tip as done", caller
+    end
+    self.class.post("/v1/tip/markdone", :body => {:tip=>tip})
+  end
+
+  # ==================
+  # = FRIEND Methods =
+  # ==================
+  def friend_requests
+     self.class.get("/v1/friend/requests")
+  end
+
+  def friend_approve(uid)
+    unless uid 
+      raise ArgumentError, "uid is required to approve friend request", caller
+    end
+    self.class.post("/v1/friend/requests", :body => {:uid=>uid})
+  end
+     
+  def friend_deny(uid)
+    unless uid 
+      raise ArgumentError, "uid is required to deny friend request", caller
+    end
+    self.class.post("/v1/friend/deny", :body => {:uid=>uid})
+  end
+     
+  def request_friend(uid)
+    unless uid 
+      raise ArgumentError, "uid is required to request friend", caller
+    end
+    self.class.post("/v1/friend/sendrequest", :body => {:uid=>uid})
   end
   
-  def add_venue(city_id,name,address,cross_street,city,state,zip="",phone="")
-    self.class.post("/v1/addvenue", :body => {:name => name, :address => address, :crossstreet => cross_street, :city => city, :state => state, :zip => zip, :cityid => city_id, :phone => phone})
+  # ================
+  # = FIND Methods =
+  # ================
+  def find_friends_by_name(q)
+    self.class.get("/v1/findfriends/byname", :query=>{:q=>q})
+  end 
+
+  def find_friends_by_phone(q)
+    self.class.get("/v1/findfriends/byphone", :query=>{:q=>q})
+  end 
+
+  def find_friends_by_twitter(q)
+    self.class.get("/v1/findfriends/bytwitter", :query=>{:q=>q})
+  end 
+
+  # ===============
+  # = SET methods =
+  # ===============
+  def set_pings(user_id=nil,ping=nil)
+    uid = user_id || "self"
+    self.class.post("/v1/settings/setpings?#{uid}=#{ping}")
   end
   
-  def add_tip(venue_id,text,type)
-    self.class.post("/v1/addtip", :body => {:vid => venue_id, :text => text, :type => type})
+  # From Foursquare API
+  # 20100108 - naveen - the concept of cities (cityid and all city-related methods) has now been removed
+  # Deprecated
+  def cities
+      self.class.get("/v1/cities")
   end
+  # Deprecated
+    def check_city(geolat, geolong) 
+      $stderr.puts "`check_city` Deprecated: The idea of \"cityid\" is now deprecated from the API"
+      self.class.get("/v1/checkcity?geolat=#{geolat}&geolong=#{geolong}")
+    end
+  # Deprecated
+    def switch_city(city_id)
+      $stderr.puts "`switch_city` Deprecated: The idea of \"cityid\" is now deprecated from the API"
+      self.class.post("/v1/switchcity", :body => {:cityid => city_id})
+    end
+  # Method changed to call checkins to match API
+    def friend_checkins(options={})
+        $stderr.puts "`friend_checkins` now calls `checkins` to match the foursquare api method call"
+        $stderr.puts "http://groups.google.com/group/foursquare-api/web/api-documentation"
+        checkins(options)
+    end
   
 end

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification 
 name: foursquare
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Jeremy Welch
+- Thomas Hanley
 autorequire: foursquare
 bindir: bin
 cert_chain: []
 
-date: 2009-11-08 00:00:00 -05:00
+date: 2010-02-07 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency