Versioning

The Google 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, whether in a test or production environment. The API versions have the following names:

• Experimental
• Release
• Frozen

We also provide best practices for managing your versioning procedures based on the type or purpose of your application.

Version rollover and version types

Each quarter we cut a new numbered version and release it for public use as the experimental version. At the same time, the previous experimental version becomes the release version, and the previous release version becomes the frozen version. This process is called version rollover.

Throughout the quarter we continue to add bug fixes to the experimental and release versions. These updates are noted in the Google Maps JavaScript API release notes.

You can indicate which version of the API to load in your application by specifying the v parameter of the Google Maps JavaScript API bootstrap request. The following options are supported:

• The experimental version, specified with v=3.exp.
• The release version, specified with v=3.
• A specific version number. For example v=3.23 or v=3.24.

If you do not explicitly specify a version, you will receive the experimental version by default if you are on the standard plan (this includes customers who do not provide a key). If you're on the premium plan and don't specify a version, you will receive the release version by default.

The experimental version

The experimental version — currently 3.25 — 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.25 when loading the 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.

You can specify the experimental version with the following bootstrap:

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

The release version

We continually apply bug fixes to the release version, while ensuring the feature set remains stable. The fixes are listed in the release notes.

The current release version is 3.24. You can request it with either of the following bootstraps:

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

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

The frozen version

When we release a new numbered version, we freeze the previous release version, meaning that we no longer update it with regular bug fixes. However, we may occasionally make changes, for example if there is a legal reason for doing so.

Each time we introduce a new frozen version, we retire the previous frozen version. Specifying a retired version, such as v=3.0, will always return the current frozen version.

The current frozen version is 3.23. You can request it with the following bootstrap:

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

Best practices

The Google Maps JavaScript API team makes every effort to maintain compatibility across different versions of the API. However, in order to continue to provide a modern service, as well as for operational reasons, we occasionally make changes that may interact with existing features. At such times it may be necessary, especially for more advanced applications, to make adjustments to code using the Google Maps JavaScript API so that your code continues to work as expected. Below we present recommended best practices for version usage, for a number of common scenarios.

For high availability / high traffic applications

Willing to do extra work to ensure stability and availability

In order to make sure that there are no issues arising from version rollover, we recommend that you explicitly specify the number of the current release version of the API in the bootstrap. For example, v=3.24. In order to avoid dropping down to the frozen version of the API as time passes, it is important to subscribe to version rollover notifications from Google on the Google Maps JS API v3 Notifications and Announcements group.

After a version rollover takes place (every quarter), your production system will be requesting the frozen version of the API. At this time we recommend setting up a staging/development environment in order to test your application with the new release version of the API. If any issues arise, you can make the necessary adjustments in your code. When you are confident that your application is running smoothly with the new release version of the API, you can push out the necessary fixes (if any) while simultaneously updating your application to request the version number corresponding to the new release version.

For regular applications

We recommend specifying v=3 in your bootstrap request. This means that you always get the current release version of the Google Maps JavaScript API that has already been subjected to a large volume of traffic and had necessary bug fixes applied. In most cases you should expect that no action is necessary when a version rolls over. However, to ensure your application continues to function smoothly we recommend subscribing to version rollover notifications from Google on the Google Maps JS API v3 Notifications and Announcements group.

After a rollover takes place, your application is using a new version of the Google Maps JavaScript API. You may also wish to inspect the release notes to learn of any changes that may affect you. If you notice that anything within your application is not working correctly, you can switch back to the old version by explicitly specifying the number of the current frozen version in your bootstrap request while you make the necessary adjustments in your code.

For cutting-edge applications

Wanting early access to the latest features

For applications where consistent availability is less critical, we recommend you get all the latest features by requesting the experimental version (v=3.exp) of the Google Maps JavaScript API. The experimental version is fully tested by Google prior to release each week and is generally quite stable. However, the weekly release cycle means that additional vigilance is required to ensure that your application continues to work as expected.

Documentation for the API versions

The developer's guide always describes the experimental version.

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

• Version 3.25 Reference (Experimental)
• Version 3.24 Reference (Release)
• Version 3.23 Reference (Frozen)
• Versions 3.0 - 3.22 have been retired.