Migration overview

European Economic Area (EEA) developers

This guide highlights key differences between the legacy Places Service and the new Place class. Upgrading to the Place class offers significant advantages, including improved performance and a new pricing model. To get the most out of Places and ensure your apps are up-to-date, familiarize yourself with the changes detailed in this guide.

Billing best practices for migration

This guidance applies if your API usage is high enough to move into second-tier pricing. When migrating to a newer version of an API, you're also being billed for a different SKU. To avoid increased costs during the month of your transition, we recommend switching to the new APIs in production as close to the beginning of the month as possible. This will ensure that you reach the most cost-effective monthly pricing tiers during the migration month. For information about pricing tiers, see the pricing page and the pricing FAQ.

Enable Places API

The Place class relies on the Places API service. To use the features of the new Place class, you must first enable Places API (New) in your Google Cloud project. For more information, see Get started.

General changes

The following table lists some of the main differences between PlacesService and Place:

PlacesService (Legacy) Place (New)
Methods require the use of a callback to handle the results object and google.maps.places.PlacesServiceStatus response. Uses Promises, and works asynchronously.
Methods require a PlacesServiceStatus check. No required status check, can use standard error handling.
Place data fields are formatted using snake case. Place data fields are formatted using camel case.
Limited to a fixed set of place types and place data fields. Provides an expanded selection of regularly updated place types and place data fields.

API-specific changes

The Place class provides an API for using the Places library, and supports modern usage patterns such as Promises. The Place class exposes the same place data fields and place types as the legacy Places Service, and includes many new values for place data fields and place types.

This table shows how features of the Places Service map to those of the Place class:

Places Service (Legacy) Place Class (New)
Place Data Fields Place Class Data Fields
Place Types Place Types
PlacesService.findPlaceFromQuery() Place.searchByText()
PlacesService.findPlaceFromPhoneNumber() Place.searchByText()
PlacesService.textSearch() Place.searchByText()
PlacesService.nearbySearch() Place.searchNearby()
PlacesService.getDetails() Place.fetchFields()
Places.AutocompletionRequest Places.AutocompleteRequest
Places.AutocompletePrediction Places.PlacePrediction
Autocomplete class PlaceAutocompleteElement class
SearchBox class ---

Load the Places library

How your app loads the Places library depends on which bootstrap loader is in use. If your app uses dynamic library import, you can load the needed libraries at runtime by using the await operator to call importLibrary(), as shown here:

const { Place } = await google.maps.importLibrary("places");

If your app uses the direct script loading tag, request the places library in the loader script:

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

Learn more about loading the Maps JavaScript API.

This section includes the following guides to help you migrate your apps to use the newest version of the Places API: