Escolha a versão do SDK

A versão 3.4.0 do SDK do Places para Android é compatível com duas versões: o SDK do Places para Android é o atual, e o SDK do Places para Android (novo) é a versão de última geração.

Observação :todos os novos recursos incluídos nesta versão fazem parte do SDK do Places para Android (novo) e não estão disponíveis no SDK do Places para Android.

Com o lançamento da versão 3.4.0 do SDK do Places para Android, sua primeira tarefa é decidir qual SDK usar. Isso é válido se você é um cliente novo ou atual que já usa o SDK. Use este guia para entender as principais diferenças entre os dois SDKs.

Como selecionar a versão do SDK

No back-end, o SDK do Places para Android depende do serviço da API Places, que pode ser a API Places (nova) ou a API Places. Antes de usar o SDK do Places para Android, ative o serviço da API Places no seu projeto do Google Cloud.

No Android, há duas ações para determinar quais APIs podem ser usadas no seu app:

1. No projeto, ative a API Places (nova), a API Places ou ambas na chave de API, dependendo do que você pretende usar no app.

2. Inicialize seu app chamando o método Places.initializeWithNewPlacesApiEnabled() ou Places.initialize().

Selecione seu SDK

A versão do serviço da API Places ativada controla a versão do SDK usada pelo app:

• Ambos: ativa todos os recursos para o SDK do Places para Android e o SDK do Places para Android (novo). Use os métodos Places.initializeWithNewPlacesApiEnabled() e Places.initialize() para controlar os recursos disponíveis.

• API Places: ativa o SDK do Places para Android. Você não tem acesso aos novos recursos adicionados no SDK do Places para Android versão 3.4.0.

• API Places (nova): ativa o SDK do Places para Android (novo) e todos os novos recursos descritos em Principais recursos adicionados ao SDK do Places para Android (novo), mas não ativa os recursos atuais, como o Current Place e o Place Autocomplete.

Para mais informações sobre como selecionar o serviço da API Places, consulte Configurar seu projeto do Google Cloud.

Inicializar seu app

Ao inicializar o app, é necessário chamar o método Places.initializeWithNewPlacesApiEnabled() ou Places.initialize().

A tabela a seguir mostra os efeitos de ativar cada SDK e chamar cada método de inicialização. Por exemplo, se você ativar o SDK do Places (novo) e chamar Places.initializeWithNewPlacesApiEnabled(), poderá usar todas as APIs novas e atuais.

Se você ativar o SDK do Places (novo) e chamar Places.initialize(), não poderá usar os novos recursos do Place Details e do Place Photos, mas poderá chamar o novo Text Search. Se você não ativar a API Places, não vai ser possível acessar a versão antiga do Place Details, mas ainda será possível chamar a nova Text Search.

Versão	APIs	SDK ativado na chave de API		Método de inicialização
		API Places	API Places (nova)	initialize()	initializeWithNewPlacesApiEnabled()
v3.3.0	Places Details
	Places Details (novo)
	Metadados de fotos (novo)
	Text Search (novo)			Qualquer um dos métodos
v3.4.0	URI da foto (novo)
	Bitmap de foto			Qualquer um dos métodos
	CurrentPlace			Qualquer um dos métodos
	Preenchimento automático			Qualquer um dos métodos

Qual SDK você deve escolher?

Para ajudar a decidir qual versão escolher:

1. Se você é um novo cliente e está começando a usar o SDK do Places para Android, comece com a API Places (nova) e o novo SDK.

2. Se você é um desenvolvedor Kotlin, pode usar qualquer um dos SDKs, mas os novos recursos do SDK do Places para Android (novo) estão disponíveis apenas em Java na versão 3.4.0.

3. Se você for um cliente atual e estiver usando tokens de sessão, continue usando o SDK atual. No momento, o SDK do Places para Android (novo) não é compatível com tokens de sessão.

4. Se você for um cliente atual, poderá continuar usando o SDK atual. No entanto, para aproveitar as melhorias de performance e os recursos do SDK do Places para Android (novo), você pode usar o novo SDK.

   Não é necessário migrar para o novo SDK. Você só precisa:

   1. Ative a API Places (nova) na chave de API usada no seu app. Para saber mais, consulte Usar chaves de API.

   2. Na seção dependencies do arquivo build.gradle no módulo, atualize a dependência places e adicione a dependência kotlin-bom:

        dependencies {
            implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
            implementation 'com.google.android.libraries.places:places:3.3.0'
        }

      Para saber mais sobre a dependência kotlin-bom, consulte Uso da versão mais recente de kotlin-stdlib em dependências transitivas.

   3. Atualize seu app para chamar o novo método Places.initializeWithNewPlacesApiEnabled() e inicializá-lo. Para saber mais, consulte Inicializar o cliente da API Places.

   Os apps atuais continuam funcionando inalterados, mas agora você pode aproveitar todos os novos recursos do SDK.

Principais recursos adicionados ao SDK do Places para Android (novo)

Esta seção aborda os principais recursos adicionados ao SDK do Places para Android (novo).

Implementado na plataforma padrão do Google Cloud

O SDK do Places para Android (novo) é implementado na infraestrutura de serviços no Google Cloud. Essa implementação traz uma plataforma mais segura e confiável. Esse design padrão traz um nível de consistência entre os SDKs, o que melhora a eficiência do desenvolvimento com o SDK do Places para Android (novo).

Tem desempenho aprimorado

O SDK do Places para Android (novo) oferece um desempenho aprimorado, o que faz com que valha a pena substituir apps que usam o SDK existente.

Novo serviço Text Search

A Pesquisa por texto retorna informações sobre um conjunto de lugares com base em uma string, por exemplo, "pizza em São Paulo", "loja de sapatos perto do Rio de Janeiro" ou "Avenida Brasil, 123". O serviço responde com uma lista de lugares correspondentes à string de texto e a todos os direcionamentos de localização definidos.

Novos dados de resposta adicionados ao Placed Details e Place Photos

• O Place Details agora inclui a nova classe Review no objeto Place de resposta. A classe Place contém o novo método getReviews() para oferecer suporte a esse campo. Chame getReviews() para retornar até cinco avaliações de um lugar.

• O Place Photo adiciona o AuthorAttributions à classe PhotoMetadata. AuthorAttributions contém um List de objetos AuthorAttribution.

Nova resposta de URI adicionada ao Place Photos

Agora você pode usar o Place Photos para retornar um URI para um bitmap de imagem. Antes, só era possível retornar o próprio bitmap de imagem.

Preços simplificados

Os preços foram simplificados com o SDK do Places para Android (novo). Assim, você paga apenas pelos dados que usar. O preço simplificado é implementado usando listas de campos, também chamadas de máscaras de campo.

Com o Place Details e o Text Search, você usa listas de campos para controlar a lista de campos a serem retornados na resposta. Você só será cobrado pelos dados solicitados. O uso de uma lista de campos é uma boa prática de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar cobranças de faturamento e tempo de processamento desnecessários.

Para informações detalhadas sobre preços de ambos os SDKs, consulte Uso e faturamento.

Observação : o novo modelo de preços se aplica apenas a Place Details, Text Search e Place Photos. Os preços do Place Autocomplete e do Current Place são os mesmos para os dois SDKs.

Tipos de lugar expandidos

O novo SDK adiciona os tipos de lugar mostrados na tabela a seguir. Esses tipos são retornados como parte da resposta do Place Details e do Text Search. Você também pode usar esses novos tipos e os existentes em uma pesquisa com o Text Search. Os novos tipos estão incluídos na Tabela A.

Tipo
american_restaurant	discount_store	ice_cream_shop	sandwich_shop
amusement_center	dog_park	indian_restaurant	school_district
athletic_field	electric_vehicle_charging_station	indonesian_restaurant	seafood_restaurant
auto_parts_store	event_venue	italian_restaurant	ski_resort
banquet_hall	extended_stay_hotel	japanese_restaurant	spanish_restaurant
barbecue_restaurant	fazenda	korean_restaurant	sporting_goods_store
barber_shop	hotel-fazenda	lebanese_restaurant	sports_club
bed_and_breakfast	fast_food_restaurant	Marina	sports_complex
brazilian_restaurant	ferry_terminal	mercado	steak_house
breakfast_restaurant	fitness_center	medical_lab	sushi_restaurant
brunch_restaurant	french_restaurant	mediterranean_restaurant	swimming_pool
bus_stop	gift_shop	mexican_restaurant	alfaiate
camping_cabin	golf_course	middle_eastern_restaurant	telecommunications_service_provider
cell_phone_store	greek_restaurant	motel	thai_restaurant
child_care_agency	grocery_store	national_park	transit_depot
chinese_restaurant	guest_house	park_and_ride	truck_stop
coffee_shop	hair_salon	performing_arts_theater	turkish_restaurant
community_center	hamburger_restaurant	pizza_restaurant	vegan_restaurant
consultor	heliporto	playground	vegetarian_restaurant
convention_center	hiking_area	pré-escolar	vietnamese_restaurant
casa de campo	historical_landmark	private_guest_room	visitor_center
courier_service	home_improvement_store	ramen_restaurant	wedding_venue
cultural_center	albergue	resort_hotel	atacadista
dental_clinic	hotel	rest_stop

Junto com esses novos tipos, a API Places (nova) moveu os seguintes tipos da Tabela B da Tabela A. Isso significa que agora é possível usar estes tipos como parte de uma pesquisa:

• country
• administrative_area_level_1
• administrative_area_level_2
• postal_code
• locality