File Under: APIs, Location

Get Started With Fire Eagle

Yahoo Fire Eagle provides an online database which you can update with your latest geographical location. All of your social applications can access this centralized database for your geo-location instead of depending on you to log in to each one and update each one separately.

Why is Fire Eagle cool? Put simply, Fire Eagle takes care of all the geographical details so you don’t have to. On top of that, Yahoo has built an administrative layer, so user’s can hand-pick the people or applications accessing their updates.

There are many applications currently using Fire Eagle, with more to come …including yours. In this tutorial, you’ll learn the basics of setting up a Fire Eagle application and accessing the Fire Eagle API. Fired up and ready fly? Let’s go!

Contents

  1. What you’ll need
  2. Register Your Application With Fire Eagle
  3. Install the PHP API Kit
  4. Authenticate a New User
    1. Send the User to Fire Eagle
    2. What Happens While the User is Gone
    3. Get the User Back From Fire Eagle
  5. Retrieve a User’s Location
  6. Set a User’s Location
  7. Pointing You in the Right Direction

What you’ll need


Register Your Application With Fire Eagle

Before writing any code, you’ll need to register your application with Fire Eagle. Yahoo wants to know some information about your new app. Don’t worry about getting everything perfect; You can always edit it later. Also, you can have more than one Fire Eagle application. Make this first one a test and later on return and create your masterpiece.

On Fire Eagle’s registration page, you’ll be asked whether you will be updating and accessing location information; We will, so select this option. We’ll need the “Auth for web-based services” option selected in the drop-down menu too.

There is one other field that may throw you off: default callback URL. This is the URL for the page used only for receiving messages directly from Yahoo. You’ll need to create this file as part of Fire Eagle’s authorization process.

In fact, now might be a good time to set up a special testing directory (let’s call it fireeagle) on your web server and create the Callback URL. Let’s plan on naming the callback file callback.php. The name doesn’t really matter; it’s completely up to you. After you create the file, your default callback URL should look something like http://yourdomain.com/fireeagle/callback.php.

Once you register your application, Fire Eagle will show you some special keys. Make of note of those. We’ll use them in the next section.


Install the PHP API Kit

Download the PHP API kit from Fire Eagle’s developer site. The two files we really need here are fireeagle.php and OAuth.php. These scripts simplify interacting with Fire Eagle.

Put these two files into a sub-directory (such as lib, meaning library, as Yahoo suggests). We’ll be using them soon.

Hey, Ruby, Perl, Python, JavaScript and .NET fans! Fire Eagle has API kits for other languages too. We’ll be using PHP for the rest of this tutorial, simply because it’s available on most servers.

Let’s light up this Fire Eagle.


Authenticate a New User

Before we can get into any of the location-based stuff, we have to authenticate the user and get permission to access the user’s location.

There are two steps in the authorization process:

  1. Get a unique ID for the user and send them to Fire Eagle with that ID
  2. Allow the user to return from Fire Eagle’s automated process, then check to see if your app was allowed permission to access their geo-location data

Send the User to Fire Eagle

Before we send the user to Fire Eagle for authentication, we need to get an OAuth token. This comes through a Fire Eagle API call.

Put the code below into a file called authorize.php. Be sure to replace the key and your secret code with your own.

<?

require_once "lib/fireeagle.php";



// Your key and secret code can be found in your application settings

$key = "YOUR_KEY_HERE";

$secret = "YOUR_SECRET_CODE_HERE";



// Create new Fire Eagle object using key and secret code

$fe = new FireEagle($key, $secret);



// Request a token from Fire Eagle's API

$response = $fe->getRequestToken();



// Grab the token pieces and add them to session variables (so our app can remember them)

session_start();

$oauth_token = $response["oauth_token"];

$_SESSION['oauth_token'] = $oauth_token;

$_SESSION['oauth_secret'] = $response["oauth_token_secret"];

$_SESSION["signed_in"] = 0;



// Redirect to the Fire Eagle authorization page

header("Location: " . $fe->getAuthorizeURL($oauth_token));

?>

Download authorize.php

Get ready to be a little bit confused, because Fire Eagle uses a lot of nonsense-looking codes. You’ve seen two already: your key and your secret code. The OAuth token introduces two more: the token itself (public) and the token secret (private).

I am using session variables to hold the values of these two new codes. If this were a real application, these would likely be stored in a database table, associated with the current user’s account. I’m pointing this out because of one of the coolest things about Fire Eagle: This whole authentication step happens exactly once, unless the user chooses to revoke your application’s privilege to see their location.

Once we have the token pieces, and we’ve stored them somewhere, we send the user to Fire Eagle. To do this, we call on the Fire Eagle API again, passing it to our public token.

What Happens While the User is Gone

Once we redirect the user to Fire Eagle, we wait for Fire Eagle to return to the callback URL. Of course, we don’t literally wait. The user left our website, so there’s nothing going on over here while the user is at Fire Eagle’s website.

Here’s what they see when Fire Eagle asks them to authorize your application:

Once the user clicks Confirm, Fire Eagle sends them to the callback URL.


Get the User Back From Fire Eagle

Welcome back, little user! If the user ends up at our callback URL, there’s a good chance they’ve authorized us to access their location. That’s super! Now we just need to write the code that goes in callback.php.

<?

require_once "lib/fireeagle.php";



// Your key and secret code can be found in your application settings

$key = "YOUR_KEY_HERE";

$secret = "YOUR_SECRET_CODE_HERE";



session_start();



// Create new FireEagle object...

// but this time we use our key, our secret code, and both of the token pieces

$fe = new FireEagle($key, $secret, $_SESSION["oauth_token"], $_SESSION["oauth_secret"]);



// We request an access token from the Fire Eagle API

$response = $fe->getAccessToken();



// We replace the OAuth token pieces with new ones, now that we've been granted access

$oauth_token = $response["oauth_token"];

$_SESSION["oauth_token"] = $oauth_token;

$_SESSION["oauth_secret"] = $response["oauth_token_secret"];

$_SESSION["signed_in"] = 1;



// Redirect to our application, so we can actually do stuff

header("Location: getloc.php");

?>



Download callback.php.

The code for callback.php is similar to authorize.php.

Let’s check out what’s different:

  • When creating a Fire Eagle object, we pass along the OAuth token pieces in addition to our standard key and secret code.
  • Instead of getting a RequestToken, now we get an AccessToken. This is good news, because it means we can now access the user’s location.
  • Last time we redirected the user to Fire Eagle. Now, we’re redirecting to our own application.

The reason the code is similar is because it’s really two sides of the same coin. It’s sort of like one of those quick oil change places. The guy who you order from isn’t the one who does the work. He calls down to another guy in the garage below. The upstairs guy hollers out an order, then the downstairs guy confirms by repeating the order. It’s sort of like that.

Anyway, we’re just delaying the really fun and useful part of Fire Eagle: accessing the user’s location!


Retrieve a User’s Location

I named my application file getloc.php and made the callback script redirect to it. In this application, I’m going to show a very basic example of retrieving a user’s location.

<?

require_once "lib/fireeagle.php";



// Your key and secret code can be found in your application settings

$key = "YOUR_KEY_HERE";

$secret = "YOUR_SECRET_CODE_HERE";



session_start();



// New FireEagle object with key, secret code, and OAuth token pieces

$fe = new FireEagle($key, $secret, $_SESSION["oauth_token"], $_SESSION["oauth_secret"]);



// Ask Fire Eagle API for the user location data

$loc = $fe->user();



// Debugging: un-comment the next line to see the full result

// print header("Content-type: text/plain");print_r($loc);



// Grab data for most granular level of location

$toploc = $loc->user->best_guess;



// Set place and date as variables, to be used later

$placename = $toploc->name;

$datetime = $toploc->located_at;



// Make the date prettier

$datetime = date("M j, g:i A", strtotime($datetime));



?>



<p>

Your current location: <strong><?=$placename?></strong> (as of <?=$datetime?>)

</p>

Download getloc.php

As with all the other files, we need to create a Fire Eagle object. Then, the heavy lifting is done via the Fire Eagle API with this line: $loc = $fe->user();

A whole bunch of location data comes flooding in to our $loc variable. It’s more information than you’ll need for your application. Fire Eagle doesn’t know what portion would be beneficial to you, so it sends the whole thing.

To get a glimpse of the entire river at once, remove the comment before the line that begins /print header/. Reload the getloc.php page and you’ll see the structure of the data that gets returned.

The next line of code grabs only a tiny portion of the data and places it in the $toploc variable. The part retrieved is its “best guess,” which is the most granular level of data the user was willing to share. For example, if the user didn’t want to tell us their address, and instead just share their postal code, that’s all we’ll have.

Because it could be useful at some point, Fire Eagle also gives us every level of geography the user has made available, all the way out to country. In this example, the best guess is just fine.

From $toploc, we get the name of the place and the date, then output it to the screen. Fairly simplistic, but it’s getting the location. Heck, for good measure, I <a href=”http://us3.php.net/date“>formatted the date</a> to be readable.

Other fun stuff you could do with this best guess location? Plenty, but how about grabbing $toploc->latitude and $toploc->longitude and plotting them on a Yahoo map. Or yeah, perform Yahoo sacrilege and plot the data on a Google map.

Oh, but wait, there’s more. Don’t go away. In the next section, you learn to /set/ the user’s location from your application.


Set a User’s Location

So far, you have used Fire Eagle to authenticate a user and then get their location. Now we’re going to take it up a notch and set the user’s location.

First, we need to create a way to let the user enter their location. The easiest way is to tack something new on to our “get location” page.

At the end of getloc.php, add this HTML form:

<form action="setloc.php" method="POST">

Set new location: <input name="location" type="text" value="<?=$placename?>" />



<input type="submit" value="Set" />

</form>

We’ve added a form on to the bottom of the get location page. This form has one input box and a submit button. Notice this form posts to setloc.php, the name of the new file we’re about to create.

<?

require_once "lib/fireeagle.php";



// Your key and secret code can be found in your application settings

$key = "YOUR_KEY_HERE";

$secret = "YOUR_SECRET_CODE_HERE";



// Get the query from the getloc.php page

$locationtext = $_POST["location"];



// If the page is being accessed with the POST method and the query isn't empty...

if ($_SERVER["REQUEST_METHOD"] == "POST" && $locationtext != "")

{

  session_start();



  // New FireEagle object with key, secret code, and OAuth token pieces

  $fe = new FireEagle($key, $secret, $_SESSION["oauth_token"], $_SESSION["oauth_secret"]);



  // Create an array with one item because Fire Eagle expects this

  $loc = array("q" => $locationtext);



  // Make the call to the Fire Eagle API updating to the user's location

  $response = $fe->update($loc);

}



// No matter what, return to getloc.php--even if we weren't able to set a location

header("Location: getloc.php");

?>



Download setloc.php

There’s a lot of supportive code here, but there’s one line making the call to update the user’s location: $response = $fe->update($loc);

The variable we pass to the update function, $loc, is an array we created to wrap the query the user sent.

There are other ways of setting a location. We could use lat/long points, or a Flickr Place ID. The easiest method to get a place from a user is likely plain text, as we’ve done here. It depends on how you design your application’s interface.

Also, know you should do some checking to see whether there are results for the user’s search before just blindly setting the location. Fire Eagle provides a lookup function, which appears to be another means of getting to the Yahoo Geocoder.

There we have it. A functioning application you can use to display a user’s location, and set a new one. However, as you’ll see in the next section, this example app is just a small taste of Fire Eagle.


Pointing You in the Right Direction

If you’ve reached the end of this tutorial, you know how to perform the most common actions in Fire Eagle. You created an application tied to your Fire Eagle account. You authenticated a user. You retrieved a location and set one, too. What else is there to do?

Well, first of all, you could make this little application of ours a little more robust. It could use some error checking and you could validate a location before setting it (as mentioned in the previous section). Yahoo has an application similar to ours that does all four of our functions in one file.

But what about fun stuff with Fire Eagle? The API is intentionally lean, because Fire Eagle is a platform. In many ways, what can be done with Fire Eagle is limited by what you can build /outside/ of Fire Eagle.

There are a couple of calls from the API that we didn’t cover in this tutorial. Read the Fire Eagle documentation to learn about the general purpose methods for retrieving data about all your users.

While you’re on the Fire Eagle site, get inspired with what others are doing in the application gallery. We’ll leave you with some examples to get your brain going for your Fire Eagle application:

If you make a rockin’ location-based service with Fire Eagle that you want to share, login and add it to this Wiki.