Class: FireEagle::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/fireeagle/client.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

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!

Raises:



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/fireeagle/client.rb', line 76

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

Instance Attribute Details

#access_token ⇒ Object (readonly)

TODO add access_token=() and request_token=() methods that check whether the tokens are usable



5
6
7
 
# File 'lib/fireeagle/client.rb', line 5

def access_token
  @access_token
end

#consumer ⇒ Object (readonly)

TODO add access_token=() and request_token=() methods that check whether the tokens are usable



5
6
7
 
# File 'lib/fireeagle/client.rb', line 5

def consumer
  @consumer
end

#format ⇒ Object (readonly)

TODO add access_token=() and request_token=() methods that check whether the tokens are usable



5
6
7
 
# File 'lib/fireeagle/client.rb', line 5

def format
  @format
end

#request_token ⇒ Object (readonly)

TODO add access_token=() and request_token=() methods that check whether the tokens are usable



5
6
7
 
# File 'lib/fireeagle/client.rb', line 5

def request_token
  @request_token
end

Instance Method Details

#authorization_url ⇒ Object

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.

Raises:



118
119
120
121
 
# File 'lib/fireeagle/client.rb', line 118

def authorization_url
  raise FireEagle::ArgumentError, "call #get_request_token first" if @request_token.nil?
  request_token.authorize_url
end

#convert_to_access_token ⇒ Object

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

Raises:



124
125
126
127
 
# File 'lib/fireeagle/client.rb', line 124

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

#get_request_token(force_token_regeneration = false) ⇒ Object

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



104
105
106
107
108
109
 
# File 'lib/fireeagle/client.rb', line 104

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

#lookup(params) ⇒ Object

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

Raises:



155
156
157
158
159
 
# File 'lib/fireeagle/client.rb', line 155

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

#mobile_authorization_url ⇒ Object

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

Raises:



112
113
114
115
 
# File 'lib/fireeagle/client.rb', line 112

def mobile_authorization_url
  raise FireEagle::ArgumentError, ":app_id required" if @app_id.nil?
  "#{FireEagle::MOBILE_AUTH_URL}#{@app_id}"
end

#recent(count = 10, start = 0, time = 'now') ⇒ Object

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:

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) 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’)

Raises:



209
210
211
212
213
214
 
# File 'lib/fireeagle/client.rb', line 209

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

#update(location = {}) ⇒ Object

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

Raises:



186
187
188
189
190
191
 
# File 'lib/fireeagle/client.rb', line 186

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

#user ⇒ Object Also known as: location

Returns the Location of a User.

Raises:



194
195
196
197
198
 
# File 'lib/fireeagle/client.rb', line 194

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

#within(location = {}, count = 10, start = 0) ⇒ Object

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

Raises:



236
237
238
239
240
241
242
 
# File 'lib/fireeagle/client.rb', line 236

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