Here's how to get started using the Google Maps API.
People reacted to the new API in one or more ways. My first act was to scratch my own itch by writing a bit of code to display my GPS waypoints on a Google Map. Fortunately, better GPX-to-Google Maps solutions have been created, one of which is documented in "View Your GPS Tracklogs in Google Maps" [Hack #37]. After scratching that itch, I looked to our Geocoder.us site. Schuyler had spent a lot of time figuring out the Census Bureau's public TIGER/Line Map Server API, and how to display the resulting map with a neat little zoomable interface. The results were slow and clunky, but they worked.
The Google Maps API gets rid of the need for that level of head scratching! The march of progress in computers (possibly in society at large) works by first figuring out ways to do new things, and then progressively making those tasks easier, and leaving the old practitioners to eat cat food and write programs for their Osborne luggable computer.
I used Google Maps to bring the geocoder.us site into the protective embrace of the Google Maps API. Geocoder.us, online at http://geocoder.us/, is a free U.S. address geocoder. You can go to the web site and get the latitude and longitude for a U.S. street address. You can also use a web service interface to get the latitude and longitude automatically for a group of addresses [Hack #62]. You can geocode using Google Maps by scraping their search results, but it's not a part of the official API, and doing so violates Google's terms and conditions of service. By contrast, the Geocoder.us site is based on free data without limited terms of service for non-commercial use.
Figure 2-1 shows the results of geocoding the address of O'Reilly Media's headquarters with the original TIGER/Line map, with a pushpin showing the location of the address that we just looked up. We'd like to replace this somewhat slow map generated by the Census Bureau with the much faster, more attractive, and more easily navigable maps offered by Google Maps. (The original Geocoder.us map view can be seen at http://geocoder.us/demo_tiger.cgi.)
Figure 2-1. The Census Bureau map originally used by http://geocoder.us/
2.2.1. Get a Developer Key
The first step in putting a Google Map on your page is to generate a developer's key, which is an alphanumeric string that identifies your web site to Google, and helps them track usage of Google Maps. Having to sign up for a developer's key can be something of an annoyance, but it's a small price to pay for being able to include free (as in beer) maps on your web site with such relative ease.
You'll need a distinct developer's key for each directory on your site that includes Google Maps. You don't need a key for each individual web page or script. So if you have several pages that generate calls to Google Maps from the same directory, you only need one key.
Figure 2-2. Enter a server and path to generate a developer's key
Example 2-1. Google Maps "Hello World"
2.2.2. Hello, World!
The next three interesting lines are:
var map = new GMap(document.getElementById("map")); map.addControl(new GSmallMapControl()); map.centerAndZoom(new GPoint(-122.1419, 37.4419), 4);
By default the size of the map is determined by the size of the HTML element that contains the map. In this example, we are using the div element to define a division in the page, which provides an area that you can control and format independently from other parts of the page.
In our example, the div element is 500 x 400 pixels high and has a 1-pixel-wide gray border around the edge. You can also specify the width and height in percentages, such as style="width: 50%; height: 40%". The border itself is totally optional, but it does set the map off nicely from the rest of the page.
The demo.cgi page at http://geocoder.us/ was already template driven, so to add Google Maps functionality I added the script= line to load the Google Maps library, and then included these lines in my template:
The map will automatically size itself to fit within the <div …> tag. In our templating system (Perl's Template Toolkit, as it happens), [% long %] will be replaced with the contents of the variable long, or the longitude. The only differences from the sample code are that the sample constants for lat and long are replaced with variables that will be set in our program, and that a point marker is added for the location of the address the user looked up.
2.2.3. Getting Outside of Your Head
The "Hello World" example presumes that the HTML script element that imports the Google Maps API library into your web page is nestled safe within the HTML document's head element. Certainly, this is the right place for it to go, but web browsers are perfectly capable of handling script elements elsewhere in an HTML document. Furthermore, situations will occur where you might want to include the API library from elsewheresay, for example, one where you have an HTML templating system that provides a boilerplate header and footer for each page on your site. In this circumstance, you don't want the API library to be imported into every page on the site, because every page outside the directory associated with your developer's key will load up with a developer key error message.
2.2.4. Getting Right to the Point
Once you've got a Google Map on your page, adding points to it is easy. You'll first create a new GPoint object, then create a marker icon at that point, and finally add that marker to the map. We'll look more at adding points and lines to Google Maps in other hacks. For now, enjoy Figure 2-3, which shows a pretty Google Map replacing our TIGER map.
Figure 2-3. http://geocoder.us/ with a Google Map
There are (at least currently) limits on the data available from Google. There is far more aerial and satellite data and map imagery available on the Web [Hack #12] from public Web Mapping Service (WMS) servers than is available from Google.
2.2.5. See Also