Up until recently, the functional vocabulary of location-based software has been limited to latitude/longitude coordinates and bounding boxes. Still, a gazillion map mashups can’t be wrong—there’s a lot to be done with points mapped onto an interactive projection. However, as location-awareness becomes an increasingly ubiquitous concept in software, it just won’t be enough to understand locations just in terms of coordinate pairs.

Enter Yahoo! GeoPlanet.

GeoPlanet represents a major shift in how software contextualizes locations in the world. What it does is coordinate existing spatial information with a set of ontological relationships. Locations aren’t just lat/long pairs, but also a member in a hierarchical chain made up of its neighborhood, zip code, city, state, and country—each uniquely identified by a Woe ID. GeoPlanet combines the current precision of geographical information with the same kind of relational intuition that humans use to conceptualize where things are.

The whole thing reminds me a bit of Charles and Ray Eames’ classic “Powers of Ten”.

GeoPlanet isn’t just limited to parent-child relationships, either. One of its most compelling features is the ability to query nearby locations through sibling relationships. Take any geographical entity—neighborhood, postal code, state, or whatever—and you can get a list of all other neighboring entities of that same type.

As it turns out, I had the perfect opportunity to sink my teeth into GeoPlanet at Yahoo! Hack U at Carnegie Mellon last week.

Enter the Hack (U)

Aside from a pretty useless SearchMonkey application and a performance art hack, where I used Javascript to improve the economic outlook on Yahoo! Finance, I focused my effort on a hack I like to call eegleye (originally “Eagle Eye”, in honor of Fire Eagle).

eegleye is a geo-based photo scavenger-hunt game. Using GeoPlanet and the Flickr API, it pulls all of the geo-tagged photos for a particular area. Players are tasked with finding the subject’s location in the photo, and taking a picture of it with a geo-enabled camera, such as the iPhone 3G. Once you’ve taken a good shot of the target, you can then go back and upload it to the site to see how you did. If the relative distance between your shot and the original is small enough, then it will assume that it’s a photo of the original subject, and award you points accordingly.

Sounds good enough, so how did it turn out?

In all honestly, I can’t remember the last time I’ve had that much fun developing software. Throughout the whole process, I was thoroughly impressed by how slick everything was. GeoPlanet was dead-simple to use and worked flawlessly. The Flickr API continued to out-do itself—this time by even offering direct integration with Woe IDs. For good measure, I used the Y! Maps API for on-the-fly distance calculation, as well as YUI for AJAX uploading.

After 24+ sleepless hours of coding, eegleye was shown off to my fellow hackers with great reception. It ended up netting me an iPod Touch for 2nd place overall, which was really awesome.

While I’m on the subject, I wanted to give shout-outs to Kent Brewster, Rasmus Lerdorf, and Paul Tarjan who were all really helpful, as well as a special thanks to Jamie Lockwood, who made the whole event possible. Shout-outs also to Paul Shen and Paul O’Shannessy (both pictured above), who were there the whole time hacking away with me in the trenches.

Bonus Round: GeoPlanet Library

In the process of developing eegleye, I managed to scrape together a pretty respectable Ruby wrapper around the GeoPlanet API. If you’re a fan of the Yahoo! Music library I wrote a while back, then you’ll be right at home with this one.

Here’s an example of what this library can do:

require 'yahoo-geoplanet'
            include Yahoo::GeoPlanet
            Yahoo::GeoPlanet.app_id = [Your App ID Here]
            
            cmu = Place.search("Carnegie Mellon University").first
            
            # Everything you get back from the API you have direct access to
            # through the Place object. For example:
            
            puts cmu.type           # "Point of Interest"
            puts cmu.county         # "Allegheny"
            puts cmu.latitude       # 40.444
                                    # Latitude and Longitude are values at Centroid
            puts cmu.bounding_box   # [[40.44445, -79.943314], [40.44355, -79.944511]]
                                    # Bounding box are NW / SE coordinates in array
            
            # We unlock the true power of GeoPlanet with association collections
            # Check out this truly amazing stuff:
            
            # The containing GeoPlanet entity for CMU
            puts cmu.parent # "Squirrel Hill North"
            
            # A list of other points of interest in the area
            cmu.siblings.each{|s| puts s}
            
            # A complete hierarchy, from country down to suburb
            cmu.ancestors.each{|s| puts s}

The project lives on GitHub, and can be installed as a gem with the following: $ gem install yahoo-geoplanet

If you get a chance, feel free to let me know what you think. Hopefully someone will find this to be useful.