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!

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:

Get a unique ID for the user and send them to Fire Eagle with that ID

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.

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.

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.

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.

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: