Hide
Google Maps JavaScript API v3
Write Feedback

Concepts

  1. Developing for Mobile Devices
  2. Localization
  3. Versioning

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?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?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."

Loading the API in China

The Google Maps APIs are served within China from http://maps.google.cn. When serving content to China, replace https://maps.googleapis.com with http://maps.google.cn. For example:

<script src="http://maps.google.cn/maps/api/js?key=API_KEY"
type="text/javascript">
</script>

If you are specifically targeting users in China, you may wish to add the region and language parameters as well. The API supports both zh-CN and zh-TW as values for the language parameter.

<script src="http://maps.google.cn/maps/api/js?region=cn&language;=zh-CN&key;=API_KEY"
type="text/javascript">
</script>

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.19.
  • A numbered version, specified with v=3.18.

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

The experimental version

The experimental version — currently 3.20 — 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.20 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 Google Maps API for Work 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"
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.19, and can be requested by either of the following bootstraps:

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

<script src="https://maps.googleapis.com/maps/api/js?v=3.19&key;=API_KEY">
</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.19) 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.18, and can be requested with the following bootstrap:

<script src="https://maps.googleapis.com/maps/api/js?v=3.18&key;=API_KEY">
</script>

Documentation of Versions

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

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.