Retrieving Map Location Coordinates

In the last installment, “Integrating Google Maps Into Your Web Applications”, you learned how to take advantage of Google’s amazingly convenient mapping API. In this tutorial, I mentioned the API doesn’t yet offer a means for translating addresses to latitudinal and longitudinal coordinates. Because these coordinates are required to display locations and plot points, information about two third-party solutions capable of doing so was provided: doing so through the geocoder.us website or by creating your own data repository using the Perl module Geo::Coder::US and the freely available U.S. Census Bureau TIGER/Line data. Because the reader response to this most recent article was considerable, I’ve decided to continue the discussion by showing you how to retrieve these coordinates using the geocoder.us Web services and PHP scripting language. In the next installment, I’ll introduce the second solution requiring the Geo::Coder::US module.

Note that in the previous article I mentioned the geocoder.us service comes at a very competitive price if you’re building a commercial applications. However the thoughtful crew behind this service has also opened up their database to developers wishing to create a non-commercial application. Therefore if you’re planning on making any profits whatsoever with an application requiring this service, you’ll need to purchase a commercial license. However, whichever license you use, the concepts covered in this tutorial will apply. The only significant differences are:

• The commercial service requires you authenticate with each request. This is trivial to do and is explained here. You’re free to sign up for an account and authenticate while using the non-commercial service, although it’s not required.
  
• The non-commercial service bandwidth is actively managed, meaning you’ll achieve higher performance using the commercial offering.

Prerequisites

The geocoder.us Web service is quite flexible, offering three different interfaces: REST, SOAP, and XML-RPC. For purposes of this exercise, we’ll be taking advantage of SOAP using PHP’s SOAP extension, available as of version 5.0. If version 5.0 or newer isn’t available to you, consider using NuSOAP, a PHP-driven Web services toolkit written by Dietrich Ayala and maintained by Scott Nichol. You can learn more about NuSOAP from Scott’s great set of tutorials located on his website. While the code won’t be exactly the same, you should be able to translate it rather easily.

Retrieving Address Coordinates

Retrieving address coordinates using the geocoder.us SOAP interface is surprisingly trivial. As an introductory example, let’s retrieve the coordinates for the venerable Ohio State University Stadium, known to the football world as “The Horseshoe”:

<?php

   // Create new instance of the SoapClient class

   // You’ll need to download the WSDL file from:

   // http://geocoder.us/dist/eg/clients/GeoCoder.wsdl

   $client = new SoapClient(“geocoder.wsdl”);

   // Retrieve the address coordinates

   $result = $client->geocode(“411 Woody Hayes Dr, Columbus, OH”);

   // Dump the returned object

   var_dump($result);

?>

Executing this example produces the following output, formatted for eas readability:

array(1) { [0]=>

   object(stdClass)#1 (10) {

      [”number”]=>  int(411)

      [”zip”]=>  int(43210)

      [”suffix”]=>  string(0) “”

      [”prefix”]=>  string(0) “”

      [”type”]=>  string(2) “Dr”

      [”street”]=>  string(11) “Woody Hayes”

      [”state”]=>  string(2) “OH”

      [”city”]=>  string(8) “Columbus”

      [”lat”]=>  float(40.004761)

      [”long”]=>  float(-83.019945)

   }

}

Easy enough! So how do we retrieve each attribute by itself, most notably lat and long? You’ll see that an array of objects are returned, meaning you’ll need to dereference each like so:

$result[0]->attribute

So for example, retrieving the latitude and longitude values occurs like so:

echo “Latitude: “. $result[0]->lat .

     ” Longitude: “. $result[0]->long;

Producing:

Latitude: 40.004761 Longitude: -83.019945

Once we have the coordinates at our disposal, it’s time to incorporate them into the map. This is the subject of the next section.

Plugging the Coordinates into the Google Map API

To pinpoint the location of the stadium, all we need to do is pass the coordinates into the appropriate Google API command. The script for doing so follows:

<?php

   $client = new SoapClient(“geocoder.wsdl”);

   $result = $client->geocode(“411 Woody Hayes Dr, Columbus, OH”);

   $latitude = $result[0]->lat;

   $longitude = $result[0]->long;

?>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Strict//EN”

      “http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd”>

  <html >

  <head>

    <script src=”http://maps.google.com/maps?file=api&v=1

         &key=ADD_YOUR_KEY_HERE” type=”text/javascript”>

    </script>

  </head>

  <body>

    <div id=”map” style=”width: 400px; height: 300px”></div>

    <script type=”text/javascript”>

    //<![CDATA[

    var map = new GMap(document.getElementById(“map”));

    map.centerAndZoom(

    new GPoint(<?php echo $longitude;?>, <?php echo $latitude;?>), 3);

    var point =

    new GPoint(<?php echo $longitude;?>, <?php echo $latitude;?>);

    var marker = new GMarker(point);

    map.addOverlay(marker);

    //]]>

    </script>

  </body>

</html>

This produces the following map:

Note that the mapping data isn’t always perfect! In this case there’s a slight oddity in that despite having the correct stadium address, the coordinates are just a tad off target.

Conclusion

It’s very important to underscore the fact that the geocoder.us non-commercial service is not intended for use with high-traffic websites, and in fact my tests for this article showed it’s tendency to choke when attempting to retrieve even 10 sets of coordinates within a short period of time (less than 90 seconds). If you’re building a low-traffic application, or take the extra steps to cache the coordinates locally (after all, they’re not changing), then this service could fit your needs nicely. If you require a somewhat more robust application or need coordinates for a large number of addresses, then the Geo::Coder::US and the freely available U.S. Census Bureau TIGER/Line data solution would be more suitable. In the next article I’ll show you how this is accomplished.

About the Author

W. Jason Gilmore (http://www.wjgilmore.com/) is the open source editor for Apress. He’s the author of the best-selling “Beginning PHP 5 and MySQL: Novice to Professional” (Apress, 2004. 758pp.). Along with Robert Treat, Jason is the co-author of the forthcoming “Beginning PHP 5 and PostgreSQL 8: From Novice to Professional”, due out at the conclusion of 2005. Jason loves receiving e-mail; so don’t hesitate to write him at wjATwjgilmore.com.