2/8/2014

Getting Started - Google Maps JavaScript API v3 Google Developers

Developers Google Maps API Getting Started

Audience Obtaining an API Key Hello, World Declaring Your Application as HTML5 Loading the Google Maps API Map DOM Elements Map Options The Map Object Loading the Map Troubleshooting

Web

Get Started

Documentation

Reference

Showcase

Support

Blog

GDG

Live

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 Google Maps API. We also publish the Google Maps API Reference.

Obtaining an API Key

All Maps API applications* should load the Maps API using an API key. Using an API key enables you to monitor your application's Maps API usage, and ensures that Google can contact you about your application if necessary. If your application's Maps API usage exceeds the Usage Limits, you must load the Maps API using an API key in order to purchase additional quota. * Google Maps API for Business developers must not include a key in their requests. Please refer to Loading the Google Maps JavaScript API for Business-specific instructions. To create your API key: 1. Visit the APIs Console at https://code.google.com/apis/console and log in with your Google Account. 2. Click the Services link from the left-hand menu. 3. Activate the Google Maps API v3 service. 4. Click the API Access link from the left-hand menu. Your API key is available from the API Access page, in the Simple API Access section. Maps API applications use the Key for browser apps.

By default, a key can be used on any site. We strongly recommend that you restrict the use of your key to domains that you administer, to prevent use on unauthorized sites. You can specify which domains are allowed to use your API key by clicking the Edit allowed referrers... link for your key.

Hello, World
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: < ! D O C T Y P Eh t m l > < h t m l > < h e a d > < m e t an a m e = " v i e w p o r t "c o n t e n t = " i n i t i a l s c a l e = 1 . 0 ,u s e r s c a l a b l e = n o "/ >

https://developers.google.com/maps/documentation/javascript/tutorial

1/5

2/8/2014

Getting Started - Google Maps JavaScript API v3 Google Developers

< s t y l et y p e = " t e x t / c s s " > h t m l{h e i g h t :1 0 0 %} b o d y{h e i g h t :1 0 0 % ;m a r g i n :0 ;p a d d i n g :0} # m a p c a n v a s{h e i g h t :1 0 0 %} < / s t y l e > < s c r i p tt y p e = " t e x t / j a v a s c r i p t "

s r c = " h t t p s : / / m a p s . g o o g l e a p i s . c o m / m a p s / a p i / j s ? k e y = { A P I _ K E Y } & s e n s o r = S E T _ T O _ T R U E _ O R _ F A L S E " > < / s c r i p t > < s c r i p tt y p e = " t e x t / j a v a s c r i p t " > f u n c t i o ni n i t i a l i z e ( ){ v a rm a p O p t i o n s={ c e n t e r :n e wg o o g l e . m a p s . L a t L n g ( 3 4 . 3 9 7 ,1 5 0 . 6 4 4 ) , z o o m :8 } ; v a rm a p=n e wg o o g l e . m a p s . M a p ( d o c u m e n t . g e t E l e m e n t B y I d ( " m a p c a n v a s " ) , m a p O p t i o n s ) ; } g o o g l e . m a p s . e v e n t . a d d D o m L i s t e n e r ( w i n d o w ,' l o a d ' ,i n i t i a l i z e ) ; < / s c r i p t > < / h e a d > < b o d y > < d i vi d = " m a p c a n v a s " / > < / b o d y > < / h t m l > View example (map-simple.html) Even in this simple example, there are a few things to note: 1. We declare the application as HTML5 using the < ! D O C T Y P Eh t m l >declaration. 2. We include the Maps API JavaScript using a s c r i p ttag. 3. We create a d i velement named "map-canvas" to hold the Map. 4. We create a JavaScript object literal to hold a number of map properties. 5. We create a JavaScript "map" object, passing it the d i velement and the map properties. 6. We use an event listener to load the map after the page has loaded. These steps are explained below.

Declaring Your Application as HTML5

We recommend that you declare a true D O C T Y P Ewithin your web application. Within the examples here, we've declared our applications as HTML5 using the simple HTML5 D O C T Y P Eas shown below: < ! D O C T Y P Eh t m l > Most current browsers will render content that is declared with this D O C T Y P Ein "standards mode" which means that your application should be more cross-browser compliant. The D O C T Y P Eis 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 < s t y l e >declaration: < s t y l et y p e = " t e x t / c s s " > h t m l{h e i g h t :1 0 0 %} b o d y{h e i g h t :1 0 0 % ;m a r g i n :0 ;p a d d i n g :0} # m a p c a n v a s{h e i g h t :1 0 0 %} < / s t y l e > This CSS declaration indicates that the map container < d i v >(named m a p c a n v a s ) should take up 100% of the height of the HTML body. Note that we must specifically declare those percentages for < b o d y >and < h t m l >as well.

Loading the Google Maps API

< h t m l > < h e a d > < s c r i p tt y p e = " t e x t / j a v a s c r i p t " s r c = " h t t p s : / / m a p s . g o o g l e a p i s . c o m / m a p s / a p i / j s ? k e y = { A P I _ K E Y } & s e n s o r = S E T _ T O _ T R U E _ O R _ F A L S E " > < / s c r i p t > The URL contained in the s c r i p ttag is the location of a JavaScript file that loads all of the symbols and definitions you need for using the Google Maps API. This s c r i p t tag is required. The k e yparameter contains your application's API key. See Obtaining an API Key for more information. Note that this key is not the same key as used with the v2 API, and must be generated from the APIs console.

https://developers.google.com/maps/documentation/javascript/tutorial

2/5

2/8/2014

Getting Started - Google Maps JavaScript API v3 Google Developers

The s e n s o rparameter of the URL must be included, and indicates whether this application uses a sensor (such as a GPS locator) 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 t r u eor f a l s eexplicitly. Google Maps API for Business users should refer to Loading the Google Maps JavaScript API in the Business documentation for important information about loading the Maps API in their applications.

HTTPS or HTTP
If your application is an HTTPS application, you must load the Google Maps JavaScript API over HTTPS: < s c r i p ts r c = " h t t p s : / / m a p s . g o o g l e a p i s . c o m / m a p s / a p i / j s ? k e y = { A P I _ K E Y } & s e n s o r = S E T _ T O _ T R U E _ O R _ F A L S E " t y p e = " t e x t / j a v a s c r i p t " > < / s c r i p t > Loading the Maps API over HTTPS is necessary in SSL applications to avoid security warnings in most browsers. If the app is an HTTP app, then you may load the Google Maps JavaScript API over HTTPS or HTTP. Note that HTTPS is recommended for applications that include sensitive user data in requests, such as a user's location.

Libraries
When loading the JavaScript Maps API via the URL you may optionally load additional libraries through use of the l i b r a r i e sURL 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 < s c r i p t >tag in response to a w i n d o w . o n l o a devent 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 c a l l b a c kparameter, 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 w i n d o w . o n l o a d ) and write the Maps JavaScript API into a < s c r i p t >tag within the page. Additionally, we instruct the API to only execute the i n i t i a l i z e ( )function after the API has fully loaded by passing c a l l b a c k = i n i t i a l i z eto the Maps API bootstrap: f u n c t i o ni n i t i a l i z e ( ){ v a rm a p O p t i o n s={ z o o m :8 , c e n t e r :n e wg o o g l e . m a p s . L a t L n g ( 3 4 . 3 9 7 ,1 5 0 . 6 4 4 ) } ; v a rm a p=n e wg o o g l e . m a p s . M a p ( d o c u m e n t . g e t E l e m e n t B y I d ( ' m a p c a n v a s ' ) , m a p O p t i o n s ) ; } f u n c t i o nl o a d S c r i p t ( ){ v a rs c r i p t=d o c u m e n t . c r e a t e E l e m e n t ( ' s c r i p t ' ) ; s c r i p t . t y p e=' t e x t / j a v a s c r i p t ' ; s c r i p t . s r c=' h t t p s : / / m a p s . g o o g l e a p i s . c o m / m a p s / a p i / j s ? v = 3 . e x p & s e n s o r = f a l s e & '+ ' c a l l b a c k = i n i t i a l i z e ' ; d o c u m e n t . b o d y . a p p e n d C h i l d ( s c r i p t ) ; } w i n d o w . o n l o a d=l o a d S c r i p t ; View example (map-simple-async.html)

Map DOM Elements

< d i vi d = " m a p c a n v a s "s t y l e = " w i d t h :1 0 0 % ;h e i g h t :1 0 0 % " > < / d i v > For the map to display on a web page, we must reserve a spot for it. Commonly, we do this by creating a named d i velement and obtaining a reference to this element in the browser's document object model (DOM). In the example above, we define a < d i v >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 < d i v >explicitly.

Map Options
v a rm a p O p t i o n s={ c e n t e r :n e wg o o g l e . m a p s . L a t L n g ( 3 4 . 3 9 7 ,1 5 0 . 6 4 4 ) , z o o m :8 } ;

https://developers.google.com/maps/documentation/javascript/tutorial

3/5

2/8/2014

Getting Started - Google Maps JavaScript API v3 Google Developers

To initialize a Map, we first create a M a po p t i o n sobject to contain map initialization variables. This object is not constructed; instead it is created as an object literal. There are two required options for every map: c e n t e rand z o o m . v a rm a p O p t i o n s={ } ;

Latitudes and Longitudes

Because we want to c e n t e rthe map on a specific point, we create a L a t L n gobject to hold this location by passing the location's coordinates in the order { latitude, longitude }: c e n t e r=n e wg o o g l e . m a p s . L a t L n g ( 3 4 . 3 9 7 ,1 5 0 . 6 4 4 ) 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 z o o mproperty, where zoom 0corresponds to a map of the Earth fully zoomed out, and higher zoom levels zoom in at a higher resolution. z o o m :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.

The Map Object

v a rm a p=n e wg o o g l e . m a p s . M a p ( d o c u m e n t . g e t E l e m e n t B y I d ( " m a p c a n v a s " ) , m a p O p t i o n s ) ; The JavaScript class that represents a map is the M a pclass. 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 n e woperator. When you create a new map instance, you specify a < d i v >HTML element in the page as a container for the map. HTML nodes are children of the JavaScript d o c u m e n t object, and we obtain a reference to this element via the d o c u m e n t . g e t E l e m e n t B y I d ( )method. This code defines a variable (named m a p ) and assigns that variable to a new M a pobject, also passing in options defined within the m a p O p t i o n sobject literal. These options will be used to initialize the map's properties. The function M a p ( )is known as a constructor and its definition is shown below: Constructor M a p ( m a p D i v : N o d e , o p t s ? : M a p O p t i o n s) Description Creates a new map inside of the given HTML container which is typically a DIV element using any (optional) parameters that are passed.

Loading the Map

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 d o c u m e n tobject. To ensure that our map is placed on the page after the page has fully loaded, we only execute the function which constructs the M a pobject once the < b o d y >element of the HTML page receives an o n l o a devent. Doing so avoids unpredictable behavior and gives us more control on how and when the map is drawn. The Google Maps JavaScript API provides a set of events that you can handle to determine state changes. For more information, see Map Events. g o o g l e . m a p s . e v e n t . a d d D o m L i s t e n e r ( w i n d o w ,' l o a d ' ,i n i t i a l i z e ) ;

https://developers.google.com/maps/documentation/javascript/tutorial

4/5

2/8/2014

Getting Started - Google Maps JavaScript API v3 Google Developers

Alternatively, you can use the b o d ytag's o n l o a dattribute. < b o d yo n l o a d = " i n i t i a l i z e ( ) " >

Troubleshooting
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.

Google Maps Garage: Where's My Map!

If your code isn't working: 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 z o o mand c e n t e rproperties 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. Refer to our examples for a reference implementation. Use a JavaScript debugger to help identify problems, like the one available in the Chrome Developer Tools. Start by looking in the JavaScript console for errors. Post questions to Stack Overflow. Guidelines on how to post great questions are available on the Support page.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Last updated December 15, 2013.

https://developers.google.com/maps/documentation/javascript/tutorial

5/5