Google Maps JavaScript API v3

Google Maps JavaScript API v3
Feedback on this document

Concepts

  1. Google Maps visual refresh
  2. Developing for Mobile Devices
  3. Localization
  4. Versioning
  5. Troubleshooting

Google Maps visual refresh

The Google Maps visual refresh brings a fresh new look to applications using the Google Maps JavaScript API. The refresh is a seamless upgrade that aligns the Google Maps API user experience with the new Google Maps.

Below you can see the two modes side-by-side — the map on the left shows a default Google Map, while the map on the right has visual refresh enabled.

The new look is available as an opt-in upgrade today, and will become the default style in our experimental branch with the next scheduled release in August. Three months later, in our November release, the visual refresh will become the default style in our release branch (used by most Maps for Business customers).

Enabling the visual refresh

For now, the Google Maps JavaScript API will render maps with the classic look and feel by default. If you wish to opt-in to the new visual refresh mode, set the google.maps.visualRefresh global property to true.

Note: You must enable the google.maps.visualRefresh property before the map is rendered.

// Enable the visual refresh
google.maps.visualRefresh = true;

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

google.maps.event.addDomListener(window, 'load', initialize);

Changes in the visual refresh

The new look is primarily visual, and won’t change the functionality of your site. The most obvious change will be new base map tiles that match the new Google Maps. The complete list of changes is:

  • Newly designed base map tiles.
  • Markers, info windows, and map controls have been redesigned.
  • The Scale control now appears on the bottom right, instead of the bottom left.
  • The default fonts used in labels and UI elements has changed. UI elements are styled with CSS by the API, which means that custom CSS that targets DOM elements on the map may require some adjustments if you would like these to apply instead of the new default styling.
  • The marker property raiseOnDrag has been replaced by crossOnDrag.
  • All shadows have been removed in the visual refresh. Any shadows specified programmatically will be ignored.

Note: With Styled Maps you can apply custom coloring to many of your maps features. The stylers hue, lightness, saturation, and gamma apply changes relative to the base map tiles. As the base map tiles have changed in the visual refresh, you may wish to revisit any custom styles in use on your site.

Developing for Mobile Devices

The Google Maps API v3 has been designed to load quickly and work well on mobile devices. In particular, we have focused on development for advanced mobile devices such as Android and iOS handsets. 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"). 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.

  • Android and iOS devices respect the following <meta> tag:

    <meta name="viewport" content="initial-scale=1.0, user-scalable=no" />

    This setting specifies that the map should be displayed full-screen and should not be resizable by the user. 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 for Android devices, consult the Android documentation.

Localization

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.

Language Localization

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="https://maps.googleapis.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)

The Maps Javascript API also supports Bi-directional (Bidi) text containing characters in both Left-to-Right (LTR) and Right-to-Left (RTL) languages natively. Examples of RTL languages include Arabic, Hebrew and Farsi. Generally, you should specify RTL language pages to render properly by adding dir='rtl' to the page's <html> element. The following example renders a map of Cairo, Egypt using Arabic controls:

View example (map-rtl.html)

See also the supported list of languages. Note that we often update supported languages so this list may not be exhaustive.

Region Localization

When you load the Maps API from maps.googleapis.com it applies a default bias for application behavior towards the United States. 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.

As the developer of a Maps API application it is your responsibility to ensure that your application complies with local laws by ensuring that the correct region localization is applied for the country in which the application is hosted.

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 &region=GB to the <script> tag as shown below:

<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?sensor=false&region=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."

Versioning

The Google Maps API team will regularly update this Javascript API with new features, bug fixes, and performance improvements. All API changes will be backwards-compatible, ensuring that if you launch an application using the currently documented interfaces, that application will continue to work without modification as the API is updated. (Note: experimental features, documented in the Experimental API Reference are not covered by this guarantee. Features that are experimental will be clearly labeled in the API documentation.)

Types of Versions

You can indicate which version of the API to load within your application by specifying it using the v parameter of the Maps Javascript API bootstrap request. Three options are supported:

  • The experimental version, specified with v=3.exp.
  • The release version, specified with v=3 or v=3.12.
  • A numbered version, specified with v=3.11.

If you do not explicitly specify a version, you will receive the experimental version by default. Google Maps for Business customers who specify a client ID will receive the release version by default.

The experimental version

The experimental version — currently 3.13 — contains the latest features and bug fixes as they are made publicly available. Changes made to the experimental version are not guaranteed to be feature stable. We encourage you to regularly test your applications with the experimental version, which you can do by adding v=3.13 when loading the Maps API. If you like to live on the edge, you can add v=3.exp to always receive the current experimental version with all of its latest features.

Note: The Maps API for Business SLA does not apply to the Experimental version.

You can specify the experimental version with the below bootstrap:

<script src="https://maps.googleapis.com/maps/api/js?v=3.exp&key;=API_KEY&sensor;=SET_TO_TRUE_OR_FALSE"
type="text/javascript">
</script>

The release version

Each quarter, we will cut a new numbered version (the "release version") and release it for public use. Throughout the quarter we will continue to add bug fixes to this release version, which will be noted within the Maps Javascript API changelog, while ensuring that the feature set remains stable.

The current release version is 3.12, and can be requested by either of the following bootstraps:

<script src="https://maps.googleapis.com/maps/api/js?v=3&key;=API_KEY&sensor;=SET_TO_TRUE_OR_FALSE">
type="text/javascript">
</script>

<script src="https://maps.googleapis.com/maps/api/js?v=3.12&key;=API_KEY&sensor;=SET_TO_TRUE_OR_FALSE">
type="text/javascript">
</script>

Production applications should specify either the release version or the previously released version.

The previously released version

When we release a new numbered version, we will "freeze" the previous release version, meaning that we will no longer update it with any code changes, including bug fixes, ensuring it is completely stable. Each time we introduce a new frozen version in this manner we will retire the oldest released version. Specifying a retired version, such as v=3.0, will always return the oldest available version.

We recommend that you request the current release version when deploying your application. Specifying the version as v=3 will ensure that you always have the most recent release version. Customers who wish to manually test their application against each new release should request the API with the release number (currently v=3.12) and update the value of this parameter with each new release. New versions of the API will be announced on the Google Maps JS API V3 Notify group.

The previously released version is 3.11, and can be requested with the following bootstrap:

<script src="https://maps.googleapis.com/maps/api/js?v=3.11&key;=API_KEY&sensor;=SET_TO_TRUE_OR_FALSE">
type="text/javascript">
</script>

Documentation of Versions

Documentation will always reflect the experimental version. However, for each version, we will offer a separately maintained reference.

Troubleshooting

If your code doesn't seem to be working, here are some approaches that might help you solve your problems:

  • 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, mapTypeId, 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.
    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 Forums 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.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.