Overview

The Maps JavaScript API lets you customize maps with your own content and
imagery for display on web pages and mobile devices. The Maps JavaScript API
features four basic map types (roadmap, satellite, hybrid, and terrain) which you can
modify using layers and styles, controls and events, and various services and libraries.

Audience

This documentation is designed for people familiar with
JavaScript programming and object-oriented programming concepts. You
should also be familiar with Google
Maps from a user's point of view. There are many
JavaScript
tutorials available on the Web.

This conceptual documentation is designed to let you quickly start
exploring and developing applications with the Maps JavaScript API. We also
publish the Maps JavaScript API Reference.

Hello, World

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

We declare the application as HTML5 using the <!DOCTYPE
html> declaration.

We create a div element named "map" to hold the
map.

We define a JavaScript function that creates a map in the
div.

We load the Maps JavaScript API using a script tag.

These steps are explained below.

Declaring your application as HTML5

We recommend that you declare a true DOCTYPE
within your web application. Within the examples here, we've
declared our applications as HTML5 using the simple HTML5 DOCTYPE
as shown below:

<!DOCTYPE html>

Most current browsers will render content that is declared with this
DOCTYPE in "standards mode" which means that your application
should be more cross-browser compliant. The DOCTYPE is also
designed to degrade gracefully; browsers that don't understand it will ignore
it, and use "quirks mode" to display their content.

Note that some CSS that works within quirks mode is not valid in
standards mode. In specific, all percentage-based sizes must inherit
from parent block elements, and if any of those ancestors fail to
specify a size, they are assumed to be sized at 0 x 0 pixels. For
that reason, we include the following <style>
declaration:

This CSS declaration indicates that the map container
<div>
(with id map) should take up 100% of the height of the HTML
body. Note that we must specifically declare those percentages for
<body> and <html> as well.

Loading the Maps JavaScript API

To load the Maps JavaScript API, use a script tag like the one in the
following example:

The URL contained in the script tag is the location of a
JavaScript file that loads all of the symbols and definitions you need for
using the Maps JavaScript API. This script tag is required.

The async attribute lets the browser render the rest of your
website while the Maps JavaScript API loads. When the API is ready, it will
call the function specified using the callback parameter.

The key parameter contains your application's API key. See
Get API Key for more information.

HTTPS or HTTP

We think security on the web is pretty important, and recommend using HTTPS
whenever possible. As part of our efforts to make the web more secure, we've
made all of the Maps JavaScript API available over HTTPS. Using HTTPS
encryption makes your site more secure, and more resistant to snooping or tampering.

We recommend loading the Maps JavaScript API over HTTPS using the
<script> tag provided above.

If required, you can load the Maps JavaScript API over HTTP by
requesting http://maps.googleapis.com/.

Libraries

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

Synchronously loading the API

In the script tag that loads the Maps JavaScript API,
it is possible to omit the async attribute and the callback
parameter. This will cause the loading of the API to block until the API is
downloaded.

This will probably slow your page load. But it means you can write
subsequent script tags assuming that the API is already loaded.

Map DOM Elements

<div id="map"></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 used CSS to set the height of the map div to
"100%". This will expand to fit the size on mobile devices. You may need to
adjust the width and height values based on the browser's screensize and
padding. Note that divs usually take their width from their containing
element, and empty divs usually have 0 height. For this reason, you must
always set a height on the <div> explicitly.

Map Options

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 larger zoom levels
zoom in at a higher resolution. Specify zoom level as an integer.

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 JavaScript 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 list shows the
approximate level of detail you can expect to see at each zoom level:

1: World

5: Landmass/continent

10: City

15: Streets

20: Buildings

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

For information on how the Maps JavaScript API loads
tiles based on the current zoom level, see the guide to
map and
tile coordinates.

The Map Object

map = new google.maps.Map(document.getElementById("map"), {...});

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. The function Map() is
known as a constructor and its definition is shown below:

API Key and Billing Errors

Under certain circumstances, a darkened map, or 'negative' Street View image,
watermarked with the text "for development purposes only", may be displayed.
This behavior typically indicates issues with either an API key or billing.
In order to use Google Maps Platform products, billing must be enabled on your account,
and all requests must include a valid API key. The following flow will help troubleshoot this:

Are you using an API key?

I'm not sure. How can I check if I am using an API key?

An API key is passed as the key parameter in the URL that is used to load the
Maps JavaScript API. Here are a few options to check if you are using an API key:

For web developers:

If you have access to the source code of your application, look for the
<script> tag which is used to load the Maps JavaScript API.
When loading the Maps JavaScript API, substitute YOUR_API_KEY
in the code below with your API key.

Check the network traffic generated by your website in the browser.
In Chrome, this can be viewed using the
DevToolsNetwork tab.
Here you will see the network requests made by your website. Requests made using the
Maps JavaScript API will be under the path maps/api/js.
Here you can confirm if the requests are using the key parameter.
It may be helpful to
filter your network traffic by maps/api/js when viewing the Network tab.

Does your API key have an IP addresses restriction?

API keys with an IP addresses restriction can only be used with web services that are
intended for use from the server side (such as the
Geocoding API
and other Web Service APIs).
Most of these web services have equivalent services within the Maps JavaScript API (for example, see the
Geocoding Service).
To use the Maps JavaScript API client side services, you will need to create a separate API key which
can be secured with an HTTP referrers restriction (see
Restricting an API key).

If your code isn't working:

To help you get your maps code up and running, Brendan Kenny and Mano Marks point out
some common mistakes and how to fix them in this video.

Look for typos. Remember that JavaScript is a case-sensitive
language.

Check the basics - some of the most common problems occur with the
initial map creation. Such as:

Confirm that you've specified the zoom
and center properties in your map
options.

Ensure that you have declared a div element in which the map will
appear on the screen.

Ensure that the div element for the map has a height. By default,
div elements are created with a height of 0, and are therefore
invisible.