When loading the JavaScript Maps API via the http://maps.googleapis.com/maps/api/js URL, you may optionally load additional libraries through use of the libraries parameter. Libraries are modules of code that provide additional functionality to the main JavaScript API but are not loaded unless you specifically request them. For more information, see Libraries in the V3 Maps API.

Asynchronously Loading the API

You may wish to load the Maps API JavaScript code after your page has finished loading, or on demand. To do so, you can inject your own <script> tag in response to a window.onload event or a function call, but you need to additionally instruct the Maps JavaScript API bootstrap to delay execution of your application code until the Maps JavaScript API code is fully loaded. You may do so using the callback parameter, which takes as an argument the function to execute upon completing loading the API.

The following code instructs the application to load the Maps API after the page has fully loaded (using window.onload) and write the Maps JavaScript API into a <script> tag within the page. Additionally, we instruct the API to only execute the initialize() function after the API has fully loaded by passing callback=initialize to the Maps API bootstrap:

function initialize() {
  var mapOptions = {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
    mapTypeId: google.maps.MapTypeId.ROADMAP
  }
  var map = new google.maps.Map(document.getElementById("map-canvas"), mapOptions);
}

function loadScript() {
  var script = document.createElement("script");
  script.type = "text/javascript";
  script.src = "http://maps.googleapis.com/maps/api/js?key=API_KEY&sensor;=TRUE_OR_FALSE&callback;=initialize";
  document.body.appendChild(script);
}

window.onload = loadScript;

View example (map-simple-async.html)

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 mapOptions = {
  center: new google.maps.LatLng(-34.397, 150.644),
  zoom: 8,
  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.

var mapOptions = {};

Latitudes and Longitudes

Because we want to center the map on a specific point, we create a LatLng object to hold this location by passing the location's coordinates in the order { latitude, longitude }:

center = new google.maps.LatLng(-34.397, 150.644)

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 chapter of this guide.

Zoom Levels

The initial resolution at which to display the map is set by the zoom property, where zoom 0 corresponds to a map of the Earth fully zoomed out, and higher zoom levels zoom in at a higher resolution.

zoom: 8

Offering a map of the entire Earth as a single image would either require an immense map, or a small map with very low resolution. As a result, map images within Google Maps and the Maps API are broken up into map "tiles" and "zoom levels." At low zoom levels, a small set of map tiles covers a wide area; at higher zoom levels, the tiles are of higher resolution and cover a smaller area.

The following three images reflect the same location of Tokyo at zoom levels 0,7 and 18.

For information on how the Maps API loads tiles based on the current zoom level, see Tile Coordinates in the Map Types documentation.

Map Types

You must specifically set an initial map type at this time as well.

mapTypeId: google.maps.MapTypeId.ROADMAP

The following map 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.).

For more information about Map Types, see the Map Types section. For most cases, however, using the basic types above is all you need to know.

The Map Object

var map = new google.maps.Map(document.getElementById("map-canvas"),
    mapOptions);

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 mapOptions 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:

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.