File Under: APIs, Location

Get Started With the Yahoo HTTP Geocoder API

Since the major search engines have opened up their mapping tools to programmers, geocoding has become an essential step in the process of building many a mashup.

Geocoding is the process of converting human-readable place data — a city name, ZIP code, or address — to latitude and longitude points that can be easily plotted on a map.

Yahoo’s HTTP Geocoder API is easy to use, and its output is easy to incorporate into your applications. This article will describe its features and show some examples of how to access the results.


Contents

  1. What You’ll Need
  2. How to Proceed
    1. Step 1: Start a Search
    2. Step 2: View the Results
    3. Step 3: Interpret the Results
  3. Where to Go From Here

What You’ll Need

  • Basic knowledge of XML
  • A Yahoo account
  • A Yahoo Application ID. Yahoo will ask for some information from you, but the good news is you get an ID right away.
  • To incorporate results with an application, you’ll need some programming skills. I’ll be showing code examples in PHP.


How to Proceed

Step 1: Start a Search

Yahoo provides several options to search for a location, such as specifying an address and city separately.

For example, here’s the address for Wired.com, the home of Webmonkey:

520 3rd Street San Francisco, CA

Breaking this into pieces for the geocoder, we get:

street: 520 3rd Street city: San Francisco state: CA

The HTTP geocoder uses a simple URL. All we have to do is pass these pieces to the geocoder with the correct parameter. Here’s the URL we can use for the Webmonkey address (remember to include your Application ID):

http://local.yahooapis.com/MapsService/V1/geocode?appid=appidhere&street=520+3rd+Street&city=San+Francisco&state=CA

Tip: Sometimes we may be geocoding an address that comes from a user. In that case, we don’t always know where the street name ends and the city name begins. The Yahoo API provides a useful option of passing along everything as one parameter and letting the geocoder figure out which part is which. We’ll do that here, using the location parameter:

http://local.yahooapis.com/MapsService/V1/geocode?appid=appidhere&location=520+3rd+Street+San+Francisco+CA



Both of these URLs return the exact same results. That geocoder is smart!


Step 2: View the Results

When we searched for the Webmonkey offices, we received a whole bunch of XML that looks like this:

<ResultSet xsi:schemaLocation="urn:yahoo:maps http://api.local.yahoo.com/MapsService/V1/GeocodeResponse.xsd">

  <Result precision="address">

    <Latitude>37.780995</Latitude>



    <Longitude>-122.395528</Longitude>

     <Address>520 3rd St</Address>

    <City>San Francisco</City>

    <State>CA</State>



    <Zip>94107-1805</Zip>

    <Country>US</Country>

  </Result>

</ResultSet>


In XML, pieces of data are wrapped in tags that look a lot like HTML. The first thing you may notice is that the geocoder separated the pieces of the address for us. Now we have the address, city, and state, with each piece clearly marked.

The geocoder also told us some things we didn’t know. For one, it changed the street name. We sent 520 3rd Street and it returned 520 3rd St. Rewritten street names could help our applications remain consistent. It’s not a big deal, but it’s nice. We also now know the postal code of the address, and in the ZIP+4 format, no less.

Even more useful than that are the latitude and longitude points. It is those long decimal numbers that we can use to plot on a map or calculate the distance from another location.

To use this data, we need to have a way to load it into an application. Time to break out some PHP.


Step 3: Interpret the Results

We’ll be using PHP for these examples. Most web languages will have some method of interpreting XML, which is all that is necessary to use results from Yahoo’s geocoder.

Since we’re using PHP, we’ll be relying on cUrl and SimpleXML. Each of these libraries is usually installed along with PHP 5. cUrl makes HTTP calls to retrieve content from web pages or services, such as the Yahoo HTTP geocoder. SimpleXML takes XML content and converts it to an object, so that individual elements can easily be picked out from XML.

Create a new PHP file in a web directory with this content to test out the geocoder. I’m calling mine test_geocoder.php:

<?

/*** REMEMBER to use your own Application ID ***/

$appid = "appidhere";

$geourl = "http://local.yahooapis.com/MapsService/V1/geocode?appid=$appid&location=520+3rd+Street+San+Francisco+CA";



// Create cUrl object to grab XML content using $geourl

$c = curl_init();

curl_setopt($c, CURLOPT_URL, $geourl);

curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);

$xmlContent = trim(curl_exec($c));

curl_close($c);



// Create SimpleXML object from XML Content

$xmlObject = simplexml_load_string($xmlContent);



// Print out all of the XML Object

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

print_r($xmlObject);

?>



Now go to your browser and load your test_geocoder.php file. The output should look like this:



SimpleXMLElement Object

(

    [Result] => SimpleXMLElement Object

        (

            [@attributes] => Array

                (

                    [precision] => address

                )

            [Latitude] => 37.780995

            [Longitude] => -122.395528

            [Address] => 520 3rd St

            [City] => San Francisco

            [State] => CA

            [Zip] => 94107-1805

            [Country] => US

        )

)



To access individual elements, such as Latitude, provide the path to the element like this:

print ($xmlObject->Result->Latitude);


Where to Go From Here

Geocoding is the basis for mapping. The Yahoo HTTP geocoder gives you the data you need to plot the points on your map so you can focus on the cooler aspects of your applications. Here are some ideas to help you take the next steps:

  • When asking users for their address, you can force them to provide it in a correct format (including the ZIP code) to ensure a good address.
  • Pre-process common locations and store the latitude and longitude in a database for easy, quick access.
  • If you’re sticking with PHP, Yahoo provides a non-XML method to read in the results. If you add &output=php to the end of the URL to get serialized PHP format, which makes it available as a PHP array. If you run the unserialize function on the content, there’s no need to use SimpleXML. You’ll simply be able to call elements like arrays:
$yarray = ["ResultSet"]["Result"]["Latitude"]