Visão geral

Selecione a plataforma: Android iOS JavaScript Serviço da Web
A API Places é um serviço que aceita solicitações HTTP de dados de local usando vários métodos. Ela retorna dados e imagens de local formatados sobre estabelecimentos, localizações geográficas ou pontos de interesse importantes.

Por que usar a API Places

Crie recursos de reconhecimento de local para facilitar o acesso a dados detalhados de localização aos usuários. Os dados disponíveis na API Places são criados com base em um dos modelos de local mais precisos, atualizados e abrangentes do mundo real. Veja alguns exemplos de casos de uso para aplicativos:

  • Mostre aluguéis de condomínio nas principais áreas metropolitanas com resultados segmentados especificamente para cidades.
  • Inclua detalhes do lugar em uma atualização de status de retirada ou entrega.
  • Mostra uma lista de parques em uma área, além de fotos e avaliações enviadas pelos usuários.
  • Forneça às pessoas que planejam viagens informações de contato, avaliações e níveis de preços dos estabelecimentos no processo.

O que você pode fazer com a API Places

Você pode usar a API Places para incluir os seguintes recursos nos seus aplicativos:

  • Forneça resultados de pesquisas de lugares de diferentes tipos de consultas de usuários, como entrada de texto, locais próximos e consultas ambíguas ou categóricas do usuário.
  • Ative os recursos de preenchimento automático para diferentes tipos de pesquisa, com consultas de texto específicas ou categóricas.
  • Refine o tipo de detalhes retornados sobre um lugar, como horário de funcionamento, um resumo, avaliações de usuários e uma foto.
  • Adicione fotos de alta qualidade aos locais veiculados pelo seu aplicativo.

Muitas APIs da Plataforma Google Maps são compatíveis com IDs de lugar, em que o ID de lugar identifica um local de forma exclusiva no banco de dados do Google Places e no Maps. Existem muitas maneiras de conseguir um ID de local, por exemplo, na API Places, na API Geocoding, na API Routes e na API Address Validation.

Com o ID de lugar, você pode usar a API Places para solicitar mais detalhes sobre um estabelecimento ou ponto de interesse específico, como endereço completo, número de telefone, classificação de usuários e avaliações.

Escolher sua versão da API Places

A API Places oferece suporte a duas versões: a API Places é a atual, e a API Places (nova) é a versão de última geração.

Com o lançamento da API Places (nova), sua primeira tarefa é decidir qual conjunto de APIs usar. Isso acontece quando você é um novo cliente ou já usa as APIs. Use este guia para saber as principais diferenças entre as duas APIs.

Como a API Places funciona

API Places (nova)

A API Places (nova) aceita solicitações como um URL padrão com um endpoint de serviço específico, como /places ou places:searchText, e retorna uma resposta JSON. A API Places (nova) aceita autorização por chave de API e token OAuth. O exemplo a seguir faz uma solicitação do Place Details para retornar os componentes de endereço de um ID de lugar usando uma chave de API:

https://places.googleapis.com/v1/places/GyuEmsRBfy61i59si0?fields=addressComponents&key=YOUR_API_KEY

API Places

A API Places aceita solicitações como um URL padrão com um endpoint de serviço específico, como /place ou /photo. Os endpoints também aceitam o tipo de formato especificado na solicitação (JSON ou XML). A solicitação de serviço usa parâmetros relevantes para esse endpoint específico a fim de refinar os dados retornados. O exemplo a seguir faz uma solicitação do Place Details para retornar os componentes de endereço de um ID de lugar no formato JSON:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&fields=address_components&key=YOUR_API_KEY

Nesse caso, o serviço usa o ID de lugar fornecido para encontrar o lugar solicitado e retornar os componentes de endereço no formato JSON.

Recursos

A tabela a seguir resume os recursos disponíveis na API Places.

API Places API Places (nova) Observação
Find Place Text Search (novo) Não há nova versão do Find Place. O Text Search (novo) foi substituído.
Nearby Search (Pesquisa de local próximo) Nearby Search (novo) Todas as solicitações que usam a API existente e incluem uma consulta de texto precisam usar o Text Search (New), porque o Nearby Search (novo) não é compatível com a entrada de texto.
Pesquisa de texto Text Search (novo)
Place Details Place Details (novo)
Place Photo Place Photo (novo)
Place Autocomplete Nenhuma versão da API Places (nova)
Preenchimento automático de consultas Nenhuma versão da API Places (nova)

Como usar a API Places

As etapas abaixo abrangem um cenário de caso de uso típico para usar o serviço da API Places. À medida que você cria sua solução, pode usar outros endpoints, como o Nearby Search e o Place Photos.
1 Começar a configurar Para começar, configure seu projeto do Google Cloud, siga as instruções de configuração a seguir. Depois, saiba como usar a chave de API. Para a API Places (nova), você também pode usar tokens OAuth.
2 Fazer uma pesquisa de texto básica Emita uma pesquisa de texto simples usando o Text Search (novo) ou o Text Search.
3 Use o ID de lugar para ver mais detalhes Muitas APIs da Plataforma Google Maps retornam um ID de lugar como parte de uma resposta. Use o ID de lugar para ver detalhes sobre ele. Consulte Place Details (novo) e Place Details.
4 Tirar a foto de um lugar O serviço Place Photo dá acesso a milhões de fotos armazenadas no banco de dados do Places. Use Place Photo (novo) ou Place Details para acessar fotos de um lugar.