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. |