No mundo atual, em que a localização é importante, os usuários esperam acesso fácil a informações de lugares, rotas e navegação. Seja por um app de mensagens, um app de descoberta de contexto local , uma plataforma de logística e transporte, um planejador de viagens ou uma plataforma de anúncios imobiliários , os usuários geralmente precisam visualizar rapidamente os detalhes de um local ou encontrar o melhor trajeto de A para B. Embora os desenvolvedores possam criar a própria experiência no app, aproveitar a interface abrangente e familiar do Google Maps oferece uma experiência superior.
Um URL do Google Maps bem estruturado é essencial para uma experiência do usuário perfeita. URLs incorretos comprometem essa experiência, direcionando os usuários para o local errado, mostrando uma visualização genérica do mapa em vez de detalhes específicos ou até mesmo resultando em um link corrompido. Isso frustra os usuários e impede que eles atinjam o objetivo. Por exemplo, mesmo com um URL válido do Maps, um usuário que espera detalhes sobre uma empresa específica pode acessar uma visualização geral do mapa sem informações relevantes. Confira o exemplo abaixo:
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152
Esse URL do Maps é válido para abrir o Google Maps e mostrar um local com base na latitude e longitude. No entanto, ele não fornece aos usuários detalhes sobre um lugar específico.
Como conectar seu aplicativo ao Google Maps com URLs precisos
A Plataforma Google Maps (GMP, na sigla em inglês) oferece dois métodos principais para criar URLs precisos: a API Places(nova), que exige uma chave de API, e os URLs do Maps, que são sem custo financeiro e não exigem uma chave. As soluções a seguir abordam diferentes cenários e casos de uso:
Como usar o campo googleMapsUri ou googleMapsLinks da API Places(nova) da GMP
A API Places(nova) da GMP retorna um conjunto abrangente de informações sobre um
lugar específico. Ao solicitar o campo googleMapsUri ou googleMapsLinks
(especificando-o na máscara de campo), a resposta da API inclui um objeto de lugar.
Esse objeto contém URLs pré-formatados, que podem ser usados para abrir diretamente
a visualização correspondente, como a visualização de detalhes do lugar, no Google Maps.
Exemplo:
Solicitação do Place Details
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: YOUR_API_KEY" \ -H "X-Goog-FieldMask: googleMapsUri,googleMapsLinks" \ https://places.googleapis.com/v1/places/ChIJ3S-JXmauEmsRUcIaWtf4MzE
Resposta do Place Details:
{
"googleMapsUri": "https://maps.google.com/?cid=3545450935484072529",
"googleMapsLinks": {
"directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!3e0",
"placeUri": "https://maps.google.com/?cid=3545450935484072529",
"writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!12e1",
"reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!9m1!1b1",
"photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!10e5"
}
}ChIJ3S-JXmauEmsRUcIaWtf4MzE no exemplo acima é o ID de lugar de Sydney
Opera House no exemplo acima. O ID de lugar é um identificador textual que identifica um local de forma exclusiva no banco de dados do Google Places e no Google Maps.
Como recuperar IDs de lugares sem custo financeiro
Para recuperar IDs de lugares de forma programática, use a funcionalidade API Places: Text Search(somente ID). Esse é um método sem custo financeiro para receber IDs de lugares. Saiba mais sobre o ID de lugar e a solicitação da API Places(nova).
API Places: Text Search(somente ID) Solicitação:
curl -X POST -d '{"textQuery" : "Sydney Opera House"}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'API Places: Text Search(somente ID) Resposta:
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}Os IDs de lugares também podem ser recuperados quando um usuário clica ou toca em um PDI nos mapas. Saiba mais detalhes sobre ícones de PDI clicáveis(JavaScript, Android, iOS)
Implementação
Ao usar a API Places, os desenvolvedores podem simplesmente extrair o campo googleMapsUri ou googleMapsLinks da resposta e usá-lo para iniciar a visualização correspondente no app Google Maps ou em um navegador se o app não estiver instalado.
| Recurso | Descrição |
|---|---|
| directionsUri | Link para abrir o Google Maps e mostrar rotas do local atual do usuário até esse lugar |
| placeUri | Link para abrir o Google Maps na página de detalhes desse lugar |
| writeAReviewUri | Link para abrir o Google Maps na página de avaliação desse lugar |
| reviewsUri | Link para abrir o Google Maps na página de avaliações desse lugar |
| photosUri | Link para abrir o Google Maps na página de fotos desse lugar |
Confira as orientações para desenvolvedores e teste o recurso hoje mesmo.
Como usar os URLs do Maps
Com os URLs do Maps, você pode criar um URL universal multiplataforma para abrir o Google Maps e fazer pesquisas, ver rotas e navegar, além de mostrar visualizações de mapa e imagens panorâmicas. A sintaxe do URL é a mesma, independentemente da plataforma em uso. Não é necessário ter uma chave de API do Google para usar os URLs do Maps.
As ações de mapa disponíveis são:
A função de pesquisa inicia um app Google Maps ou um navegador se o app não estiver instalado, que mostra um marcador para um lugar específico ou faz uma pesquisa geral e inicia um mapa para mostrar os resultados.
A função Rotas inicia um app Google Maps ou um navegador se o app não estiver instalado, que mostra rotas entre pontos ou ativa a navegação guiada no Google Maps para dispositivos móveis.
A função de panorama do Street View permite iniciar um visualizador para mostrar imagens do Street View como panoramas interativos.
Acesse a documentação para desenvolvedores de URLs do Maps da GMP para conferir mais funções e exemplos.
Aqui, vamos analisar duas funcionalidades principais dos URLs do Maps:
Como mostrar detalhes de lugares no Google Maps:esta seção explica como criar URLs que mostram detalhes de um local específico no Google Maps. Ela também detalha como trabalhar com lugares que têm nomes não exclusivos usando IDs de lugares e consultas precisas.
Como fornecer rotas usando URLs do Maps:esta seção explica como criar URLs que fornecem rotas entre locais, incluindo rotas com vários waypoints e navegação guiada.
Como mostrar detalhes de lugares no Google Maps
A função de pesquisa usa dois parâmetros para concluir a pesquisa de lugares, que
são query(obrigatório) e query_place_id(opcional).
O parâmetro query é obrigatório para todas as solicitações de pesquisa. Ele aceita um nome de lugar
, coordenadas de latitude/longitude separadas por vírgulas ou um termo de pesquisa geral.
A estrutura do URL de pesquisa:
https://www.google.com/maps/search/?api=1¶meters
Situação 1: como mostrar detalhes de um lugar com um nome exclusivo
https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House
Agora, considere um lugar com um nome não exclusivo. O que acontece quando você pesquisa apenas por esse nome não exclusivo? Confira o próximo cenário.
Situação 2: pesquisar lugares com um nome não exclusivo
https://www.google.com/maps/search/?api=1&query=7-Eleven
Como o nome do lugar não é exclusivo, esse URL abre uma lista de locais próximos do 7-Eleven na janela de visualização. Os usuários podem escolher uma loja específica para conferir os detalhes.
Para evitar a lista de locais e acessar diretamente uma página de detalhes específica, você pode usar um método mais preciso. Confira o próximo exemplo.
Situação 3: como mostrar detalhes de um lugar com um nome não exclusivo
Ao lidar com nomes de lugares comuns, uma pesquisa simples de nome geralmente retorna uma lista de locais. Para criar um link direto para uma página de detalhes específica, use um dos seguintes métodos:
Método 1: usar uma consulta precisa com o nome e o endereço do lugar
https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia
Nesse URL, o parâmetro query é formatado como nome do lugar, endereço. Isso
ajuda a restringir a pesquisa e criar um link direto para o local pretendido.
Método 2: usar o ID de lugar
IDs de lugares identificam um local de modo exclusivo no banco de dados do Google Places e no Google Maps.
https://www.google.com/maps/search/?api=1&query=7-Elevan&query_place_id=ChIJGcmcg7ZC1moRAOacd3HoEwM
Aqui, ChIJGcmcg7ZC1moRAOacd3HoEwM é o ID de lugar exclusivo para o lugar específico. O parâmetro query ainda é obrigatório, mas só será usado se o Google
Maps não encontrar o ID do lugar.
Situação 4: como mostrar detalhes de um lugar usando coordenadas de latitude e longitude, bem como o ID do lugar
O uso do ID de lugar garante que o Google Maps mostre informações detalhadas sobre o lugar.
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE
Como recuperar IDs de lugares sem custo financeiro
Para recuperar IDs de lugares de forma programática, use a funcionalidade API Places: Text Search(somente ID). Esse é um método sem custo financeiro para receber IDs de lugares. Saiba mais sobre o ID de lugar e a solicitação da API Places(nova).
API Places: Text Search(somente ID) Solicitação:
curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'API Places: Text Search(somente ID) Resposta:
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}Os IDs de lugares também podem ser recuperados quando um usuário clica ou toca em um PDI nos mapas. Saiba mais detalhes sobre ícones de PDI clicáveis(JavaScript, Android, iOS)
Conclusão
Fornecer detalhes precisos do lugar é fundamental para uma experiência positiva. Para garantir que os usuários acessem a página de detalhes do lugar correto, crie os URLs de pesquisa usando um dos seguintes formatos recomendados:
query=PLACE_NAME, ADDRESSquery=PLACE_NAME&query_place_id=PLACE_ID
Evite usar apenas coordenadas de latitude/longitude no query parâmetro quando
seu objetivo for mostrar os detalhes de um lugar específico. Formatos como
query=latitude,longitude, query=PLACE_NAME,latitude,longitude,
ou query=ADDRESS,latitude,longitude não vão levar de forma consistente à
página de detalhes do lugar desejado. Em vez disso, ele vai mostrar a latitude e a longitude de
o local.
Pesquisa categórica usando URLs do Maps
Em uma pesquisa categórica, você transmite um termo de pesquisa geral, e o Google Maps tenta encontrar anúncios que correspondam aos seus critérios perto do local especificado. Se nenhum local for especificado, o Google Maps tentará encontrar anúncios próximos ao seu local atual.
Situação 1: pesquisa de lugares por perto
https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now
Como fornecer rotas usando URLs do Maps
A função de rotas mostra o caminho entre dois ou mais pontos especificados no mapa, bem como a distância e o tempo de viagem. Ela oferece aos desenvolvedores mais controle sobre as rotas fornecidas. A documentação de rotas de URLs do Maps da GMP fornece instruções detalhadas sobre como criar URLs para rotas personalizadas.
A estrutura do URL de rotas:
https://www.google.com/maps/dir/?api=1¶meters
Situação 1: encontrar o melhor trajeto do local atual do usuário até um destino
https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving
Esse URL abre o Google Maps e mostra rotas de carro do local atual do usuário.
Nesse URL, a origin é omitida. Quando origin é omitida, o caminho é definido
como o local de partida mais relevante, como o local do dispositivo, se disponível.
Se não houver nenhum, o mapa resultante vai mostrar um formulário para que o usuário insira a origem.
O valor de origem e destino pode ser um nome de lugar, endereço ou
coordenadas de latitude/longitude separadas por vírgulas.
O travelmode é um parâmetro opcional. Ele define o método de viagem.
Esse parâmetro pode ser definido como:
- de carro
- caminhada
- bicicleta
- motocicleta
- transporte público
Se nenhum travelmode for especificado, o Google Maps vai mostrar um ou mais dos modos mais relevantes para o trajeto especificado e/ou as preferências do usuário.
Os desenvolvedores também podem especificar IDs de lugares usando o parâmetro origin_place_id e
destination_place_id. Usar um ID de lugar é a melhor garantia de que você vai
criar um link para o lugar certo.
Como recuperar IDs de lugares sem custo financeiro
Para recuperar IDs de lugares de forma programática, use a funcionalidade API Places: Text Search(somente ID). Esse é um método sem custo financeiro para receber IDs de lugares. Saiba mais sobre o ID de lugar e a solicitação da API Places(nova).
API Places: Text Search(somente ID) Solicitação:
curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'API Places: Text Search(somente ID) Resposta:
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}Os IDs de lugares também podem ser recuperados quando um usuário clica ou toca em um PDI nos mapas. Saiba mais detalhes sobre ícones de PDI clicáveis(JavaScript, Android, iOS)
Situação 3: como fornecer navegação guiada
https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate
Definir dir_action=navigate no URL vai iniciar o Google Maps no modo de navegação guiada se o local atual do usuário(local do dispositivo) estiver disponível e
for usado como origem (fornecido explicitamente ou usado implicitamente quando o parâmetro de origem
é omitido). Caso contrário, uma prévia do trajeto será mostrada.
A navegação guiada é iniciada quando dir_action=navigate é definido e:
- A origem é especificada e está perto do local atual do usuário
- A origem é omitida e o local atual do usuário está disponível
A prévia do trajeto é iniciada quando:
dir_action=navigatenão está definidodir_action=navigateestá definido e a origem é especificada, e a origem não está perto do local atual do usuáriodir_action=navigateestá definido e a origem é omitida, e o local atual do usuário não está disponível
A navegação não está disponível em todos os produtos do Google Maps, como o Google Maps para Web, e/ou entre todos os destinos. Nesses casos, esse parâmetro será ignorado.
 |
 |
Conclusão
Ao criar os URLs do Maps corretamente, você garante que os usuários recebam as informações certas de que precisam de forma rápida e eficiente.
Sempre especifique o destino e use o ID do lugar sempre que possível para garantir a precisão
Quando o objetivo é fornecer navegação imediata, inclua o parâmetro dir_action=navigate para acionar a navegação guiada. A navegação será iniciada no local atual do usuário se o local do dispositivo estiver disponível e for usado como origem (definido explicitamente ou omitido)
Como escolher a abordagem certa para seu aplicativo
Você tem duas opções principais: aproveitar os URLs pré-formatados fornecidos pela API Places ou criar manualmente URLs do Maps no seu aplicativo. Cada abordagem tem seu próprio conjunto de vantagens e desvantagens.
API Places:
Os campos
googleMapsUriegoogleMapsLinksna resposta do Place Details fornecem URLs prontos para uso. Isso reduz o tempo de desenvolvimento e minimiza o risco de erros na formatação do URL.Oferece menos controle sobre a configuração das rotas. Embora
googleMapsLinksofereça rotas básicas, ele não aceita waypoints ou personalização avançada. Além disso, é relativamente menos simples acionar a navegação guiada diretamente.
URLs do Maps:
Oferece maior flexibilidade e controle. Os desenvolvedores podem criar URLs para mostrar detalhes de lugares e configurar vários aspectos das rotas, incluindo a adição de waypoints, a especificação de modos de viagem e o início da navegação guiada.
Exige um conhecimento mais profundo dos parâmetros e da estrutura do URL. A criação manual aumenta o potencial de erros se não for feita com cuidado.
Como melhorar os URLs do Maps com parâmetros UTM
Para ajudar o Google a entender melhor como os desenvolvedores estão integrando os URLs do Maps e
garantir a performance ideal, recomendamos que você inclua parâmetros de rastreamento UTM
na criação do URL. Ao adicionar os parâmetros utm_source e utm_campaign, você
fornece dados valiosos que nos permitem analisar padrões de uso e melhorar o produto de URLs do
Maps.
Para o parâmetro utm_source, use o nome do seu aplicativo. O
utm_campaign parâmetro precisa refletir a ação pretendida do usuário, como
"compartilhamento_de_localização", "pesquisa_de_detalhes_do_lugar" ou "solicitação_de_rotas".
Por exemplo, um URL com parâmetros UTM pode ser assim:
https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YourAppName&utm_campaign=place_details_search
O uso consistente desses parâmetros nos ajuda a identificar áreas de melhoria, resolver problemas com mais eficiência e, por fim, oferecer uma experiência melhor para todos os usuários.
Próximas etapas
Leituras sugeridas:
Colaboradores
Principais autores:
Teresa Qin | Engenheira de soluções da Plataforma Google Maps