To improve Google Maps Platform for developers and end users, sometimes we need to deprecate existing functionality. For example, last year when many establishments closed temporarily to limit the spread of COVID-19, we introduced the business_status field to describe a place's status in a non-binary way and deprecated the permanently_closed field because it cannot accurately describe a place that is temporarily closed.
We try to minimize deprecations because we recognize that changing your production code can be stressful. When you receive a communication about a deprecation that may affect your project, understanding how Google Maps Platform deprecations work can help you decide when to take action.
Deprecation vs decommissioning
First, let's take a look at definitions for two terms that are often confused in software discussions.
deprecated**:** It is recommended to stop using this. Reasons to stop may include a better alternative or a planned decommissioning.
decommissioned: Something that was once available is no longer available or supported. Calling decommissioned software can result in unpredictable behavior or invalid responses.
Deprecations in SDKs: how they're different from API deprecations
In SDKs, there are two levels of deprecation: version deprecation and feature deprecation. When a version of the SDK is deprecated, it will soon be decommissioned. Building with a dependency on a decommissioned SDK version may cause errors or crashes, so when you see a notice that an SDK version is deprecated, please make time to migrate to a newer version—ideally, the latest available version.
The two diagrams below illustrate two stages of feature deprecation. First, a new major version is introduced that does not include the deprecated feature. You can still use the deprecated feature by specifying an older version in your dependencies. However, you will not be able to use any features that are exclusively available in the newer version until you remove use of the deprecated feature from your code and update your dependency to the new version.
Example of deprecating Feature B in an SDK. Since v3.0 does not include Feature B, v2 is the last supporting version of Feature B. To continue using Feature B, specify v2. Remove use of Feature B from code in order to upgrade to v3.0.
Once the last version that supports the deprecated feature is itself decommissioned, there are no more versions that support the feature and any continued use of the feature is not guaranteed to work.
Example of decommissioning a version of an SDK. Since v2 is the last supporting version of Feature B and is no longer supported, Feature B is no longer available. New builds of applications depending on the SDK must upgrade to a supported version and therefore stop using Feature B.
Learn more about the nuances of deprecations in APIs and SDKs in our deprecations documentation, which also lists all active deprecations.
How to manage SDK dependencies
For developers using Google Maps Platform mobile SDKs (Maps and Places SDKs for Android, Maps and Places SDKs for iOS), managing your dependency versions can help you schedule deprecation migration changes according to your app development cycle instead of as a rushed fix before a deadline.
For mobile SDKs, it's best to specify an exact version number in your app's dependencies. We've added documentation for how to manage your SDK dependencies for Maps SDK for Android, Places SDK for Android, Maps SDK for iOS, and Places SDK for iOS.
The Maps JavaScript API is different from the mobile SDKs. We recommend that you always load the latest version by default (v=weekly), because versions are released and decommissioned on a quarterly schedule. Learn more about how to prepare for regular Maps JavaScript API updates here.
You choose when to update code
The final step is to schedule code maintenance regularly in your development cycle, so that you can minimize technical debt and enjoy the latest improvements in the SDKs. The release notes and mandatory service announcements point to migration guides or provide workarounds for deprecated features in order to minimize the effort needed to update your code.
By following the steps above, the next time you receive a notification about deprecated features or versions, you can relax, knowing that you'll be able to choose when you have time to update your code to adopt the latest SDK version. Your mobile app builds will be predictable against stable SDK versions, and you'll know what to do (specify an earlier version) when you receive JavaScript release notes about changes that may affect your website. We hope these tips allow you to plan ahead for code updates, so deprecation notices don't cause stress.
For more information on Google Maps Platform, visit our website.
