Class FireEagle::Client
In: lib/fireeagle/client.rb
Parent: Object

Methods

Attributes

access_token  [R]  TODO add access_token=() and request_token=() methods that check whether the tokens are usable
consumer  [R]  TODO add access_token=() and request_token=() methods that check whether the tokens are usable
format  [R]  TODO add access_token=() and request_token=() methods that check whether the tokens are usable
request_token  [R]  TODO add access_token=() and request_token=() methods that check whether the tokens are usable

Public Class methods

Initialize a FireEagle Client. Takes an options Hash.

Required keys:

:consumer_key
OAuth Consumer key representing your FireEagle Application
:consumer_secret
OAuth Consumer secret representing your FireEagle Application

Optional keys:

:request_token
OAuth Request Token, for use with convert_to_access_token
:request_token_secret
OAuth Request Token Secret, for use with convert_to_access_token
:access_token
OAuth Token, either User-specific or General-purpose
:access_token_secret
OAuth Token, either User-specific or General-purpose
:app_id
Your Mobile Application ID
:debug
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!

Public Instance methods

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.

Exchange an authorized OAuth Request token for an access token. For use by desktop-based and mobile applications.

Obtain an <strong>new</strong> unauthorized OAuth Request token

location()

Alias for user

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:

(:lat, :lon)
both required, valid values are floats of -180 to 180 for lat and -90 to 90 for lon
(:woeid)
Where on Earth ID
:place_id
Place ID (via Flickr/Upcomoing); deprecated in favor of WOE IDs when possible
:address
street address (may contain a full address, but will be combined with postal, city, state, and country when available)
(:mnc, :mcc, :lac, :cellid)
cell tower information, all required (as integers) for a valid tower location
:postal
a ZIP or postal code (combined with address, city, state, and country when available)
:city
city (combined with address, postal, state, and country when available)
:state
state (combined with address, postal, city, and country when available)
:country
country (combined with address, postal, city, and state when available)
:q
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:

  • upcoming_venue_id
  • yahoo_local_id
  • plazes_id

Return the Fire Eagle authorization URL for your mobile application. At this URL, the User will be prompted for their request_token.

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:

time 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’) count Number of users to return per page. (default: 10) start 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)

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:

(:lat, :lon)
both required, valid values are floats of -180 to 180 for lat and -90 to 90 for lon
:place_id
Place ID - valid values decrypts to an integer value
:address
street address (may contain a full address, but will be combined with postal, city, state, and country when available)
(:mnc, :mcc, :lac, :cellid)
cell tower information, all required (as integers) for a valid tower location
:postal
a ZIP or postal code (combined with address, city, state, and country when available)
:city
city (combined with address, postal, state, and country when available)
:state
state (combined with address, postal, city, and country when available)
:country
country (combined with address, postal, city, and state when available)
:q
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:

  • upcoming_venue_id
  • yahoo_local_id
  • plazes_id

Returns the Location of a User.

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:

(:lat, :lon)
both required, valid values are floats of -180 to 180 for lat and -90 to 90 for lon
:woeid
Where on Earth ID
:place_id
Place ID
:address
street address (may contain a full address, but will be combined with postal, city, state, and country when available)
(:mnc, :mcc, :lac, :cellid)
cell tower information, all required (as integers) for a valid tower location
:postal
a ZIP or postal code (combined with address, city, state, and country when available)
:city
city (combined with address, postal, state, and country when available)
:state
state (combined with address, postal, city, and country when available)
:country
country (combined with address, postal, city, and state when available)
:q
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:

  • upcoming_venue_id
  • yahoo_local_id
  • plazes_id

Protected Instance methods

[Validate]