Direcionar os usuários aos detalhes e direções dos lugares do Google Maps com o URL do Maps ou a API Places

No mundo atual, os usuários esperam ter acesso fácil a informações sobre 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 listagem de imóveis, os usuários geralmente precisam conferir rapidamente os detalhes do local ou encontrar a melhor rota de A a B. Embora os desenvolvedores possam criar a própria experiência no app, aproveitar 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 tranquila do usuário. URLs incorretos comprometem essa experiência, direcionando os usuários para o local errado, exibindo uma visualização de mapa genérica em vez de detalhes específicos ou até mesmo resultando em um link quebrado. Isso frustra os usuários e impede que eles alcancem a meta. 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 de mapa geral 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 na longitude. No entanto, ele não fornece aos usuários detalhes sobre um lugar específico.

Como integrar seu aplicativo ao 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 precisam de uma chave. As soluções a seguir abordam diferentes cenários e casos de uso:

Como usar o campo googleMapsUri ou googleMapsLinks da API GMP Places(nova)

A API GMP Places(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 de detalhes do lugar, no Google Maps.

Exemplo:

Solicitação de detalhes do lugar

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 no exemplo acima. 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.

Como recuperar IDs de lugar sem custos financeiros

Para recuperar os IDs de lugar de forma programática, use a funcionalidade API Places: Pesquisa de texto(somente ID). Esse é um método sem custo para conseguir IDs de lugar. Saiba mais sobre o ID de local e a solicitação da API Place(nova).

Solicitação da API Places Text Search(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 sobre os ícones de ponto de interesse clicáveis(JavaScript, Android, iOS).

Implementação

Ao usar a API Places, os desenvolvedores podem 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.

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 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, que mostra um alfinete para um lugar específico ou realiza uma pesquisa geral e inicia um mapa para mostrar os resultados.

• A função "Rotas" inicia um app do Google Maps ou um navegador, se o app não estiver instalado, que mostra rotas entre pontos ou ativa a navegação passo a passo 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 sobre URLs do Google Maps para conferir mais funções e exemplos.

Aqui, vamos abordar duas funcionalidades principais dos URLs do Maps:

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

• Como fornecer direções usando URLs do Maps:esta seção explica como criar URLs que fornecem direções entre locais, incluindo direções com vários pontos de passagem e navegação passo a passo.

Como mostrar os detalhes do lugar 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.

Estrutura do URL de pesquisa:

https://www.google.com/maps/search/?api=1&parameters

Cenário 1: mostrar detalhes de um lugar com 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 de lugar 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 da 7-Eleven próximos dentro da viewport. 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, use um método mais preciso. Confira o próximo exemplo.

Cenário 3: mostrar detalhes de um lugar com 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 destes 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 tem o formato de 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 para o lugar 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, 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 lugar sem custo financeiro

Para recuperar os IDs de lugar de forma programática, use a funcionalidade API Places: Pesquisa de texto(somente ID). Esse é um método sem custo para conseguir IDs de lugares. Saiba mais sobre o ID de lugar e a solicitação da API Places(nova).

Solicitação da API Places Text Search(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 sobre os ícones de ponto de interesse 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, ADDRESS
• query=PLACE_NAME&query_place_id=PLACE_ID

Evite usar apenas coordenadas de latitude/longitude no parâmetro query quando o 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 do 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 listagens que correspondem aos seus critérios perto do local especificado. Se nenhum local for especificado, o Google Maps vai tentar encontrar listagens próximas ao seu local 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 direções 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. Ele oferece aos desenvolvedores mais controle sobre as direções fornecidas. A documentação Direções de URLs do Maps do Google (em inglês) oferece instruções detalhadas sobre como criar URLs para direções personalizadas.

Estrutura do URL das direções:

https://www.google.com/maps/dir/?api=1&parameters

Cenário 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 a partir do local atual do usuário.

Neste URL, o origin é omitido. Quando origin é omitido, o caminho padrão é o local de início mais relevante, como a localização do dispositivo, se disponível. Se não houver nenhuma, o mapa resultante vai fornecer um formulário para permitir 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.

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 transporte for especificado, o Google Maps vai mostrar um ou mais dos modos mais relevantes para a rota especificada 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 o lugar certo.

Como recuperar IDs de lugar sem custo financeiro

Para recuperar os IDs de lugar de forma programática, use a funcionalidade API Places: Pesquisa de texto(somente ID). Esse é um método sem custo para conseguir IDs de lugares. Saiba mais sobre o ID de lugar e a solicitação da API Places(nova).

Solicitação da API Places Text Search(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 sobre os ícones de ponto de interesse clicáveis(JavaScript, Android, iOS).

Cenário 3: fornecer navegação passo a passo

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate

A definição de dir_action=navigate no URL vai iniciar o Google Maps no modo de navegação passo a passo 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 for 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 ao local atual do usuário
• A origem é omitida e o local atual do usuário está disponível

A visualização do trajeto é iniciada quando:

• dir_action=navigate não está definido
• dir_action=navigate está definido e a origem é especificada, e a origem não está perto do local atual do usuário
• dir_action=navigate é definido, 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 Web e/ou entre todos os destinos. Nesses casos, esse parâmetro será ignorado.

Conclusão

Ao construir os URLs do Maps corretamente, você garante que os usuários recebam as informações corretas de forma rápida e eficiente.

• Sempre especifique o destino e use o ID de lugar sempre que possível para garantir a precisão.

• Quando o objetivo é oferecer navegação imediata, inclua o parâmetro dir_action=navigate para acionar a navegação guiada. A navegação vai começar no local atual do usuário se o local do dispositivo estiver disponível e for usado como a origem (definida explicitamente ou omitida)

Como escolher a abordagem certa para seu aplicativo

Você tem duas opções principais: aproveitar os URLs pré-formatados fornecidos pela API Places ou construir manualmente os URLs do Maps no seu aplicativo. Cada abordagem tem seu próprio conjunto de vantagens e desvantagens.

API Places:

• Os campos googleMapsUri e googleMapsLinks na 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 do URL.

• Oferece menos controle sobre a configuração de direções. Embora googleMapsLinks ofereça direções básicas, ele não oferece suporte a pontos de passagem ou personalização avançada. Além disso, é relativamente menos simples acionar a navegação passo a passo 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 direções, incluindo a adição de pontos de passagem, a especificação de modos de transporte e a ativação da navegação passo a passo.

• Requer um entendimento mais profundo dos parâmetros e da estrutura do URL. A construçã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 URLs do Maps e garantir a melhor performance, 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 de URLs do Maps.

Para o parâmetro utm_source, use o nome do 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 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 para melhoria, resolver problemas de forma mais eficaz e, em última análise, oferecer uma experiência melhor para todos os usuários.

Próximas etapas

Leitura adicional sugerida:

• URL do Maps
• IDs de lugar
• API Places: vincular ao Google Maps
• API Routes

Colaboradores

Autores principais:

Teresa Qin | Engenheira de soluções da Plataforma Google Maps