Same great maps plus a SLA, support, and control over ads
Welcome to the release of version 3 of the Google Maps API. This JavaScript API will look similar to the existing version 2 of the Google Maps API. However, much has changed under the hood: Version 3 (called V3 within this document) has been designed to load fast, especially on mobile browsers such as Android-based devices and the iPhone™.
The initial launch has a smaller feature set than that available in the V2 API. We will migrate additional features from V2 while working to keep the size of the JavaScript code small and maintain our optimized loading speeds. We welcome your feedback and comments on this version of the Google Maps API within the Google Maps API V3 discussion group.
New! Directions in the V3 Maps API!
Welcome to the release of version 3 of the Google Maps API. This JavaScript API will look similar to the existing version 2 of the Google Maps API. However, much has changed under the hood: Version 3 (called V3 within this document) has been designed to load fast, especially on mobile browsers such as Android-based devices and the iPhone™. The initial launch has a smaller feature set than that available in the V2 API. We will migrate additional features from V2 while working to keep the size of the JavaScript code small and maintain our optimized loading speeds. We welcome your feedback and comments on this version of the Google Maps API within the Google Maps API V3 discussion group.
We've implemented this latest version of the Google Maps API using a modified MVC framework. Any state changes of an MVC object (such as a map) for example, are handled through setters and getters of a particular format. As well, all state of the MVC objects are stored as properties of that object, and all observation of state changes through event handlers is of a particular format as well.
Special emphasis on enabling reliable and fast maps on mobile browsers has been integrated into this API. We encourage you to test out this API on mobile devices and post issues with specific devices to the group noted above.
Note: This version of the Google Maps JavaScript API no longer needs API keys!
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 cool applications with the Google Maps API. We also publish the Google Maps API Reference.
The conceptual documentation is divided up into the following areas:
Feedback on this version of the API and its documentation is welcome. Make sure to post feedback to the Google Maps JavaScript API V3 group.
Use of the Google Maps API requires that you indicate whether your application is using a
sensor (such as a GPS locator) to determine the user's location. This is especially important for
mobile devices. Applications must pass a required sensor parameter to the
<script> tag when including the Maps API javascript code, indicating whether or not
your application is using a sensor device.
Applications that determine the user's location via a sensor must pass sensor=true
when loading the Maps API JavaScript.
# # Example using sensor when loading the Maps JavaScript API # <script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=true">
Note that even if your device does not use a sensing device, you must still pass this parameter, setting
its value to false.
The Google Maps API V3 has been designed to load fast and work well on mobile devices. In particular, we have focused on development for advanced mobile devices such as the iPhone and handsets running the Android operating system. Mobile devices have smaller screen sizes than typical browsers on the desktop. As well, they often have particular behavior specific to those devices (such as "pinch-to-zoom" on the iPhone). If you wish to have your application work well on mobile devices, we recommend the following:
Set the <div> containing your map to have width and height attributes of
100%. Be aware that some older desktop browsers don't display well with these
values, however.
You can detect iPhone and Android devices by inspecting the navigator.userAgent
property within the DOM:
|
function detectBrowser() {
var useragent = navigator.userAgent;
var mapdiv = document.getElementById("map_canvas");
if (useragent.indexOf('iPhone') != -1 || useragent.indexOf('Android') != -1 ) {
mapdiv.style.width = '100%';
mapdiv.style.height = '100%';
} else {
mapdiv.style.width = '600px';
mapdiv.style.height = '800px';
}
}
This allows you to alter layout for particular devices, as we've done here to change the screen real estate for each device.
The iPhone device respects the following <meta> tag:
<meta name="viewport" content="initial-scale=1.0, user-scalable=no" />
This setting specifies that this map should be displayed full-screen and should
not be resizable by the user. Android devices running software version 1.5 (Cupcake)
also support these parameters. Note that the iPhone's Safari browser requires
this <meta> tag be included within the page's <head>
element.
For more information on development for the iPhone, consult Apple's Developer documentation. For more information on development of Android devices, consult the Android documentation.
You may localize your Maps API application both by altering default language settings and by setting the application's region code, which alters how it behaves based on a given country or territory.
The Google Maps API uses the browser's preferred language setting when
displaying textual information such as the names for controls, copyright
notices, driving directions and labels on maps. In most cases, this is
preferable; you usually do not wish to override the user's preferred
language setting. However, if you wish to change the Maps API to ignore
the browser's language setting and force it to display information in a
particular language, you can add an optional language
parameter to the <script> tag when including the Maps
API javascript code, specifying the language to use.
For example, to display a Maps API application in Japanese, add
&language=ja to the <script> tag
as shown below:
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false&language=ja">
Note: loading the API in the manner shown above will use the Japanese language for all users regardless of user preferences. Be sure you wish this behavior before setting this option.
View example (map-language.html)
See also the supported list of languages. Note that we often update supported languages so this list may not be exhaustive.
The Maps API serves map tiles and biases application behavior, by default,
using the country of the host domain from which the API is loaded
(which is the USA for
maps.google.com). If you wish to alter your application
to serve different map tiles or bias the application (such as biasing
geocoding results towards the region), you can override this default
behavior by adding a region parameter to the
<script> tag when including the Maps API javascript
code.
The region parameter accepts
Unicode region subtag identifiers which (generally) have a
one-to-one mapping to country code Top-Level Domains (ccTLDs). Most
Unicode region identifiers are identical to ISO 3166-1 codes, with
some notable exceptions. For example, Great Britain's ccTLD is "uk"
(corresponding to the domain .co.uk) while its region
identifier is "GB."
For example, to use a Maps API application localized to the
United Kingdom, add ®ion=GB to the
<script> tag as shown below:
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false®ion=GB">
The following examples show two maps, one which geocodes "Toledo" based on
the default region (US) to "Toledo, Ohio" and one which biases results based
on a region set to ES (Spain) to "Toledo, Spain."
At this time, there is only one fixed version of the Google Maps JavaScript V3 API; you do not need to pass a version parameter when requesting the API JavaScript. As we add more functionality or fix issues with the API, we expect to deploy a versioning scheme for requesting specific versions of the API. When that occurs, we will update this section with a description for how to request specific versions of the API.
If your code doesn't seem to be working, here are some approaches that might help you solve your problems: