jnewland-fireeagle 0.7.1.0

data/History.txt

@@ -0,0 +1,33 @@
+== 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/client.rb

@@ -0,0 +1,283 @@
+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 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], :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 an <strong>new</strong> unauthorized OAuth Request token
+    def get_request_token(force_token_regeneration = false)
+      if force_token_regeneration || @request_token.nil?
+        @request_token = consumer.get_request_token
+      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?
+      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
+      raise FireEagle::ArgumentError, "call #get_request_token and have user authorize the token first" if @request_token.nil?
+      @access_token = request_token.get_access_token
+    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>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. Pages are 0-indexed, each page contains the per_page number of users. (default: 0)
+    # <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')
+    def recent(count = 10, start = 0, time = 'now')
+      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 = 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)
+      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

data/lib/fireeagle/location.rb

@@ -0,0 +1,70 @@
+#Describes a location
+class FireEagle
+  class Location
+
+    #Initialize a Location from an XML response
+    def initialize(doc)
+      doc = Hpricot(doc) unless doc.is_a?(Hpricot::Doc || Hpricot::Elem)
+      @doc = doc
+    end
+
+    def label
+      @label ||= @doc.at("/location/label").innerText rescue nil
+    end
+
+    #Level of granularity for this Location
+    def level
+      @level ||= @doc.at("/location/level").innerText.to_i rescue nil
+    end
+
+    #Name of the level of granularity for this Location
+    def level_name
+      @level_name ||= @doc.at("/location/level-name").innerText rescue nil
+    end
+
+    #Human Name for this Location
+    def name
+      @name ||= @doc.at("/location/name").innerText rescue nil
+    end
+    alias_method :to_s, :name
+
+    #Unique identifier for this place. Pro-tip: This is the same place_id used by Flickr.
+    def place_id
+      @place_id ||= @doc.at("/location/place-id").innerText rescue nil
+    end
+    
+    #Numeric unique identifier for this place.
+    def woeid
+      @woeid ||= @doc.at("/location/woeid").innerText rescue nil
+    end
+
+    #The Time at which the User last updated in this Location
+    def located_at
+      @located_at ||= Time.parse(@doc.at("/location/located-at").innerText) rescue nil
+    end
+
+    #The coordinates of the lower corner of a bounding box surrounding this Location
+    def lower_corner
+      @georss ||= @doc.at("/location//georss:box").innerText.split.map{ |l| l.to_f } rescue nil
+      @lower_corner ||= @georss[0..1] rescue nil
+    end
+
+    # The GeoRuby[http://georuby.rubyforge.org/] representation of this location
+    def geom
+      if @doc.at("/location//georss:box")
+        @geo ||= GeoRuby::SimpleFeatures::Geometry.from_georss(@doc.at("/location//georss:box").to_s)
+      elsif @doc.at("/location//georss:point")
+        @geo ||= GeoRuby::SimpleFeatures::Geometry.from_georss(@doc.at("/location//georss:point").to_s)
+      else
+        return nil
+      end
+    end
+    alias_method :geo, :geom
+    
+    #Is this Location FireEagle's best guess?
+    def best_guess?
+      @best_guess ||= @doc.at("/location").attributes["best-guess"] == "true" rescue false
+    end
+
+  end
+end

data/lib/fireeagle/response.rb

@@ -0,0 +1,31 @@
+class FireEagle
+  class Response
+
+    #Parses the XML response from FireEagle
+    def initialize(doc)
+      doc = Hpricot(doc) unless doc.is_a?(Hpricot::Doc || Hpricot::Elem)
+      @doc = doc
+      raise FireEagle::FireEagleException, @doc.at("/rsp/err").attributes["msg"] if !success? 
+    end
+
+    #does the response indicate success?
+    def success?
+      @doc.at("/rsp").attributes["stat"] == "ok" rescue false
+    end
+
+    #An array of of User-specific tokens and their Location at all levels the Client can see and larger.
+    def users
+      @users ||= @doc.search("/rsp//user").map do |user|
+        FireEagle::User.new(user.to_s)
+      end
+    end
+
+    #A Location array.
+    def locations
+      @locations ||= @doc.search("/rsp/locations/location").map do |location|
+        FireEagle::Location.new(location.to_s)
+      end
+    end
+
+  end
+end

data/lib/fireeagle/user.rb

@@ -0,0 +1,33 @@
+class FireEagle
+  class User
+
+    #Parses the XML response from FireEagle.
+    def initialize(doc)
+      doc = Hpricot(doc) unless doc.is_a?(Hpricot::Doc || Hpricot::Elem)
+      @doc = doc
+    end
+
+    #The User-specific token for this Client.
+    def token
+      @token ||= @doc.at("/user").attributes["token"] rescue nil
+    end
+
+    #FireEagle's "best guess" form this User's Location. This best guess is derived as the most accurate
+    #level of the hierarchy with a timestamp in the last half an hour <b>or</b> as the most accurate
+    #level of the hierarchy with the most recent timestamp.
+    def best_guess
+      @best_guess ||= locations.select { |location| location.best_guess? }.first rescue nil
+    end
+
+    #An Array containing all Location granularity that the Client has been allowed to
+    #see for the User. The Location elements returned are arranged in hierarchy order consisting of: 
+    #Country, State, County, Large Cities, Neighbourhoods/Local Area, Postal Code and exact location.
+    #The Application should therefore be prepared to receive a response that may consist of (1) only
+    #country, or (2) country & state or (3) country, state & county and so forth.
+    def locations
+      @locations ||= @doc.search("/user/location-hierarchy/location").map do |location|
+        FireEagle::Location.new(location.to_s)
+      end
+    end
+  end
+end

data/lib/fireeagle/version.rb

@@ -0,0 +1,10 @@
+class FireEagle #:nodoc:
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 7
+    TINY  = 1
+    TEENY = 0
+
+    STRING = [MAJOR, MINOR, TINY, TEENY].join('.')
+  end
+end