My favorites | English | Sign in

Google Maps JavaScript API V3 (Labs)

Map V3 Tutorial

  1. Introduction
  2. The "Hello, World" of Google Maps
    1. Loading the Google Maps API v3
    2. Map DOM Elements
    3. Map Options
    4. google.maps.Map - the Elementary Object
    5. Loading the Map
  3. Latitudes and Longitudes

Introduction

The fundamental element in any Google Maps V3 API application is the "map" itself. This document discusses usage of the fundamental google.maps.Map object and the basics of map operations. (If you've followed the Version 2 tutorial, much will look the same. However, there are some differences, so please read this document.)

The "Hello, World" of Google Maps v3

The easiest way to start learning about the Google Maps API is to see a simple example. The following web page displays a map centered on Sydney, New South Wales, Australia:

<html>
<head>
<meta name="viewport" content="initial-scale=1.0, user-scalable=no" />
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=set_to_true_or_false"></script>
<script type="text/javascript">
  function initialize() {
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var myOptions = {
      zoom: 8,
      center: latlng,
      mapTypeId: google.maps.MapTypeId.ROADMAP
    };
    var map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);
  }

</script>
</head>
<body onload="initialize()">
  <div id="map_canvas" style="width:100%; height:100%"></div>
</body>
</html>

Even in this simple example, there are a few things to note:

  1. We include the Maps API JavaScript using a script tag.
  2. We create a div element named "map_canvas" to hold the Map.
  3. We create a JavaScript object literal to hold a number of map properties.
  4. We write a JavaScript function to create a "map" object.
  5. We initialize the map object from the body tag's onload event.

These steps are explained below.

Loading the Google Maps API

<html>
<head>
<meta name="viewport" content="initial-scale=1.0, user-scalable=no" />
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=set_to_true_or_false"></script>

The http://maps.google.com/maps/api/js URL points to the location of a JavaScript file that loads all of the symbols and definitions you need for using v3 of the Google Maps API. Your page must contain a script tag pointing to this URL.

The <meta> tag within this header specifies that this map should be displayed full-screen and should not be resizable by the user. (See Developing for Mobile Devices for more information.)

Note that we also need to set a sensor parameter to indicate whether this application uses a sensor to determine the user's location. We've left this example as a variable set_to_true_or_false to emphasize that you must set this value to either true or false explicitly.

Map DOM Elements

<div id="map_canvas" style="width: 100%; height: 100%"></div>

For the map to display on a web page, we must reserve a spot for it. Commonly, we do this by creating a named div element and obtaining a reference to this element in the browser's document object model (DOM).

In the example above, we define a <div> named "map_canvas" and set its size using style attributes. Note that this size is set to "100%" which will expand to fit the size on mobile devices. You may need to adjust these values based on the browser's screensize and padding. Note that the map will always take its size from that of its containing element, so you must always set a size on that <div> explicitly.

Map Options

var myLatlng = new google.maps.LatLng(-34.397, 150.644);
var myOptions = {
  zoom: 8,
  center: myLatlng,
  mapTypeId: google.maps.MapTypeId.ROADMAP
};

To initialize a Map, we first create a Map options object to contain map initialization variables. This object is not constructed; instead it is created as an object literal. Because we want to center the map on a specific point, we also create a latlng value to hold this location and pass this into the map's options. For more information on specifiying locations see Latitudes and Longitudes below.

We also set the initial zoom level and mapTypeId to google.maps.MapTypeId.ROADMAP. The following types are supported:

  • ROADMAP displays the normal, default 2D tiles of Google Maps.
  • SATELLITE displays photographic tiles.
  • HYBRID displays a mix of photographic tiles and a tile layer for prominent features (roads, city names).
  • TERRAIN displays physical relief tiles for displaying elevation and water features (mountains, rivers, etc.).

Unlike in the Google Maps V2 API, there is no default map type. You must specifically set an initial map type to see appropriate tiles.

google.maps.Map - the Elementary Object

var map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);

The JavaScript class that represents a map is the Map class. Objects of this class define a single map on a page. (You may create more than one instance of this class - each object will define a separate map on the page.) We create a new instance of this class using the JavaScript new operator.

When you create a new map instance, you specify a <div> HTML element in the page as a container for the map. HTML nodes are children of the JavaScript document object, and we obtain a reference to this element via the document.getElementById() method.

This code defines a variable (named map) and assigns that variable to a new Map object, also passing in options defined within the myOptions object literal. These options will be used to initialize the map's properties. The function Map() is known as a constructor and its definition is shown below:

Constructor Description
google.maps.Map( opts?) Creates a new map using the passed optional parameters in the opts parameter.

Loading the Map

  <body onload="initialize()">

While an HTML page renders, the document object model (DOM) is built out, and any external images and scripts are received and incorporated into the document object. To ensure that our map is placed on the page after the page has fully loaded, we only execute the function which constructs the Map object once the <body> element of the HTML page receives an onload event. Doing so avoids unpredictable behavior and gives us more control on how and when the map draws.

The body tag's onload attribute is an example of an event handler. The Google Maps JavaScript API also provides a set of events that you can handle to determine state changes. For more information, see Map Events.

View example (map-simple.html)

Latitudes and Longitudes

We need a way to refer to locations on the map. The google.maps.LatLng object provides such a mechanism within the Google Maps API. You construct a LatLng object, passing its parameters in the order { latitude, longitude }:

  var myLatlng = new google.maps.LatLng(myLatitude, myLongitude)

Note: the process of turning an address into a geographic point is known as geocoding. Geocoding is supported in this release of the Google Maps API. For more information, see Geocoding in the services section.

LatLng objects have many uses within the Google Maps API. The google.maps.Marker object uses a LatLng in its constructor, for example, and places a marker overlay on the map at the given geographic location.

Map Types

There are many types of maps available within the Google Maps API. In addition to the familiar "painted" road map tiles, the Google Maps API also supports other maps types. These map types are set within the map's Map options object using the mapTypeId property.

The following map types are available in the Google Maps API:

  • MapTypeId.ROADMAP displays the default road map view
  • MapTypeId.SATELLITE displays Google Earth satellite images
  • MapTypeId.HYBRID displays a mixture of normal and satellite views
  • MapTypeId.TERRAIN displays a physical map based on terrain information.

You can change a map's map type by calling the map's setMapTypeId() method.