Most people are familiar with Google Maps. You type in an address, and you are given a map that shows you the exact location of your query. Part of the process that goes on behind the scenes is geocoding, which takes a physical address and maps it to a set of longitude and latitude coordinates. This makes it much easier when plotting out maps or pinpointing one location in relation to another. As it turns out, on a recent project, I had to use geocoding to figure out a user’s location to find their governmental districts.

There are many different services out there that provide geocoding but many are extremely limited as more and more applications require geocoding. Most of the services, Google Maps included, either have very restrictive limits on what you can do with the information or have such low usage restrictions that it isn’t feasible to use without costing a fortune. As luck would have it, I came across a great service provided by none other than Yahoo! called Yahoo! PlaceFinder.

Yahoo! PlaceFinder is a REST web service that will turn an address into the latitudinal and longitudinal coordinates in XML, JSON, or serialized PHP objects. It has a few other functions too, like finding the nearest airport, time zone, and even telephone area code. The documentation is well laid out and detailed. You send a GET request to the service, and you’ll get back the information.

Getting Started

Since PlaceFinder is a very low-interactive API, all you need is a Yahoo! Application ID. Register for an API key (even though you don’t really need the key), and once you are at the Project screen, click your Project name. You’ll find the Application ID right under your project’s name. Copy that down, as we’ll need it later.

PlaceFinder is a very simple REST service, so cURL is a quick and easy way to access it. There are no authentication tokens to deal with or logon procedures. Just send a GET request, and read the response. A basic object would look like this:

class PlacefinderAPI {
    protected static $baseUrl = 'http://where.yahooapis.com/geocode';
    static public function fetch(array $location, $parameters = array() {
        $query = http_build_query(array_merge($location, $parameters));
        $ch = curl_init(static::$baseUrl.'?'.$query);
        curl_setopt_array($ch, array(
            CURLOPT_RETURNTRANSFER => true,
        ));
        $res = curl_exec($ch);
        curl_close($ch);
        return $res;
    }
}

We should really beef that up with some error checking, but I’ll leave that to you. Now, I’ve heard there’s a really nice hotel near Chicago O’Hare where a PHP conference happens, and I want to get the time zone and nearest airport so that I know which one to fly into. To save time looking at the documentation, we’ll use the T (time zone), Q (Airport), and P (PHP object) as our flags.

$location = array(
    'location' => '6501 North Mannheim Road, Rosemont IL 60018',
);
$parameters = array(
    'appid' => 'YOUR APP ID',
    'flags' => 'PTQ'
);
$res = PlacefinderAPI::fetch($location, $parameters);
$obj = unserialize($res);
var_dump($obj['ResultSet']['Result'][0]['airport'], $obj['ResultSet']['Result'][0]['timezone']);

// Result:
// string(3) "ORD"
// string(15) "America/Chicago

Contained in that result set is also the latitude, longitude, full address, postal code, county, and country.

That’s all there is to using it. The current Terms of Service, as of this writing, are pretty non-restrictive, and you can use up to 50,000 API calls a day. PlaceFinder can also take coordinates and turn them into a street address via reverse geocoding. If you are in need of a geocoding service, Yahoo! has created a great service.