No mundo atual, em que a localização é importante, os usuários esperam ter 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 ver 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, usar a interface abrangente e conhecida do Google Maps oferece uma experiência superior.
Um URL do Google Maps bem estruturado é essencial para uma experiência do usuário integrada. 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 quebrado. Isso frustra os usuários e impede que eles alcancem o objetivo. Por exemplo, mesmo com um URL do Maps válido, um usuário que espera detalhes sobre uma empresa específica pode acessar uma visualização geral do mapa sem informações relevantes. Veja 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 detalhes sobre um lugar específico.
Fazer a ponte entre seu aplicativo e o Google Maps com URLs precisos
A Plataforma Google Maps (GMP) 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:
Usando o campo googleMapsUri ou googleMapsLinks da API Places da GMP(nova)
A API Places do GMP(nova) 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 de 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 do lugar da Sydney Opera House. Um ID de lugar é um identificador textual que identifica de forma exclusiva um lugar no banco de dados do Google Places e no Google Maps.
Recuperar IDs de lugares sem custo financeiro
Para recuperar IDs de lugar de forma programática, use a funcionalidade API Places: Pesquisa de texto(somente ID). Esse é um método de custo zero para receber IDs de lugares. Saiba mais sobre o ID de lugar e a solicitação da API Places(nova).
Solicitação da Pesquisa de texto da API Places(somente ID):
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'Resposta da Pesquisa de texto da API Places(somente ID):
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}Os IDs de lugar 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é este lugar |
| placeUri | Link para abrir a página de detalhes do lugar no Google Maps |
| writeAReviewUri | Link para abrir a página de escrita de avaliações do Google Maps para este lugar |
| reviewsUri | Link para abrir a página de avaliações deste lugar no Google Maps |
| photosUri | Link para abrir o Google Maps na página de fotos deste 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 em várias plataformas para abrir o Google Maps e fazer pesquisas, ver rotas e navegar, além de exibir visualizações de mapa e imagens panorâmicas. A sintaxe do URL é a mesma, independente da plataforma em uso. Você não precisa de uma chave de API do Google para usar os URLs do Maps.
As ações disponíveis no mapa são:
A função de pesquisa inicia um app do Google Maps ou um navegador se o app não estiver instalado. Ela mostra um marcador para um lugar específico ou realiza uma pesquisa geral e abre 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. Ela mostra rotas entre pontos ou ativa a navegação curva a curva no Google Maps para dispositivos móveis.
Com a função de panorama do Street View, é possível abrir um visualizador para mostrar imagens do Street View como panoramas interativos.
Acesse a documentação para desenvolvedores de URLs do Google Maps Platform e confira mais funções e exemplos.
Aqui, vamos analisar duas funcionalidades principais dos URLs do Maps:
Mostrar detalhes do lugar no Google Maps:esta seção explica como criar URLs que mostram detalhes de um local específico no Google Maps. Ele também detalha como trabalhar com lugares que têm nomes não exclusivos usando IDs de lugar e consultas precisas.
Fornecer rotas usando URLs do Maps:esta seção explica como criar URLs que fornecem rotas entre locais, incluindo rotas com vários pontos de parada e navegação curva a curva.
Exibir detalhes do lugar no Google Maps
A função "Search" usa dois parâmetros para concluir a pesquisa de lugares: 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írgula ou um termo de pesquisa geral.
A estrutura do URL de pesquisa:
https://www.google.com/maps/search/?api=1¶meters
Cenário 1: 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.
Cenário 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 da 7-Eleven na janela de visualização. Em seguida, os usuários podem escolher uma loja específica para ver os detalhes.
Para evitar a lista de locais e acessar diretamente uma página de detalhes específica, use um método mais preciso. Confira o próximo exemplo.
Cenário 3: 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 vincular diretamente a uma página de detalhes específica, use um dos seguintes métodos:
Método 1: usar uma consulta precisa com nome e endereço do lugar
https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia
Neste URL, o parâmetro query é formatado como nome do lugar, endereço. Isso ajuda a restringir a pesquisa e vincular diretamente ao local pretendido.
Método 2: usar o ID do lugar
Os IDs de lugar identificam um local de forma exclusiva 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 do local específico. O parâmetro query ainda é necessário, mas só será usado se o Google Maps não conseguir encontrar o ID do lugar.
Cenário 4: mostrar detalhes do lugar usando coordenadas de latitude e longitude, além do ID do lugar
Usar o ID de lugar garante que o Google Maps mostre informações detalhadas sobre o local.
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE
Como recuperar IDs de lugar sem custo financeiro
Para recuperar IDs de lugar de forma programática, use a funcionalidade API Places: Pesquisa de texto(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).
Solicitação da Pesquisa de texto da API Places(somente ID):
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'Resposta da Pesquisa de texto da API Places(somente ID):
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}Os IDs de lugar 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
É fundamental fornecer detalhes precisos para uma experiência positiva. Para garantir que os usuários cheguem à página de detalhes do lugar correta, 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 parâmetro query quando o objetivo for mostrar detalhes de um lugar específico. Formatos como query=latitude,longitude, query=PLACE_NAME,latitude,longitude ou query=ADDRESS,latitude,longitude não levam consistentemente à página de detalhes do lugar desejada. Em vez disso, ela vai mostrar a latitude e a longitude do local.
Pesquisa por categorias usando URLs do Maps
Em uma pesquisa por categoria, você transmite um termo de pesquisa geral, e o Google Maps tenta encontrar listagens que correspondam aos seus critérios perto do local especificado. Se nenhum local for especificado, o Google Maps vai tentar encontrar fichas nas proximidades da sua localização atual.
Cenário 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 Rotas mostra o caminho entre dois ou mais pontos especificados no mapa, além da distância e do tempo de viagem. Ela oferece aos desenvolvedores mais controle sobre as rotas fornecidas. A documentação Instruções de URLs do Maps do GMP (em inglês) oferece instruções detalhadas sobre como criar URLs para rotas personalizadas.
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.
Neste URL, o origin é omitido. Quando origin é omitido, o caminho usa como padrão o local de partida mais relevante, como a localização do dispositivo, se disponível.
Se não houver, o mapa resultante vai fornecer um formulário para que o usuário insira a origem.
O valor de origem e destino pode ser um nome de lugar, um 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 modo de viagem 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 lugar usando o parâmetro origin_place_id e destination_place_id. Usar um ID de lugar é a melhor garantia de que você vai vincular ao lugar certo.
Como recuperar IDs de lugar sem custo financeiro
Para recuperar IDs de lugar de forma programática, use a funcionalidade API Places: Pesquisa de texto(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).
Solicitação da Pesquisa de texto da API Places(somente ID):
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'Resposta da Pesquisa de texto da API Places(somente ID):
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}Os IDs de lugar 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)
Cenário 3: fornecer um trajeto passo a passo
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
orientada por voz se a localização atual do usuário(localização do dispositivo) estiver disponível e
for usada como origem (fornecida explicitamente ou usada implicitamente quando o parâmetro de origem
é omitido). Caso contrário, uma prévia do trajeto será exibida.
A navegação guiada é iniciada quando dir_action=navigate é definido e:
- A origem é especificada e está próxima da localização atual do usuário
- A origem é omitida e a localização atual do usuário está disponível
A visualização do trajeto é iniciada quando:
dir_action=navigatenão está definidodir_action=navigateestá definido e a origem é especificada, mas não está perto da localização atual do usuário.dir_action=navigateestá definido e a origem é omitida, e a localização 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 na Web, e/ou entre todos os destinos. Nesses casos, esse parâmetro será ignorado.
 |
 |
Conclusão
Ao construir corretamente os URLs do Maps, você garante que os usuários recebam as informações certas de maneira 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 for fornecer navegação imediata, inclua o parâmetro dir_action=navigate para acionar a navegação guiada. A navegação vai começar do 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: usar os URLs pré-formatados fornecidos pela API Places ou criar manualmente URLs do Maps no seu aplicativo. Cada abordagem tem um conjunto de vantagens e desvantagens.
API Places:
Os campos
googleMapsUriegoogleMapsLinksna resposta de detalhes do lugar fornecem URLs prontos para uso. Isso reduz o tempo de desenvolvimento e minimiza o risco de erros na formatação de URL.Oferece menos controle sobre a configuração de rotas. Embora o
googleMapsLinksofereça rotas básicas, ele não é compatível com waypoints ou personalização avançada. Além disso, é relativamente menos simples acionar a navegação ponto a ponto diretamente.
URLs do Maps:
Oferece mais flexibilidade e controle. Os desenvolvedores podem criar URLs para mostrar detalhes de lugares e configurar vários aspectos de rotas, incluindo a adição de pontos de referência, a especificação de modos de viagem e o início da navegação curva a curva.
Exige um entendimento mais profundo dos parâmetros e da estrutura de URL. A construção manual aumenta o potencial de erros se não for feita com cuidado.
Melhorar os URLs do Maps com parâmetros UTM
Para ajudar o Google a entender melhor como os desenvolvedores estão integrando URLs do Maps e garantir a performance ideal, recomendamos que você inclua parâmetros de rastreamento UTM na construçã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 URLs do Maps.
Para o parâmetro utm_source, use o nome do seu aplicativo. O parâmetro
utm_campaign precisa refletir a ação pretendida do usuário, como "location_sharing", "place_details_search" ou "directions_request".
Por exemplo, um URL com parâmetros UTM pode ter esta aparência:
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 para melhoria, resolver problemas com mais eficiência e, por fim, oferecer uma experiência melhor para todos os usuários.
Próximas etapas
Leitura adicional sugerida:
Colaboradores
Principais autores:
Teresa Qin | Engenheira de soluções da Plataforma Google Maps