Introduction to the Google Maps API

When Google Maps (http://maps.google.com) first debuted, it was the victim of numerous hackers. People were enthralled with this next-generation Ajax application that did things no one had ever seen done before. Developers from around the world wanted to know how it worked and how they could use it to their advantage. Though not damaging in any way, these early Google Maps hackers opened the eyes of the folks in Mountain View, CA, and soon the Google Maps API was released to the public.

Using the API, numerous people have created useful and interesting "mashups", combining the Google Maps interface with geographic information from other data centers. A few examples are:

As you can see, the possibilities for combining Google Maps with other geographic information are practically endless.

Getting Started

To begin, you need to have a Google account (such as to access Gmail). If you don't have a Google account yet, go to http://www.google.com/accounts/ for information on how to sign up. The next step is to go to http://www.google.com/apis/maps/signup.html to sign up for an API key. To do so, you must provide a URL indicating the location at which the API will be used. This location is a specific directory on your server; so www.mydomain.com/maps1 and www.mydomain.com/maps2 would each require separate keys.

Keep in mind that there are some limitations to using the Google Maps API. First, you're limited to 50,000 page views per day. If you believe your site will be receiving more page views, you'll need to contact Google to discuss it. Also, you are not allowed to obscure any attributions or ads that appear within the map window. The other caveat is that whenever Google releases a new version of the API, you must update your site within a month to use that new version before the old one disappears. As such, it's probably not a good idea to rely on Google Maps for very important uses as of yet; once the API has been more fully developed, it will be a bit safer. In the meantime, though, it's certainly fun to experiment with.


There is only one JavaScript file necessary for you to begin using the Google Maps API. Unlike other APIs, you can't download the files locally. Instead, you'll need to access the file located on the Google Maps server. This file must include the version and your key in this format:

http://maps.google.com/maps?file=api&v={version}&key={your key}

As of the time of my writing, the most current version is 1, so you'd use this URL in your <script/> tag:

http://maps.google.com/maps?file=api&v=1&key={your key}

Next, you need to create an area in which to place the map. To do so, place and style a <div/> tag so that it is located where you'd like the map to appear. There are then two steps that need to be completed: creating a GMap object and centering the map on an initial point. Each of these steps is remarkably easy.

Suppose you have a <div/> with an ID of "divMap", you can create a GMap object like this:

var oMap = new GMap(document.getElementById("divMap"));

This step essentially initializing the map control. At this point, though, nothing is displayed in the map area; you need to give it an initial set of coordinates to center on. To do so, use the centerAndZoom() method, with accepts two arguments: the GPoint object to center on and the zoom level.

A GPoint object contains the latitude and longitude geocodes for a specific location in the world. To create new GPoint object, just pass in the coordinates:

var oPoint = new GPoint(iLat, iLong);

This point can be passed in to centerAndZoom(), along with a zoom level, to set the initial display of the map (you need to specify both a center and a zoom level initially, after that you can modify just one or the other if necessary). The zoom level is an integer between 0 and 17, where 0 is street-level and 17 is world-level.

The center of the United States can be given as latitude -92 and longitude 32 (somewhere around Kansas City, Kansas), and all of the country can be seen at zoom level 14, so the following code will setup the map to view this area:

oMap.centerAndZoom(new GPoint(-92, 32), 14);

This yields a map that looks like this:

Figure 1
Figure 1

Introduction to the Google Maps API


You may have noticed that the previous map had no way for the user to control what was being displayed. The regular Google Maps interface has a number of different ways the user can manipulate the map, and these are available to you as well as controls.

Controls are used to allow the user to zoom or otherwise manipulate the display of the map. There are four built-in controls that can be used:

  • GLargeMapControl - the typical pan/zoom control displayed on http://maps.google.com.
  • GSmallMapControl - a smaller version of the previous control, with only plus/minus and directional controls (but no zoom slider).
  • GSmallZoomControl - the zoom slider control without any directional controls.
  • GMapTypeControl - the Map/Satellite/Hybrid control.

One or more of these controls can be added to the map via the addControl() method. Each of the controls can simply be created without any parameters and passed in like this:

oMap.addControl(new GSmallMapControl());

Though you'll most often do this just after creating a GMap object, you can add controls at any point. Additionally, you remove controls using the removeControl() method if you have a reference to the control:

var oControl = new GSmallMapControl();
oMap.addControl(oControl);//do some other stuff

The first three controls, GLargeMapControl, GSmallMapControl, and GSmallZoomControl should not be used together since they all occupy the same location on the map (upper left corner). The GMapTypeControl can safely be used with any of the others, since it occupies the upper right corner.

If you want your map to have controls right from the onset, you should add them immediately after creating the GMap() object but before you call centerAndZoom(), such as:

var oMap = new GMap(document.getElementById("divMap"));
oMap.addControl(new GSmallMapControl());
oMap.addControl(new GMapTypeControl());
oMap.centerAndZoom(new GPoint(-92, 32), 14);

Adding these controls yields a map that looks like this:

Figure 2
Figure 2


To mark a particular spot on the map, you'll need to create a marker. A marker is just one of the types of overlays that are available in the Google Maps API. Overlays can be simply defined as anything that gets placed on the map at a particular coordinate. To create a new marker, you need to instantiate a GMarker object and pass in a GPoint indicating where to place it. Then, the marker must be added to the map using the addOverlay() method, such as:

oMap.addOverlay(new GMarker(new GPoint(-92, 32)));

This code adds a marker right at the center of the map defined earlier:

Figure 3
Figure 3

Note that all overlays must be added after the initial call to centerAndZoom(). It is during this method call that the data for the map is initially loaded, and it is that data that determines where an overlay is placed. Calling addOverlay() beforehand causes a JavaScript error.

You can also make it so that a marker pops up an information balloon when clicked on by assigning an event handler for the click event and calling the openInfoWindowHtml() method, which allows you to pass in an HTML string to be displayed in the balloon. For example:

var oMarker = new GMarker(new GPoint(-92, 32));
GEvent.addListener(marker, "click", function () {
    oMarker.openInfoWindowHtml("Center of the U.S.");

This code uses the GEvent library's addListener() method to add an event handler for the click event. In the event handler, the openInfoWindowHtml() method is called, passing in a string. When this marker is clicked, the information balloon will appear and display the given string, as in this image:

Figure 4
Figure 4

There are many other types of overlays and different ways to use information balloons, but this is the fastest way to get you started.


There is no built-in way to do geocoding using the Google Maps API, so if you need the latitude and longitude of a particular building or other location, you'll need to look elsewhere. Fortunately, there are a whole series of free geocoders available from which you can get the necessary information. Try out Geocoder.us, which has a very simple interface and fast results.

Further Uses

This article has just scratched the surface of everything that is possible with the Google Maps API. It is recommended that you read over the API documentation yourself. The documentation contains many examples and numerous tips and tricks on how to get the most of the Google Maps API.

Adapted from Professional Ajax written by Nicolas C. Zakas . Copyright 2006 by Wiley Publishing, Inc. All rights reserved. Reproduced here by permission of the publisher.

This article was originally published on May 4th, 2006

About the Author

Nicholas C. Zakas

Nicholas C. Zakas is the lead author of Professional Ajax by (Wrox, 2006, ISBN: 0-471-77778-1) and the author of Professional JavaScript for Web Developers (Wrox, 2005, ISBN: 0-7645-7908-8). He has worked in web development for more than five years. He has helped develop web solutions in use at some of the largest companies in the world. Nicholas is also an active blogger on JavaScript and Ajax topics at http://www.nczonline.net/.

Most Popular Programming Stories

More for Developers

RSS Feeds

Thanks for your registration, follow us on our social networks to keep up-to-date