/ 
Net-FireEagle-1.0
River stage one • 1 direct dependent • 1 total dependent
/ Net::FireEagle

NAME

Net::FireEagle - access Yahoo's new FireEagle location service

SYNOPSIS

# Set up Fire Eagle oauth
my $fe  = Net::FireEagle->new( consumer_key    => $consumer_key, 
                               consumer_secret => $consumer_secret );

# Resume previous Fire Eagle oauth, feed access token and secret
my $fe2 = Net::FireEagle->new( consumer_key        => $consumer_key, 
                               consumer_secret     => $consumer_secret, 
                               access_token        => $access_token, 
                               access_token_secret => $access_token_secret );

# Send this to user to grant authorization for this app
my $auth_url = $fe->get_authorization_url;
# ... and request an access token
# Note: you can save these in DB to restore previous Fire Eagle oauth session
my ($access_token, $access_token_secret) = $fe->request_access_token;

# Get them back
my $access_token = $fe->access_token;
my $access_token_secret = $fe->access_token_secret;

# in the case of a web app, you want to save the request tokens
# (and/or set them)
my $request_token = $fe->request_token;
my $request_token_secret = $fe->request_token_secret;
$fe->request_token( $request_token );
$fe->request_token_secret( $request_token_secret );

# Can't query or update location without authorization
my $loc = $fe->location;                     # returns xml
my $loc = $fe->location( format => 'xml'  ); # returns xml
my $loc = $fe->location( format => 'json' ); # returns json

# returns result on success. dies or returns undef on failure    
my $return = $fe->update_location( "500 Third St., San Francisco, CA" );

# Find a location. Returns either xml or json
my $return = $fe->lookup_location( "Pensacola" );

ABOUT

Fire Eagle is a site that stores information about your location. With your permission, other services and devices can either update that information or access it. By helping applications respond to your location, Fire Eagle is designed to make the world around you more interesting! Use your location to power friend-finders, games, local information services, blog badges and stuff like that...

For more information see http://fireeagle.yahoo.net/

AUTHENTICATION

For more information read this

http://fireeagle.yahoo.net/developer/documentation/getting_started

but, in short you have to first get an API key from the FireEagle site. Then using this consumer key and consumer secret you have to authenticate the relationship between you and your user. See the script fireagle packaged with this module for an example of how to do this.

SIMPLE DAILY USAGE AND EXAMPLE CODE

The script fireeagle shipped with this module gives you really quick access to your FireEagle account - you can use it to simply query and update your location.

It also serves as a pretty good example of how to do desktop app authentication and how to use the API.

METHODS

new <opts>

Create a new FireEagle object. This must have the options

consumer_key
consumer_secret

which you can get at http://fireeagle.yahoo.net/developer/manage

then, when you have your per-user authentication tokens (see above) you can supply

access_token
access_token_secret

authorized

Whether the client has the necessary credentials to be authorized.

Note that the credentials may be wrong and so the request may still fail.

consumer_key [consumer key]

Returns the current consumer key.

Can optionally set the consumer key.

consumer_secret [consumer secret]

Returns the current consumer secret.

Can optionally set the consumer secret.

access_token [access_token]

Returns the current access token.

Can optionally set a new token.

access_token_secret [access_token_secret]

Returns the current access token secret.

Can optionally set a new secret.

request_token [request_token]

Returns the current request token.

Can optionally set a new token.

request_token_secret [request_token_secret]

Returns the current request token secret.

Can optionally set a new secret.

request_access_token

Request the access token and access token secret for this user.

The user must have authorized this app at the url given by get_authorization_url first.

Returns the access token and access token secret but also sets them internally so that after calling this method you can immediately call location or update_location.

get_authorization_url

Get the URL to authorize a user.

location [opt[s]

Get the user's current location.

Options are passed in as a hash and may be one of

format

Either 'xml' or 'json'. Defaults to 'xml'.

update_location <location> <opt[s]>

Takes a free form string with the new location.

Return the result of the update in either xml or json depending on opts.

The location can either be a plain string or a hash reference containing location parameters as described in

http://fireeagle.yahoo.net/developer/documentation/location#locparams

lookup_location <query> <opt[s]>

Disambiguates potential values for update. Results from lookup can be passed to update to ensure that Fire Eagle will understand how to parse the location parameter.

Return the result of the update in either xml or json depending on opts.

The query can either be a plain string or a hash reference containing location parameters as described in

http://fireeagle.yahoo.net/developer/documentation/location#locparams

RANDOMNESS

If Math::Random::MT is installed then any nonces generated will use a Mersenne Twiser instead of Perl's built in randomness function.

BUGS

Non known

DEVELOPERS

The latest code for this module can be found at

http://svn.unixbeard.net/simon/Net-FireEagle

AUTHOR

Original code by Yahoo! Brickhouse.

Additional code from Aaron Straup Cope

Rewritten and packaged by Simon Wistow <swistow@sixapart.com>

COPYRIGHT

Copyright 2008 - Simon Wistow and Yahoo! Brickhouse

Distributed under the same terms as Perl itself.

See perlartistic and perlgpl.

SEE ALSO

Net::OAuth