pezra-fireeagle 0.9.0.1

data/History.txt

@@ -0,0 +1,41 @@
+== 0.9.0
+
+* Support for OAuth 1.0a
+
+== 0.8.0.0
+
+* Update recent method
+
+== 0.7.1.0
+
+* Fix OAuth Dependency Issue
+
+== 0.6.3
+
+* Bugfix for Ruby 1.9
+
+== 0.6.2
+
+* Offload heavy lifting to OAuth for tokens and signing requests
+* Add time parameter to Client#recent
+* Change lookup params from :cid to :cellid to follow Fire Eagle
+* Cleaned up specs
+
+== 0.6.1
+
+* Remove 'not implemented' message
+* Remove JSON requirement
+
+== 0.6.0
+
+* Complete rewrite
+
+== 0.0.2
+
+* Fix callback_url
+* Add token_url
+
+== 0.0.1
+
+* Initial version
+* Works

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Jesse Newland
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,21 @@
+config/hoe.rb
+config/requirements.rb
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/fireeagle.rb
+lib/fireeagle/client.rb
+lib/fireeagle/location.rb
+lib/fireeagle/response.rb
+lib/fireeagle/user.rb
+lib/fireeagle/version.rb
+setup.rb
+spec/fireeagle_location_spec.rb
+spec/fireeagle_response_spec.rb
+spec/fireeagle_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/environment.rake
+tasks/rspec.rake

data/README.txt

@@ -0,0 +1,52 @@
+FireEagle[http://fireeagle.yahoo.net] (FE) is a system providing centralized
+management of user location information. FE allows 3rd party developers to
+pdate and/or access user's location data.
+
+http://fireeagle.yahoo.net/developer/documentation
+
+== Installation
+
+ gem install fireeagle
+ 
+== Usage
+
+  >> require 'fireeagle'
+  >> client = FireEagle::Client.new(
+    :consumer_key        => "<consumer key>",
+    :consumer_secret     => "<consumer secret>",
+    :access_token        => "[access token]",
+    :access_token_secret => "[access token secret]")
+
+==== With a User-specific OAuth Access Token
+
+  # update your location
+  >> client.update(:q => "punta del diablo, uruguay") # I wish
+  # query your location
+  >> user = client.user
+  => #<FireEagle::User:0x1ca5e08 ... >
+  >> user.locations
+  => [#<FireEagle::Location:0x1cdd9e8 ...>, #<FireEagle::Location:0x1cc8ffc ...>, ... ]
+  >> user.best_guess
+  => #<FireEagle::Location:0x1cdd9e8 ...>
+  >> user.best_guess.name
+  => "Punta del Diablo, Uruguay"
+  # lookup a location
+  >> locations = client.lookup(:q => "30022")
+  => [#<FireEagle::Location:0x1cdd9e8 ...>, #<FireEagle::Location:0x1cc8ffc ...>, ...]
+  >> locations.first.name => "Alpharetta, GA 30022"
+  >> locations.first.place_id => "IrhZMHuYA5s1fFi4Qw"
+
+== Authorization
+
+Authorization is handled by OAuth. For more details about the OAuth
+authorization flow and how it differs based on your application type, please
+see http://fireeagle.yahoo.net/developer/documentation/authorizing
+
+== Contributing
+
+http://github.com/jnewland/fireeagle/tree/master. You know what to do.
+
+Rubyforge Project Page:: http://rubyforge.org/projects/fireeagle
+Author::    Jesse Newland (http://soylentfoo.jnewland.com) (jnewland@gmail.com[mailto:jnewland@gmail.com])
+Copyright:: Copyright (c) 2008 Jesse Newland. Portions[http://pastie.caboo.se/private/oevvkdzl0zrdkf8s7hetg] Copyright (c) 2008 Yahoo!
+License::   Distributed under the same terms as Ruby

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,70 @@
+require 'fireeagle/version'
+
+AUTHOR = 'Jesse Newland'  # can also be an array of Authors
+EMAIL = "jnewland@gmail.com"
+DESCRIPTION = "Ruby wrapper for Yahoo!'s FireEagle"
+GEM_NAME = 'fireeagle' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'fireeagle' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "unknown"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = FireEagle::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'fireeagle rdoc',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' } 
+    @extra_deps
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.extra_deps = [ ['oauth', '>= 0.2.1'], ['hpricot', '>= 0.6'], ['GeoRuby', '>= 1.3.2'] ]     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+hoe.rsync_args = '-av --delete --ignore-errors'

data/config/requirements.rb

@@ -0,0 +1,18 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen oauth geo_ruby].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    req_gem = 'GeoRuby' if req_gem == 'geo_ruby' # gem not the same name
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))
+
+require 'fireeagle'

data/lib/fireeagle.rb

@@ -0,0 +1,66 @@
+require 'time'
+require 'net/https'
+require 'rubygems'
+gem 'oauth', ">= 0.2.4"
+require 'oauth/helper'
+require 'oauth/client/helper'
+require 'oauth/request_proxy/net_http'
+require 'hpricot'
+require 'geo_ruby'
+
+class FireEagle
+  API_SERVER = "https://fireeagle.yahooapis.com"
+  AUTH_SERVER = "https://fireeagle.yahoo.net"
+  REQUEST_TOKEN_PATH = "/oauth/request_token"
+  ACCESS_TOKEN_PATH  = "/oauth/access_token"
+  AUTHORIZATION_URL  = "#{AUTH_SERVER}/oauth/authorize"
+  MOBILE_AUTH_URL    = "#{AUTH_SERVER}/oauth/mobile_auth/"
+  USER_API_PATH      = "/api/0.1/user"
+  LOOKUP_API_PATH    = "/api/0.1/lookup"
+  UPDATE_API_PATH    = "/api/0.1/update"
+  RECENT_API_PATH    = "/api/0.1/recent"
+  WITHIN_API_PATH    = "/api/0.1/within"
+  FORMAT_XML         = "xml"
+  UPDATE_PARAMS      = :lat, :lon, :woeid, :place_id, :address, :mnc, :mcc, :lac, :cellid, :postal, :city, :state, :country, :q, :label
+                        # not yet supported
+                        #,:geom, :upcoming_venue_id, :yahoo_local_id, :plazes_id
+
+  class Error < RuntimeError #:nodoc:
+  end
+
+  class ArgumentError < Error #:nodoc:
+  end
+
+  class FireEagleException < Error #:nodoc:
+  end
+end
+
+# FireEagle additions to the <code>Hash</code> class
+class Hash
+  # Returns <code>true</code> if the ALL or NONE of the given keys are present in <i>my_keys</i>.
+  def has_all_or_none_keys?(*my_keys)
+    size = my_keys.length
+    false_count = 0
+    my_keys.each do |k|
+      false_count += 1 unless keys.include?(k)
+    end
+    false_count == 0 or false_count == size
+  end
+end
+
+# FireEagle addition to the <code>OAuth::Consumer</code> class
+class OAuth::Consumer
+  alias_method :create_http_with_verify, :create_http
+  # Monkey patch to silence the SSL warnings
+  def create_http_without_verify #:nodoc:
+    http_object             = create_http_with_verify
+    http_object.verify_mode = OpenSSL::SSL::VERIFY_NONE if uri.scheme=="https"
+    http_object
+  end
+  alias_method :create_http, :create_http_without_verify
+end
+
+require File.dirname(__FILE__) + '/fireeagle/client'
+require File.dirname(__FILE__) + '/fireeagle/location'
+require File.dirname(__FILE__) + '/fireeagle/user'
+require File.dirname(__FILE__) + '/fireeagle/response'

data/lib/fireeagle/client.rb

@@ -0,0 +1,320 @@
+class FireEagle
+  class Client
+    # TODO add access_token=() and request_token=() methods that check whether the tokens are usable
+    
+    attr_reader :access_token, :request_token, :consumer, :format
+
+    # Initialize a FireEagle Client. Takes an options Hash.
+    #
+    # == Required keys:
+    #
+    # [<tt>:consumer_key</tt>]       OAuth Consumer key representing your FireEagle Application
+    # [<tt>:consumer_secret</tt>]    OAuth Consumer secret representing your FireEagle Application
+    #
+    # == Optional keys:
+    #
+    # [<tt>:request_token</tt>]           OAuth Request Token, for use with convert_to_access_token
+    # [<tt>:request_token_secret</tt>]    OAuth Request Token Secret, for use with convert_to_access_token
+    # [<tt>:access_token</tt>]           OAuth Token, either User-specific or General-purpose
+    # [<tt>:access_token_secret</tt>]    OAuth Token, either User-specific or General-purpose
+    # [<tt>:app_id</tt>]                 Your Mobile Application ID
+    # [<tt>:debug</tt>]                  Boolean
+    #
+    # User-specific OAuth tokens tie Fire Eagle users to your application. As
+    # such, they are intended to be distributed (with keys) to that user's
+    # mobile device and/or computer running your desktop or mobile client. For
+    # web-based applications User-specific tokens will be retrieved by your
+    # web server where they should be treated as private data. Take care to
+    # avoid releasing this data to the public, as the corresponding User's
+    # location information may be inadvertently exposed. User-specific OAuth
+    # tokens should be considered the property of your users.
+    #
+    # General-purpose OAuth tokens are tied to your application and allow you,
+    # as a developer, to make more general (often batch-style) queries against
+    # Fire Eagle. As a result, allowing this token/secret combination loose
+    # has the potential to reveal a much greater amount of personal data. In
+    # an attempt to mitigate this, we will only grant general-purpose tokens
+    # to web applications (contact us with details, if you seek an exception).
+    # In addition, we require developers to provide a restrictive IP range at
+    # registration time in order to further mitigate the risk of
+    # general-purpose tokens being used inappropriately.
+    #
+    # In general, OAuth tokens should be considered sacrosanct in order to
+    # help us respect our users' privacy. Please take this responsibility on
+    # as your own. If your Application Oauth tokens are compromised, Fire
+    # Eagle will turn off your application service until the problem is
+    # resolved.
+    #
+    # If the Client is initialized without an OAuth access token, it's assumed
+    # you're operating a non-web based application.
+    #
+    # == Example web-based authentication flow:
+    #
+    # Initialize a client with your consumer key and consumer secret.
+    #
+    #   >> c = FireEagle::Client.new(:consumer_key => "key", :consumer_secret => "sekret")
+    #   => #<FireEagle::Client:0x1ce2e70 ... >
+    #
+    # Generate a request token with a +callback_url+:
+    #
+    #   >> c.get_request_token("http://example.com/cb")
+    #   => #<OAuth::Token:0x1cdb5bc @token="request_token", @secret="sekret">
+    #
+    # Prompt your user to visit your app's authorization url:
+    #
+    #   >> c.authorization_url
+    #   => "http://fireeagle.yahoo.net/oauth/authorize?oauth_token=request_token"
+    #
+    # When the user has completed this step, s/he will be redirected back to
+    # the callback url you configured when obtaining a request token.
+    # +oauth_verifier+ will be present in the callback.
+    #
+    #   >> c.convert_to_access_token(oauth_verifier)
+    #   => #<OAuth::Token:0x1cd3bf0 @token="access_token", @secret="access_token_secret">
+    #
+    # == Non web-based applications
+    #
+    # For non web-based applications, such as a mobile client application, the
+    # authentication between the user and the application is slightly
+    # different. The request token is displayed to the user by the client
+    # application. The user then logs into the FireEagle website (using
+    # mobile_authorization_url) and enters this code to authorize the
+    # application. When the user finishes the authorization step the client
+    # application exchanges the request token for an access token (using
+    # +convert_to_access_token+). This is a lightweight method for non-web
+    # application users to authenticate an application without entering any
+    # identifying information into a potentially insecure application. Request
+    # tokens are valid for only 1 hour after being issued.
+    #
+    # == Example mobile-based authentication flow:
+    #
+    # Initialize a client with your consumer key, consumer secret, and your mobile application id:
+    #
+    #   >> c = FireEagle::Client.new(:consumer_key => "key", :consumer_secret => "sekret", :app_id => 12345)
+    #   => #<FireEagle::Client:0x1ce2e70 ... >
+    #
+    # Generate a request token:
+    #
+    #   >> c.get_request_token
+    #   => #<OAuth::Token:0x1cdb5bc @token="ENTER_THIS_TOKEN", @secret="sekret">
+    #
+    # Prompt your user to visit your app's mobile authorization url and enter ENTER_THIS_TOKEN:
+    #
+    #   >> c.mobile_authorization_url
+    #   => "http://fireeagle.yahoo.net/oauth/mobile_auth/12345"
+    #
+    # Once the user has indicated to you that they've done this (and provided
+    # a verification code), convert their request token to an access token:
+    #
+    #   >> c.convert_to_access_token(oauth_verifier)
+    #   => #<OAuth::Token:0x1cd3bf0 @token="access_token", @secret="access_token_secret">
+    #
+    # You're done!
+    def initialize(options = {})
+      options = {
+        :debug  => false,
+        :format => FireEagle::FORMAT_XML
+      }.merge(options)
+
+      # symbolize keys
+      options.map do |k,v|
+        options[k.to_sym] = v
+      end
+      raise FireEagle::ArgumentError, "OAuth Consumer Key and Secret required" if options[:consumer_key].nil? || options[:consumer_secret].nil?
+      @consumer = OAuth::Consumer.new(options[:consumer_key], options[:consumer_secret], :site => FireEagle::API_SERVER, :authorize_url => FireEagle::AUTHORIZATION_URL)
+      @debug    = options[:debug]
+      @format   = options[:format]
+      @app_id   = options[:app_id]
+      if options[:access_token] && options[:access_token_secret]
+        @access_token = OAuth::AccessToken.new(@consumer, options[:access_token], options[:access_token_secret])
+      else
+        @access_token = nil
+      end
+      if options[:request_token] && options[:request_token_secret]
+        @request_token = OAuth::RequestToken.new(@consumer, options[:request_token], options[:request_token_secret])
+      else
+        @request_token = nil
+      end
+    end
+
+    # Obtain a <strong>new</strong> unauthorized OAuth Request token
+    def get_request_token(callback_url = "", force_token_regeneration = false)
+      if force_token_regeneration || @request_token.nil?
+        @request_token = consumer.get_request_token(:oauth_callback => callback_url)
+      end
+      @request_token
+    end
+
+    # Return the Fire Eagle authorization URL for your mobile application. At this URL, the User will be prompted for their request_token.
+    def mobile_authorization_url
+      raise FireEagle::ArgumentError, ":app_id required" if @app_id.nil?
+      "#{FireEagle::MOBILE_AUTH_URL}#{@app_id}"
+    end
+
+    # The URL the user must access to authorize this token. get_request_token must be called first. For use by web-based and desktop-based applications.
+    def authorization_url
+      raise FireEagle::ArgumentError, "call #get_request_token first" if @request_token.nil?
+      request_token.authorize_url
+    end
+
+    # Exchange an authorized OAuth Request token for an access token. For use by desktop-based and mobile applications.
+    def convert_to_access_token(oauth_verifier)
+      raise FireEagle::ArgumentError, "call #get_request_token and have the user authorize the token first" if @request_token.nil?
+      @access_token = request_token.get_access_token(:oauth_verifier => oauth_verifier)
+    end
+
+    # Disambiguates potential values for update query. Results from lookup can be passed to
+    # update to ensure that FireEagle will understand how to parse the Location Hash.
+    #
+    # All three Location methods (lookup, update, and within) accept a Location Hash.
+    #
+    # There is a specific order for looking up locations. For example, if you provide lat, lon, and address,
+    # FireEagle will use the the latitude and longitude geo-coordinates and ignore the address.
+    #
+    # Location Hash keys, in order of priority:
+    #
+    # [<tt>(:lat, :lon)</tt>]                   both required, valid values are floats of -180 to 180 for lat and -90 to 90 for lon
+    # [<tt>(:woeid)</tt>]                       Where on Earth ID
+    # [<tt>:place_id</tt>]                      Place ID (via Flickr/Upcomoing); deprecated in favor of WOE IDs when possible
+    # [<tt>:address</tt>]                       street address (may contain a full address, but will be combined with postal, city, state, and country when available)
+    # [<tt>(:mnc, :mcc, :lac, :cellid)</tt>]    cell tower information, all required (as integers) for a valid tower location
+    # [<tt>:postal</tt>]                        a ZIP or postal code (combined with address, city, state, and country when available)
+    # [<tt>:city</tt>]                          city (combined with address, postal, state, and country when available)
+    # [<tt>:state</tt>]                         state (combined with address, postal, city, and country when available)
+    # [<tt>:country</tt>]                       country (combined with address, postal, city, and state when available)
+    # [<tt>:q</tt>]                             Free-text fallback containing user input. Lat/lon pairs and geometries will be extracted if possible, otherwise this string will be geocoded as-is.
+    #
+    # Not yet supported:
+    #
+    # * <tt>upcoming_venue_id</tt>
+    # * <tt>yahoo_local_id</tt>
+    # * <tt>plazes_id</tt>
+    def lookup(params)
+      raise FireEagle::ArgumentError, "OAuth Access Token Required" unless @access_token
+      response = get(FireEagle::LOOKUP_API_PATH + ".#{format}", :params => params)
+      FireEagle::Response.new(response.body).locations
+    end
+
+    # Sets a User's current Location using using a Place ID hash or a set of Location parameters. If the User
+    # provides a Location unconfirmed with lookup then FireEagle makes a best guess as to the User's Location.
+    #
+    # All three Location methods (lookup, update, and within) accept a Location Hash.
+    #
+    # There is a specific order for looking up locations. For example, if you provide lat, lon, and address,
+    # FireEagle will use the the latitude and longitude geo-coordinates and ignore the address.
+    #
+    # Location Hash keys, in order of priority:
+    #
+    # [<tt>(:lat, :lon)</tt>]                   both required, valid values are floats of -180 to 180 for lat and -90 to 90 for lon
+    # [<tt>:place_id</tt>]                      Place ID - valid values decrypts to an integer value
+    # [<tt>:address</tt>]                       street address (may contain a full address, but will be combined with postal, city, state, and country when available)
+    # [<tt>(:mnc, :mcc, :lac, :cellid)</tt>]    cell tower information, all required (as integers) for a valid tower location
+    # [<tt>:postal</tt>]                        a ZIP or postal code (combined with address, city, state, and country when available)
+    # [<tt>:city</tt>]                          city (combined with address, postal, state, and country when available)
+    # [<tt>:state</tt>]                         state (combined with address, postal, city, and country when available)
+    # [<tt>:country</tt>]                       country (combined with address, postal, city, and state when available)
+    # [<tt>:q</tt>]                             Free-text fallback containing user input. Lat/lon pairs and geometries will be extracted if possible, otherwise this string will be geocoded as-is.
+    #
+    # Not yet supported:
+    #
+    # * <tt>upcoming_venue_id</tt>
+    # * <tt>yahoo_local_id</tt>
+    # * <tt>plazes_id</tt>
+    def update(location = {})
+      raise FireEagle::ArgumentError, "OAuth Access Token Required" unless @access_token
+      location = sanitize_location_hash(location)
+      response = post(FireEagle::UPDATE_API_PATH + ".#{format}", :params => location)
+      FireEagle::Response.new(response.body)
+    end
+
+    # Returns the Location of a User.
+    def user
+      raise FireEagle::ArgumentError, "OAuth Access Token Required" unless @access_token
+      response = get(FireEagle::USER_API_PATH + ".#{format}")
+      FireEagle::Response.new(response.body).users.first
+    end
+    alias_method :location, :user
+
+    # Query for Users of an Application who have updated their Location recently. Returns a list of
+    # Users for the Application with recently updated locations.
+    #
+    # == Optional parameters:
+    #
+    # <tt>time</tt>   The time to start looking at recent updates from. Value is flexible, supported forms are 'now', 'yesterday', '12:00', '13:00', '1:00pm' and '2008-03-12 12:34:56'. (default: 'now')
+    # <tt>count</tt>  Number of users to return per page. (default: 10)
+    # <tt>start</tt>  The page number at which to start returning the list of users.
+    def recent(time = 'now', count = 10, start = 1)
+      raise FireEagle::ArgumentError, "OAuth Access Token Required" unless @access_token
+      params = { :count => count, :start => start, :time => time }
+      response = get(FireEagle::RECENT_API_PATH + ".#{format}", :params => params)
+      FireEagle::Response.new(response.body).users
+    end
+
+    # Takes a Place ID or a Location and returns a list of users of your application who are within the bounding box of that Location.
+    #
+    # Location Hash keys, in order of priority:
+    #
+    # [<tt>(:lat, :lon)</tt>]                   both required, valid values are floats of -180 to 180 for lat and -90 to 90 for lon
+    # [<tt>:woeid</tt>]                         Where on Earth ID
+    # [<tt>:place_id</tt>]                      Place ID
+    # [<tt>:address</tt>]                       street address (may contain a full address, but will be combined with postal, city, state, and country when available)
+    # [<tt>(:mnc, :mcc, :lac, :cellid)</tt>]    cell tower information, all required (as integers) for a valid tower location
+    # [<tt>:postal</tt>]                        a ZIP or postal code (combined with address, city, state, and country when available)
+    # [<tt>:city</tt>]                          city (combined with address, postal, state, and country when available)
+    # [<tt>:state</tt>]                         state (combined with address, postal, city, and country when available)
+    # [<tt>:country</tt>]                       country (combined with address, postal, city, and state when available)
+    # [<tt>:q</tt>]                             Free-text fallback containing user input. Lat/lon pairs and geometries will be extracted if possible, otherwise this string will be geocoded as-is.
+    #
+    # Not yet supported:
+    #
+    # * <tt>upcoming_venue_id</tt>
+    # * <tt>yahoo_local_id</tt>
+    # * <tt>plazes_id</tt>
+    def within(location = {}, count = 10, start = 1)
+      raise FireEagle::ArgumentError, "OAuth Access Token Required" unless @access_token
+      location = sanitize_location_hash(location)
+      params = { :count => count, :start => start }.merge(location)
+      response = get(FireEagle::WITHIN_API_PATH + ".#{format}", :params => params)
+      FireEagle::Response.new(response.body).users
+    end
+
+  protected
+
+    def sanitize_location_hash(location)
+      location.map do |k,v|
+        location[k.to_sym] = v
+      end
+
+      location = location.reject { |key, value| !FireEagle::UPDATE_PARAMS.include?(key) }
+      raise FireEagle::ArgumentError, "Requires all or none of :lat, :lon" unless location.has_all_or_none_keys?(:lat, :lon)
+      raise FireEagle::ArgumentError, "Requires all or none of :mnc, :mcc, :lac, :cellid" unless location.has_all_or_none_keys?(:mnc, :mcc, :lac, :cellid)
+      location
+    end
+
+    def get(url, options = {}) #:nodoc:
+      request(:get, url, options)
+    end
+
+    def post(url, options = {}) #:nodoc:
+      request(:post, url, options)
+    end
+
+    def request(method, url, options) #:nodoc:
+      response = case method
+      when :post
+        access_token.request(:post, url, options[:params])
+      when :get
+        qs = options[:params].collect { |k,v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }.join("&") if options[:params]
+        access_token.request(:get, "#{url}?#{qs}")
+      else
+        raise ArgumentError, "method #{method} not supported"
+      end
+
+      case response.code
+      when '500'; then raise FireEagle::FireEagleException, "Internal Server Error"
+      when '400'; then raise FireEagle::FireEagleException, "Method Not Implemented Yet"
+      else response
+      end
+    end
+  end
+end