fireeagle 0.0.2 → 0.6.0

data/History.txt

@@ -1,3 +1,7 @@
+== 0.6.0
+
+* Complete rewrite
+
 == 0.0.2
 
 * Fix callback_url

data/License.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2007 Jesse Newland
+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

data/Manifest.txt

@@ -1,19 +1,21 @@
+config/hoe.rb
+config/requirements.rb
 History.txt
 License.txt
 Manifest.txt
 README.txt
 Rakefile
 lib/fireeagle.rb
-lib/fireeagle/application.rb
-lib/fireeagle/apibase.rb
-lib/fireeagle/base.rb
+lib/fireeagle/client.rb
 lib/fireeagle/location.rb
+lib/fireeagle/response.rb
 lib/fireeagle/user.rb
 lib/fireeagle/version.rb
-scripts/txt2html
 setup.rb
-test/test_fireeagle.rb
-test/test_fireeagle_application.rb
-test/test_fireeagle_location.rb
-test/test_fireeagle_user.rb
-test/test_helper.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

@@ -1,4 +1,8 @@
-FireEagle[http://fireeagle.research.yahoo.com/] (FE) is a system providing centralized management of user location information. FE allows 3rd party developers to update and/or access user's location data.
+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
 
@@ -6,15 +10,39 @@ FireEagle[http://fireeagle.research.yahoo.com/] (FE) is a system providing centr
  
 == Usage
 
- require 'fireeagle'
- f = FireEagle::Base.new(:token => "foo", :secret => "bar")
- user = FireEagle::User.new(f,"token")
- l = FireEagle::Location.new(:country => "Belize")
- user.location = l
- user.location
- =>  #<FireEagle::Location:0x15ba0d0 @details={:country=>"Belize"}>
+  >> 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
 
 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) 2007 Jesse Newland
-License::   Distributes under the same terms as Ruby
+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

@@ -1,123 +1,4 @@
-require 'rubygems'
-require 'rake'
-require 'rake/clean'
-require 'rake/testtask'
-require 'rake/packagetask'
-require 'rake/gempackagetask'
-require 'rake/rdoctask'
-require 'rake/contrib/rubyforgepublisher'
-require 'fileutils'
-require 'hoe'
-
-include FileUtils
-require File.join(File.dirname(__FILE__), 'lib', 'fireeagle', 'version')
-
-AUTHOR = 'Jesse Newland'  # can also be an array of Authors
-EMAIL = "jnewland@gmail.com"
-DESCRIPTION = "Fire Eagle is a site that keeps track of your current location and helps you share it with other sites and services safely. There are hundreds of potential applications. This gem exposes the FireEagle API as Ruby Classes"
-GEM_NAME = 'fireeagle' # what ppl will type to install your gem
-
-@config_file = "~/.rubyforge/user-config.yml"
-@config = nil
-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 ||= @config["username"]
-end
-
-RUBYFORGE_PROJECT = 'fireeagle' # The unix name for your project
-HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
-DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
-
-NAME = "fireeagle"
-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}" : "")
-CLEAN.include ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']
-RDOC_OPTS = ['--quiet', '--title', 'fireeagle documentation',
-    "--opname", "index.html",
-    "--line-numbers", 
-    "--main", "README",
-    "--inline-source"]
-
-class Hoe
-  def extra_deps 
-    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
-  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.author = AUTHOR 
-  p.description = DESCRIPTION
-  p.email = EMAIL
-  p.summary = DESCRIPTION
-  p.url = HOMEPATH
-  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
-  p.test_globs = ["test/**/test_*.rb"]
-  p.clean_globs |= CLEAN  #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 = [['hpricot', '>= 0.5.145'] ]     # 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 = ''
-
-desc 'Generate website files'
-task :website_generate do
-  Dir['website/**/*.txt'].each do |txt|
-    sh %{ ruby scripts/txt2html #{txt} > #{txt.gsub(/txt$/,'html')} }
-  end
-end
-
-desc 'Upload website files to rubyforge'
-task :website_upload do
-  host = "#{rubyforge_username}@rubyforge.org"
-  remote_dir = "/var/www/gforge-projects/#{PATH}/"
-  local_dir = 'website'
-  sh %{rsync -aCv #{local_dir}/ #{host}:#{remote_dir}}
-end
-
-desc 'Generate and upload website files'
-task :website => [:website_generate, :website_upload, :publish_docs]
-
-desc 'Release the website and new gem version'
-task :deploy => [:check_version, :website, :release] do
-  puts "Remember to create SVN tag:"
-  puts "svn copy svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/trunk " +
-    "svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/tags/REL-#{VERS} "
-  puts "Suggested comment:"
-  puts "Tagging release #{CHANGES}"
-end
-
-desc 'Runs tasks website_generate and install_gem as a local deployment of the gem'
-task :local_deploy => [:website_generate, :install_gem]
-
-task :check_version do
-  unless ENV['VERSION']
-    puts 'Must pass a VERSION=x.y.z release version'
-    exit
-  end
-  unless ENV['VERSION'] == VERS
-    puts "Please update your version.rb to match the release version, currently #{VERS}"
-    exit
-  end
-end
-
-
+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'], ['json', '>= 1.1.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,17 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    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

@@ -1,27 +1,41 @@
-%w[ cgi digest/sha1 net/http hpricot time ].each { |f| require f }
+require 'time'
+require 'net/https'
+require 'rubygems'
+gem 'oauth', ">= 0.2.1"
+require 'oauth/client/helper'
+require 'oauth/request_proxy/net_http'
+require 'json'
+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_JSON        = "json"
+  FORMAT_XML         = "xml"
+  UPDATE_PARAMS      = :lat, :lon, :woeid, :place_id, :address, :mnc, :mcc, :lac, :cid, :postal, :city, :state, :country, :q, :label
+                        # not yet supported
+                        #,:geom, :upcoming_venue_id, :yahoo_local_id, :plazes_id
 
-class FireEagle#:nodoc:
-  API_DOMAIN = "fireeagle.research.yahoo.com"
-  API_PATH = "/api/"
-  DEBUG = false
-  
   class Error < RuntimeError #:nodoc:
   end
 
   class ArgumentError < Error #:nodoc:
   end
-  
+
   class FireEagleException < Error #:nodoc:
   end
 end
 
-require 'fireeagle/base'
-require 'fireeagle/apibase'
-require 'fireeagle/application'
-require 'fireeagle/user'
-require 'fireeagle/location'
-require 'fireeagle/version'
-
 #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>hsh</i>.
@@ -33,33 +47,9 @@ class Hash
     end
     false_count == 0 or false_count == size
   end
-  
 end
 
-#FireEagle additions to the <code>Object</code> class
-class Object
-  # A Ruby-ized realization of the K combinator, courtesy of Mikael Brockman.
-  #
-  #   def foo
-  #     returning values = [] do
-  #       values << 'bar'
-  #       values << 'baz'
-  #     end
-  #   end
-  #
-  #   foo # => ['bar', 'baz']
-  #
-  #   def foo
-  #     returning [] do |values|
-  #       values << 'bar'
-  #       values << 'baz'
-  #     end
-  #   end
-  #
-  #   foo # => ['bar', 'baz']
-  #
-  def returning(value)
-   yield(value)
-   value
-  end
-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,343 @@
+class FireEagle
+  class Client
+    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 FireEagle 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 FireEagle. 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, FireEagle 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.
+    #
+    # == 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, convert their request token to an access token:
+    #
+    #   >> c.convert_to_access_token
+    #   => #<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])
+      @debug = options[:debug]
+      @format = options[:format]
+      @app_id = options[:app_id]
+      if options[:access_token] && options[:access_token_secret]
+        @access_token = OAuth::Token.new(options[:access_token], options[:access_token_secret])
+      else
+        @access_token = nil
+      end
+      if options[:request_token] && options[:request_token_secret]
+        @request_token = OAuth::Token.new(options[:request_token], options[:request_token_secret])
+      else
+        @request_token = nil
+      end
+    end
+
+    # Obtain an <strong>new</strong> unauthorized OAuth Request token
+    def get_request_token(force_token_regeneration = false)
+      if force_token_regeneration || @request_token.nil?
+        response = get(FireEagle::REQUEST_TOKEN_PATH, :token => nil)
+        @request_token = create_token(response)
+      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. 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?
+      "#{FireEagle::AUTHORIZATION_URL}?oauth_token=#{@request_token.token}"
+    end
+
+    #Exchange an authorized OAuth Request token for an access token. For use by desktop-based and mobile applications.
+    def convert_to_access_token
+      raise FireEagle::ArgumentError, "call #get_request_token and have user authorize the token first" if @request_token.nil?
+      response = get(FireEagle::ACCESS_TOKEN_PATH, :token => @request_token)
+      @access_token = create_token(response)
+    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, :cid)</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)
+
+      if json?
+        JSON.parse(response.body)
+      else
+        FireEagle::Response.new(response.body).locations
+      end
+    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, :cid)</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)
+
+      if json?
+        JSON.parse(response.body)
+      else
+        FireEagle::Response.new(response.body)
+      end
+    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}")
+
+      if json?
+        JSON.parse(response.body)
+      else
+        FireEagle::Response.new(response.body).users.first
+      end
+    end
+    alias_method :location, :user
+
+    # <b>NOTE: not implemented yet</b>
+    #
+    # Query for Users of an Application who have updated their Location recently. Returns a list of 
+    # Users for the Application with recently updated locations.
+    def recent(count = 10, start = 0)
+      raise FireEagle::ArgumentError, "OAuth Access Token Required" unless @access_token
+
+      params = { :count => count, :start => start }
+
+      response = get(FireEagle::RECENT_API_PATH + ".#{format}", :params => params)
+
+      if json?
+        JSON.parse(response.body)
+      else
+        FireEagle::Response.new(response.body).users
+      end
+    end
+
+    # <b>NOTE: not implemented yet</b>
+    # 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, :cid)</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 = 0)
+      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)
+
+      if json?
+        JSON.parse(response.body)
+      else
+        FireEagle::Response.new(response.body).users
+      end
+    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, :cid)
+      location
+    end
+
+    def xml? #:nodoc:
+      format == FireEagle::FORMAT_XML
+    end
+
+    def json? #:nodoc:
+      format == FireEagle::FORMAT_JSON
+    end
+
+    def create_token(response) #:nodoc:
+      token = Hash[*response.body.split("&").map { |x| x.split("=") }.flatten]
+      OAuth::Token.new(token["oauth_token"], token["oauth_token_secret"])
+    end
+
+    # Is the Client in debug mode?
+    def debug?
+      @debug == true
+    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:
+      options = {
+        :params => {},
+        :token  => @access_token
+      }.merge(options)
+
+      request_uri = URI.parse(FireEagle::API_SERVER + url)
+      http = Net::HTTP.new(request_uri.host, request_uri.port)
+      http.set_debug_output $stderr if debug?
+      if FireEagle::API_SERVER =~ /https:/
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+
+      request = nil
+      if method == :post
+        request = Net::HTTP::Post.new(request_uri.path)
+        request.set_form_data(options[:params])
+      elsif method == :get
+        qs = options[:params].collect { |k,v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }.join("&")
+        request = Net::HTTP::Get.new(request_uri.path + "?" + qs)
+      end
+      request.oauth!(http, consumer, options[:token])
+      response = http.request(request)
+      raise FireEagle::FireEagleException, "Internal Server Error" if response.code == '500'
+      raise FireEagle::FireEagleException, "Method Not Implemented Yet" if response.code == '400'
+      response
+    end
+
+  end
+end