Versioning

The Maps JavaScript API team regularly updates the API with new features, bug fixes, and performance improvements. This page describes the versions of the API that are available for use in your applications.

Release channels and version numbers

In your application you can specify release channels or version numbers:

  • The weekly channel is specified with v=weekly.
    This channel is updated once per week, and is the most current.
  • The quarterly channel is specified with v=quarterly.
    This channel is updated once per quarter, and is the most predictable.
  • The beta channel is specified with v=beta.
    This channel is based on the weekly channel, and is updated once per week. It includes additional changes for early testing and feedback.
  • The alpha channel is specified with v=alpha.
    This channel is based on the beta channel, and is updated once per week. It includes experiments for customer feedback on prototypes. It is for development purposes only and should not be used in production.
  • The version number is specified with v=n.nn.
    You can choose v=3.56, v=3.55, v=3.54 or v=3.53.
    Version numbers are updated once per quarter (see Quarterly updates).

If you do not explicitly specify a channel or version, you will receive the weekly channel by default. If you migrated from the premium plan and did not explicitly specify a channel or version, you will receive the quarterly channel by default. If you specify an invalid version, you will receive your default channel.

Choosing the weekly channel

For most applications, we recommend the weekly channel. This is the most current and up-to-date version and contains the latest bug fixes and performance improvements. You can specify the weekly channel by loading the Maps JavaScript API with the following script tag:

<script async
    src="https://maps.googleapis.com/maps/api/js?v=weekly
        &key=YOUR_API_KEY&callback=initMap">
</script>

Currently, the weekly channel is version 3.56. This version is updated weekly with new features, bug fixes, and performance improvements.

In mid-May, the weekly channel will be updated to version 3.57. At that time, the new version may remove deprecated features, and/or introduce backwards-incompatibilities.

Choosing the quarterly channel

Some applications may benefit from fewer but larger updates, because it gives greater predictability. These applications should use the quarterly channel. Use this approach if you want bug fixes and performance improvements to arrive at an expected time (see quarterly updates). You can specify the quarterly channel by loading the Maps JavaScript API with the following script tag:

<script async
    src="https://maps.googleapis.com/maps/api/js?v=quarterly
        &key=YOUR_API_KEY&callback=initMap">
</script>

Currently, the quarterly channel is version 3.55. During the quarter, this version does not receive new features, bug fixes, or performance improvements. We may, from time to time, introduce security bug fixes into this version.

In mid-May, the quarterly channel will be updated to version 3.56. At that time, the new version will include new features, remove deprecated features, and/or introduce backwards incompatibilities from the previous three months.

Choosing the beta channel

Use the beta channel to try out new beta features and changes. Beta features are feature complete but might have some outstanding issues (please use Issue Tracker to report issues and provide feedback). The beta channel is not covered by any SLA or deprecation policy, and some changes might not be backward compatible with earlier releases.

This channel is based on the weekly channel, and is updated once per week.

You can specify the beta channel by loading the Maps JavaScript API with the following script tag:

<script async
    src="https://maps.googleapis.com/maps/api/js?v=beta
        &key=YOUR_API_KEY&callback=initMap">
</script>

Choosing the alpha channel

Use the alpha channel to try out new experimental features and changes. Please use Issue Tracker to report issues and provide feedback. The alpha channel is not covered by any SLA or deprecation policy, and some changes might not be backward compatible with earlier releases. It is for development purposes only and should not be used in production.

This channel is based on the beta channel, and is updated once per week.

You can specify the alpha channel by loading the Maps JavaScript API with the following script tag:

  <script async
      src="https://maps.googleapis.com/maps/api/js?v=alpha
          &key=YOUR_API_KEY&callback=initMap">
  </script>
  

Choosing a version number

Specify a version by number only if you regularly test and update your application. This is because numbered versions are eventually deleted as new versions are created every quarter. You can specify the version number by loading the Maps JavaScript API with the following script tag:

<script async
    src="https://maps.googleapis.com/maps/api/js?v=3.55
        &key=YOUR_API_KEY&callback=initMap">
</script>

Currently, you can specify v=3.56, v=3.55, v=3.54, or v=3.53.

  • Version 3.56 is receiving weekly updates with new features, bug fixes, and performance improvements.
  • Version 3.55 is not receiving weekly updates.
  • Version 3.54 is not receiving weekly updates.
  • Version 3.53 is not receiving weekly updates.
  • We may, from time to time, introduce security bug fixes into any version.
  • We may introduce backwards-incompatible changes when creating a new version.

After mid-May, you will be able to specify v=3.57, v=3.56, v=3.55, or v=3.54.

  • Version 3.57 will receive weekly updates with new features, bug fixes, and performance improvements.
  • Version 3.56 will no longer receive weekly updates.
  • Version 3.55 will no longer receive weekly updates.
  • Version 3.54 will no longer receive weekly updates.
  • We may, from time to time, introduce security bug fixes into any version.
  • Version 3.53 will no longer be available. Any attempt to load this version will be ignored, and you will receive your default channel instead.

The diagram below shows which versions will be available in each channel over the next year.

v=weekly v=quarterly v=3.nn v=3.nn-1 Feb 2024 May 2024 Aug 2024 Nov 2024 v3.53 v3.54 v3.54 v3.55 v3.55 v3.55 v3.56 v3.56 v3.56 v3.56 v3.57 v3.57 v3.57 v3.58 v3.58 v3.59

An update affected my application

When we update the release channels, it could affect your application. This could occur because your application is relying on undocumented or deprecated features, or because of a bug or bug fix we have introduced.

As a temporary workaround, you can reconfigure your application to use an older version.

  1. Open the console in your browser developer tools, and look at the value of google.maps.version.
  2. Update the script tag that loads the API, and request an older version number.
    For example, if google.maps.version is "3.56.2", use v=3.55 in your script tag.
    This temporary workaround will work for a limited time only.

Once the temporary workaround is in place, you will have time (typically 3 to 6 months) to update your application, so it no longer uses undocumented or deprecated features, and accounts for bugs or bug fixes.

You should then revert to the original script tag to load the API.

You are also welcome to create a support case or report an issue.

Quarterly updates

Once per quarter, the Maps JavaScript API team releases a new version. This happens mid-February, mid-May, mid-August, and mid-November. The next update will be mid-May. The new weekly channel will provide version 3.57, and at that time the other channels will be updated.

Weekly channel update

The weekly channel currently points to version 3.56.

In mid-May, the weekly channel will be updated from version 3.56 to version 3.57. At this point, the new version will include new features, remove deprecated features, and/or introduce backwards-incompatibilities. You may need to test for these changes when the channel is updated.

Over the course of the quarter, the new version will be updated weekly with new features, bug fixes, and performance improvements. It will not remove deprecated features and will not introduce backwards-incompatibilities.

Quarterly channel update

The quarterly channel currently points to version 3.55.

In mid-May, the quarterly channel will be updated from version 3.55 to version 3.56. Upon update, this version will include new features, remove deprecated features, and/or introduce backwards-incompatibilities from the previous three months. You may need to test for these changes when the channel is updated.

Over the course of the quarter, this version will not include new features, bug fixes, or performance improvements. It will not remove deprecated features and will not introduce backwards-incompatibilities.

Version updates

In mid-May, the version numbers roll over to accommodate the release of a new version.

Version 3.57

A new version 3.57 will be released in mid-May. Upon release, this version will include new features, remove deprecated features, and/or introduce backwards-incompatibilities compared to version 3.56. You should test your application when changing between version numbers.

During the quarter, the new version will be updated weekly with new features, bug fixes, and performance improvements. It will not remove deprecated features and will not introduce backwards-incompatibilities.

Version 3.56

This version includes new features, removes deprecated features, and/or introduces backwards-incompatibilities compared to version 3.55. You should test your application when changing between version numbers.

After mid-May, this version will no longer be updated with new features, bug fixes, or performance improvements. It will not remove deprecated features and will not introduce backwards-incompatibilities.

Version 3.55

This version includes new features, removes deprecated features, and/or introduces backwards-incompatibilities compared to version 3.54. You should test your application when changing between version numbers.

This version will no longer be updated with new features, bug fixes, or performance improvements. It will not remove features deprecated after this version and will not introduce new backwards-incompatibilities.

Version 3.54

This version includes new features, removes deprecated features, and/or introduces backwards-incompatibilities compared to version 3.53. You should test your application when changing between version numbers.

This version will no longer be updated with new features, bug fixes, or performance improvements. It will not remove features deprecated after this version and will not introduce new backwards-incompatibilities.

Version 3.53

After mid-May, this version will be deleted, and can no longer be used. Any attempt to load this version will be ignored, and you will receive your default channel instead.

Version support

In any given quarter, four versions are available. All four of these versions are supported.

Version checks

For debugging, use the google.maps.version property to obtain the current version of the Maps JavaScript API in your application. The following code sample writes the API version to the browser console. (For more information about the browser console, see the guide to checking errors in your browser.)

<!DOCTYPE html>
<html>
  <head>
    <title>Display Google Maps API Version</title>
  </head>
  <body>
    <script>
      function initMap() {
        // Add your map here.
        console.log('Google Maps API version: ' + google.maps.version);
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    defer></script>
  </body>
</html>

Documentation for the API versions

The developer's guide always describes the weekly version.

In addition, there is a separately maintained reference for each version: