Visão geral da migração

Este guia destaca as principais diferenças entre o serviço de lugares legado e a nova classe Place. Atualizar para a classe Place oferece vantagens significativas, incluindo desempenho aprimorado e um novo modelo de preços. Para aproveitar ao máximo o Places e garantir que seus apps estejam atualizados, conheça as mudanças detalhadas neste guia.

Práticas recomendadas de faturamento para migração

Essa orientação se aplica se o uso da API for alto o suficiente para passar para o nível 2 de preços. Ao migrar para uma versão mais recente de uma API, você também vai receber uma cobrança por uma SKU diferente. Para evitar o aumento de custos durante o mês da sua transição, recomendamos mudar para as novas APIs em produção o mais próximo possível do início do mês. Isso garante que você atinja os níveis de preço mensais mais econômicos durante o mês de migração. Para mais informações sobre os níveis de preços, consulte a página de preços e as Perguntas frequentes sobre preços.

Ativar a API Places

A classe Place depende do serviço da API Places. Para usar os recursos da nova classe Place, primeiro é necessário ativar a API Places (nova) no projeto do Google Cloud. Para mais informações, consulte Começar.

Mudanças gerais

A tabela a seguir lista algumas das principais diferenças entre PlacesService e Place:

PlacesService (legado) Place (novo)
Os métodos exigem o uso de um callback para processar o objeto de resultados e a resposta google.maps.places.PlacesServiceStatus. Usa promessas e funciona de forma assíncrona.
Os métodos exigem uma verificação PlacesServiceStatus. Nenhuma verificação de status necessária. É possível usar o tratamento de erros padrão.
Os campos de dados do lugar são formatados usando letras minúsculas. Os campos de dados de lugar são formatados usando letras maiúsculas e minúsculas.
Limitado a um conjunto fixo de tipos de lugar e campos de dados de lugar. Oferece uma seleção ampliada de tipos de lugar e campos de dados de lugar atualizados regularmente.

Mudanças específicas da API

A classe Place oferece uma API para usar a biblioteca Places e oferece suporte a padrões de uso modernos, como promessas. A classe Place expõe os mesmos campos de dados e tipos de lugar do serviço legado do Google Places e inclui muitos novos valores para campos de dados e tipos de lugar.

Esta tabela mostra como os recursos do serviço do Places são mapeados para os da classe Place:

Serviço do Places (legado) Classe Place (nova)
Campos de dados de lugares Campos de dados da classe Place
Tipos de lugar Tipos de lugar
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
Classe Autocomplete Classe PlaceAutocompleteElement
Classe SearchBox ---

Carregar a biblioteca Places

A forma como o app carrega a biblioteca Places depende de qual carregador de inicialização está em uso. Se o app usar a importação de biblioteca dinâmica, carregue as bibliotecas necessárias no momento da execução usando o operador await para chamar importLibrary(), conforme mostrado aqui:

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

Se o app usar a tag de carregamento direto de script, solicite a biblioteca places no script do carregador:

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

Saiba mais sobre o carregamento da API Maps JavaScript.

Esta seção inclui os seguintes guias para ajudar a migrar seus apps para usar a versão mais recente da API Places: