Maps API Launch - Prague 2008

Each of the following examples shows only the relevant JavaScript code, not the full HTML file. You can plug the JS code into the skeleton HTML file shown earlier, or you can download the full HTML file for each example by clicking the link after the example.

Create a map

Reducing Browser Memory Leaks

GUnload() will remove most of the circular references that cause memory leaks. You should call GUnload() in the unload event of your page to reduce the potential that your application leaks memory:

Map Movement and Animation

The following example displays a map, waits two seconds, and then pans to a new center point.

The panTo method centers the map at a given point. If the specified point is in the visible part of the map, then the map pans smoothly to the point; if not, the map jumps to the point.

Adding Controls

Event Listeners

To register an event listener, call the GEvent.addListener method. Pass it a map, an event to listen for, and a function to call when the specified event occurs. In the following example code, we display the latitude and longitude of the center of the map after the user drags the map.

Opening an Info Window

To create an info window, call the openInfoWindow method, passing it a location and a DOM element to display. The following example code displays an info window anchored to the center of the map with a simple "Hello, world" message.

Markers

This example uses GMarker to create 3 markers, then addOverlay to display them

Click Handling

To trigger an action when a user clicks the map, register a listener for the "click" event on your GMap2 instance. When the event is triggered, the event handler will receive two arguments: the marker that was clicked (if any), and the GLatLng of the clicked point. If no marker was clicked, the first argument will be null.

In the following example, when the visitor clicks a point on the map without a marker, we create a new marker at that point. When the visitor clicks a marker, we remove it from the map.

Example 8

For more information about events, see the Events Overview. For a complete list of GMap2 events and the arguments they generate, see GMap2.Events.

Display Info Windows Above Markers

In this example, we show a custom info window above each marker by listening to the click event for each marker. We take advantage of JavaScript function closures to customize the info window content for each marker.

Example 9

For more information about events, see the Events Overview. For a complete list of GMap2 events and the arguments they generate, see GMap2.Events.

Tabbed Info Windows

Version 2 of the API introduces openInfoWindowTabs() and the GInfoWindowTab class to support info windows with multiple, named tabs. The example below displays a simple tabbed info window above a single marker.

Example 10

Custom Icons

This example creates a new type of icon, using the Google Ride Finder "mini" markers as an example. We have to specify the foreground image, the shadow image, and the points at which we anchor the icon to the map and anchor the info window to the icon.

Example 11

var map = new GMap2(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(50.1, 14.4), 12);

// Create our "tiny" marker icon
var icon = new GIcon();
icon.image = "http://labs.google.com/ridefinder/images/mm_20_red.png";
icon.shadow = "http://labs.google.com/ridefinder/images/mm_20_shadow.png";
icon.iconSize = new GSize(12, 20);
icon.shadowSize = new GSize(22, 20);
icon.iconAnchor = new GPoint(6, 20);
icon.infoWindowAnchor = new GPoint(5, 1);

// Add 10 markers to the map at random locations
var bounds = map.getBounds();
var southWest = bounds.getSouthWest();
var northEast = bounds.getNorthEast();
var lngSpan = northEast.lng() - southWest.lng();
var latSpan = northEast.lat() - southWest.lat();
for (var i = 0; i < 10; i++) {
  var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
                          southWest.lng() + lngSpan * Math.random());
  map.addOverlay(new GMarker(point, icon));
}

Geocoding using JavaScript

The geocoder can be accessed from within the JavaScript using the GClientGeocoder object. The getLatLng method can be used to convert an address into a GLatLng. Because geocoding involves sending a request to Google's servers, it can take some time. To avoid making your script wait, you need to pass in a function to call after the response comes back. In this example, we geocode an address, add a marker at that point, and open an info window displaying the address.

Example 12

Extracting Structured Address Information

If you would like to access structured information about an address, GClientGeocoder also provides a getLocations method that returns a JSON object consisting of the following information.

Here we show the JSON object returned by the geocoder for the address of Google's headquarters.

Example 13

{ 
  name: "1600 Amphitheatre Parkway, Mountain View, CA, USA",
  Status: {
    code: 200, 
    request: "geocode"
  }, 
  Placemark: [
    {
      address: "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      AddressDetails: {
        Country: {
          CountryNameCode: "US",
          AdministrativeArea: {
            AdministrativeAreaName: "CA",
            SubAdministrativeArea: {
              SubAdministrativeAreaName: "Santa Clara",
              Locality: {
                LocalityName: "Mountain View",
                Thoroughfare: {
                  ThoroughfareName: "1600 Amphitheatre Pkwy"
                },
                PostalCode: {
                  PostalCodeNumber: "94043"
                }
              }
            }
          }
        }
      },
      Point: {
        coordinates: [-122.083739, 37.423021, 0]
      }
    }
  ]
}

In this example, we use the getLocations method to geocode addresses, and extract the nicely formatted version of the address and the two-letter country from the JSON and display it in the info window.

Example 14

var map;
var geocoder;

map = new GMap2(document.getElementById("map"));
map.setCenter(new GLatLng(34, 0), 1);
geocoder = new GClientGeocoder();


function addAddressToMap(response) {
  map.clearOverlays();
  if (!response || response.Status.code != 200) {
    alert("\"" + input.value + "\" not found");
  } else {
    place = response.Placemark[0];
    point = new GLatLng(place.Point.coordinates[1],
                        place.Point.coordinates[0]);
    marker = new GMarker(point);
    map.addOverlay(marker);
    marker.openInfoWindowHtml(place.address + '<br>' + 
    '<b>Country code:</b> ' + place.AddressDetails.Country.CountryNameCode);
    map.panTo(point);
  }
}

var input = document.getElementById('in16');

// showLocation() is called when you click on the Search button
// in the form.  It geocodes the address entered into the form
// and adds a marker to the map at that location.
function showLocation() {
  var address = input.value;
  geocoder.getLocations(address, addAddressToMap);
}

// findLocation() is used to enter the sample addresses into the form.
function findLocation(address) {
  input.value = address;
  showLocation();
}

Caching Geocodes

GClientGeocoder is equipped with a client-side cache by default. The cache stores geocoder responses, so that if the same address is geocoded again, the response will be returned from the cache rather than from Google's geocoder. To turn off caching, pass null to the setCache method of GClientGeocoder. However, we recommend that you leave caching on because it improves performance. To change the cache being used by GClientGeocoder, use the setCache method and pass in the new cache. To empty the contents of the current cache, use the reset method on the geocoder or on the cache directly.

Developers are encouraged to build their own client-side caches. In this example, we construct a cache that contains pre-computed geocoder responses to six capital cities in countries covered by geocoding API. First, we build an array of geocode responses. Next, we create a custom cache that extends a standard GeocodeCache. Once the cache is defined, we call the setCache method. There is no strict checking of objects stored in the cache, so you may store other information (such as population size) in the cache as well.

Example 15

// Builds an array of geocode responses for the 6 capitals
var city = [
  {
    name: "Washington, DC",
    Status: {
      code: 200,
      request: "geocode"
    },
    Placemark: [
      {
        address: "Washington, DC, USA",
        population: "0.563M",
        AddressDetails: {
          Country: {
            CountryNameCode: "US",
            AdministrativeArea: {
              AdministrativeAreaName: "DC",
              Locality: {
                LocalityName: "Washington"
              }
            }
          }
        },
        Point: {
          coordinates: [-77.036667, 38.895000, 0]
        }
      }
    ]
  },
  // ... etc., and so on for other cities
];

  var map;
  var geocoder;

  // CapitalCitiesCache is a custom cache that extends the standard GeocodeCache.
  // We call apply(this) to invoke the parent's class constructor.
  function CapitalCitiesCache() {
    GGeocodeCache.apply(this);
  }

  // Assigns an instance of the parent class as a prototype of the
  // child class, to make sure that all methods defined on the parent
  // class can be directly invoked on the child class.
  CapitalCitiesCache.prototype = new GGeocodeCache();

  // Override the reset method to populate the empty cache with
  // information from our array of geocode responses for capitals.
  CapitalCitiesCache.prototype.reset = function() {
    GGeocodeCache.prototype.reset.call(this);
    for (var i in city) {
      this.put(city[i].name, city[i]);
    }
  }

  function addAddressToMap(response) {
    map.clearOverlays();

    if (response && response.Status.code != 200) {
      alert("Unable to locate " + decodeURIComponent(response.name));
    } else {
      var place = response.Placemark[0];
      var point = new GLatLng(place.Point.coordinates[1],
                              place.Point.coordinates[0]);
      map.setCenter(point, 6);
      map.openInfoWindowHtml(point, "City: " + place.address
       + "
Population: " + place.population);
    }
  }

  function findCity(which) {
    if (which != 0) {
      geocoder.getLocations(city[which - 1].name, addAddressToMap);
    }
  }

  map = new GMap2(document.getElementById("map"));
  map.setCenter(new GLatLng(50.144, 14.144), 6);

  // Here we set the cache to use the UsCitiesCache custom cache.
  geocoder = new GClientGeocoder();
  geocoder.setCache(new CapitalCitiesCache());

HTTP Request

It is possible to access the Maps API Geocoder using HTTP. However, for any web application involving users making geocoding requests, this is a phenomenally bad idea, because it will use your Geocoding quota, and will burn quickly. Please use the GClientGeocoder for all client-side geocoding.

To access the Maps API geocoder directly using server-side scripting, send a request to http://maps.google.com/maps/geo? with the following parameters in the URI:

In this example, we request the geographic coordinates of Google's headquarters.

If you specify json as the output, the response is formatted as a JSON object, as shown in the example above. If you specify xml or kml, the response is returned in XML or KML. The XML and KML outputs are identical except for the MIME types.

For example, this is the response that the geocoder returns for "1600 amphitheatre mtn view ca".

Example 16

<kml>
  <Response>
    <name>1600 amphitheatre mtn view ca</name>
    <Status>
      <code>200</code>

      <request>geocode</request>
    </Status>
    <Placemark>
      <address> 
        1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA
      </address>

      <AddressDetails>
        <Country>
          <CountryNameCode>US</CountryNameCode>
 	  <AdministrativeArea>
            <AdministrativeAreaName>CA</AdministrativeAreaName>

           <SubAdministrativeArea>
             <SubAdministrativeAreaName>Santa Clara</SubAdministrativeAreaName>
             <Locality>
               <LocalityName>Mountain View</LocalityName>

    	       <Thoroughfare>

                 <ThoroughfareName>1600 Amphitheatre Pkwy</ThoroughfareName>
               </Thoroughfare>
               <PostalCode>
                 <PostalCodeNumber>94043</PostalCodeNumber>

               </PostalCode>

             </Locality>
           </SubAdministrativeArea>
         </AdministrativeArea>
       </Country>

     </AddressDetails>

     <Point>

       <coordinates>-122.083739,37.423021,0</coordinates>
     </Point>
   </Placemark>

  </Response>

</kml>

Driving Directions

If you have a car or motorbike, driving is awesome. If you do not, then it's not so much fun. If you would like your application to display driving directions, then here's how to do it.

Example 17

KML

KML stands for Keyhole Markup Language. You can learn much more about it at http://earth.google.com/kml/.
As a very quick overview, it's an industry standard XML variation, used to describe geographic locations. It's also the common language spoken by the Google Maps API, Google Earth and Google Maps for Mobile.

Example 18

Using KML in Google Maps

Google Maps can import external files in a number of ways. The easiest is to import GeoRSS or KML natively, using GGeoXML

Street View

Street View is pretty new (it's still only available in the development version of Google Maps at time of writing).

However, it's also pretty cool. Here's a very quick overview.

Image Cutter

Image Cutter allows you to very easily make custom google maps from any image.
You can download it from the UCL Centre of Spatial Analysis site.

Troubleshooting

If your code doesn't seem to be working, here are some approaches that might help you solve your problems:

Other resources

Here are some additional resources. Note that these sites are not owned or supported by Google.

Agenda

Examples