Esquema de URL do Google Maps para iOS

Em dispositivos com iOS 9 ou versões mais recentes, é possível usar os links universais para iniciar o Google Maps quando você tem um URL do Google Maps.

Você pode usar o esquema de URL do Google Maps para iniciar o app Google Maps para iOS e fazer pesquisas, receber solicitações de rotas e exibir visualizações de mapas. Ao iniciar o Google Maps, o identificador do pacote é enviado automaticamente como parte da solicitação.

Não é necessário ter uma chave de API do Google para usar o esquema de URL do Google Maps.

O Google Maps para iOS é compatível com links universais em dispositivos com iOS 9 ou versões posteriores.

Se o URL corresponder à seguinte expressão regular e o dispositivo estiver executando o iOS 9 ou posterior, considere usar o método openURL: diretamente.

(http(s?)://)?
((maps\.google\.{TLD}/)|
 ((www\.)?google\.{TLD}/maps/)|
 (goo.gl/maps/))
.*

Por exemplo:

Swift

UIApplication.shared.openURL(URL(string:"https://www.google.com/maps/@42.585444,13.007813,6z")!)

Objective-C

[[UIApplication sharedApplication] openURL:
   [NSURL URLWithString:@"https://www.google.com/maps/@42.585444,13.007813,6z"]];

Visão geral

Com um esquema de URL, é possível iniciar um aplicativo nativo do iOS em outro app da Web ou iOS. É possível definir opções no URL que será transmitido para o aplicativo iniciado. O app Google Maps para iOS é compatível com os seguintes esquemas de URL:

  • comgooglemaps:// e comgooglemaps-x-callback://: esses esquemas permitem iniciar o app Google Maps para iOS e realizar uma das várias ações:

    • Exibir um mapa em um local e nível de zoom especificados.
    • Procurar locais ou lugares e exibi-los em um mapa.
    • Solicitar rotas de um local para outro. As rotas podem ser retornadas para quatro meios de transporte: carro, caminhada, bicicleta e transporte público.
    • Adicionar navegação ao app.
    • Até o iOS 8, emita um callback quando o app for concluído, usando comgooglemaps-x-callback://. Muitas vezes, os callbacks são usados para retornar um usuário ao app que originalmente abriu o Google Maps para iOS. No iOS 9, o sistema fornece automaticamente um link "Voltar para" no canto esquerdo da barra de status.
  • comgooglemapsurl://: esse esquema permite iniciar o app Google Maps no iOS usando um URL derivado do site do Google Maps para computadores. Isso significa que é possível oferecer aos seus usuários uma experiência móvel nativa em vez de simplesmente carregar o site do Google Maps.

    • O URL original pode ser para maps.google.com, google.com/maps ou usar qualquer domínio de país de nível superior válido em vez de com. Também é possível transmitir goo.gl/maps URLs de redirecionamento.
    • É possível emitir um callback usando os parâmetros x-source e x-success com o esquema de URL comgooglemapsurl://.

Iniciar o app Google Maps para iOS e realizar uma função específica

Para iniciar o app Google Maps para iOS e, opcionalmente, executar uma das funções compatíveis, use um esquema de URL com o seguinte formato:

comgooglemaps://?parameters

ou

comgooglemaps-x-callback://?parameters

Os parâmetros são descritos em detalhes posteriormente neste documento.

Verificar a disponibilidade do app Google Maps no dispositivo

Antes de apresentar um desses URLs a um usuário no seu app, primeiro verifique se o aplicativo está instalado. Seu app pode verificar se o esquema de URLs está disponível com o seguinte código:

Swift

UIApplication.shared.canOpenURL(URL(string:"comgooglemaps://")!)

Objective-C

[[UIApplication sharedApplication] canOpenURL:
    [NSURL URLWithString:@"comgooglemaps://"]];

Por exemplo, para exibir um mapa do Central Park em Nova York, use o seguinte código:

Swift

if (UIApplication.shared.canOpenURL(URL(string:"comgooglemaps://")!)) {
  UIApplication.shared.openURL(URL(string:
    "comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic")!)
} else {
  print("Can't use comgooglemaps://");
}

Objective-C

if ([[UIApplication sharedApplication] canOpenURL:
     [NSURL URLWithString:@"comgooglemaps://"]]) {
  [[UIApplication sharedApplication] openURL:
   [NSURL URLWithString:@"comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic"]];
} else {
  NSLog(@"Can't use comgooglemaps://");
}

Exibir um mapa

Use o esquema de URL para exibir um mapa em uma localização e com o nível de zoom especificados. Você também pode sobrepor outras visualizações em cima de seu mapa ou exibir imagens do Street View.

Parâmetros

Todos os parâmetros a seguir são opcionais. Se nenhum parâmetro for definido, o esquema de URL iniciará o app Google Maps no iOS.

  • center: é o ponto central do mapa na janela de visualização. Formatado como uma string separada por vírgulas de latitude,longitude.
  • mapmode: define o tipo de mapa exibido. Pode ser definido como: standard ou streetview. Se não for especificado, as configurações atuais do aplicativo serão usadas.
  • views: ativa/desativa visualizações específicas. Pode ser definido como: satellite, traffic ou transit. Vários valores podem ser definidos usando um separador de vírgulas. Se o parâmetro for especificado sem valor, todas as visualizações serão apagadas.
  • zoom: especifica o nível de zoom do mapa.

Este URL de exemplo exibe o mapa centralizado em Nova York no zoom 14 com a visualização de trânsito ativada:

comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic

Mapa de tráfego de Nova York

Veja outros exemplos:

comgooglemaps://?center=37.788463,-122.392545&zoom=12
comgooglemaps://?center=46.414382,10.013988&mapmode=streetview

Use este esquema para exibir consultas de pesquisa em um local especificado da janela de visualização.

Parâmetros

Além dos parâmetros usados para exibir um mapa, a Pesquisa é compatível com o parâmetro q.

  • q: a string de consulta da sua pesquisa.

Este URL de exemplo para pesquisar "Pizza" ao redor do local especificado:

comgooglemaps://?q=Pizza&center=37.759748,-122.427135

Pizza ao redor

Veja outros exemplos:

comgooglemaps://?q=Steamers+Lane+Santa+Cruz,+CA&center=37.782652,-122.410126&views=satellite,traffic&zoom=15
comgooglemaps://?q=Google+Japan,+Minato,+Tokyo,+Japan&center=35.660888,139.73073&zoom=15&views=transit

Exibir rotas

Use este esquema para solicitar e exibir rotas entre duas localizações. Você também pode especificar o meio de transporte.

Parâmetros

  • saddr: define o ponto de partida para pesquisas de rotas. Ele pode ser uma latitude,longitude ou um endereço formatado por consulta. Se for uma string de consulta que retorna mais de um resultado, o primeiro resultado será selecionado. Se o valor for deixado em branco, a localização atual do usuário será usada.
  • daddr: define o ponto final para as pesquisas de rotas. Tem o mesmo formato e comportamento de saddr.
  • directionsmode: método de transporte. Pode ser definido como: driving, transit, bicycling ou walking.

O URL de exemplo exibe rotas de transporte público entre o Google Nova York e o aeroporto JFK:

comgooglemaps://?saddr=Google+Inc,+8th+Avenue,+New+York,+NY&daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York&directionsmode=transit

Rotas de transporte público

Veja outros exemplos:

comgooglemaps://?saddr=Google,+1600+Amphitheatre+Parkway,+Mountain+View,+CA+94043&daddr=Google+Inc,+345+Spear+Street,+San+Francisco,+CA&center=37.422185,-122.083898&zoom=10
comgooglemaps://?saddr=2025+Garcia+Ave,+Mountain+View,+CA,+USA&daddr=Google,+1600+Amphitheatre+Parkway,+Mountain+View,+CA,+United+States&center=37.423725,-122.0877&directionsmode=walking&zoom=17

Como especificar um URL de callback

Se você quiser especificar um URL de callback, use o esquema de URL comgooglemaps-x-callback://. Esse esquema segue a especificação x-callback-url. Quando você chama o app Google Maps para iOS com esse esquema, o app exibe um botão na parte superior da tela. Tocar nesse botão emitirá um retorno de chamada para um URL que você especificou.

As solicitações para o comgooglemaps-x-callback:// precisam ter o formato:

comgooglemaps-x-callback://?parameters

Parâmetros

O esquema de URL x-callback aceita os mesmos parâmetros que o esquema de URL comgooglemaps://, com os parâmetros adicionais a seguir. Os dois parâmetros são obrigatórios.

  • x-source: o nome do aplicativo que envia a solicitação de x-callback. Recomendamos usar nomes curtos.
  • x-success: o URL a ser chamado quando concluído. Muitas vezes, esse será um esquema de URL para o app, permitindo que os usuários retornem ao app original.

Seu app precisa registrar o próprio esquema de URL para que possa responder ao URL de callback.

  1. Verifique se o aplicativo registrou um esquema de URL que pode responder à solicitação de callback.
  2. Transmita o rótulo do botão de callback no parâmetro x-source.
  3. Transmita o URL de callback no parâmetro x-success.

O exemplo a seguir inicia o app Google Maps para iOS e mostra um mapa centralizado em Nova York. O app também exibirá um botão chamado "quoApp;SourceApp"". Quando o botão "SourceApp" for clicado, o app Google Maps para iOS emitirá um retorno de chamada para um esquema de URL fictício, sourceapp://?resume=true.

comgooglemaps-x-callback://?center=40.765819,-73.975866&zoom=14
   &x-success=sourceapp://?resume=true
   &x-source=SourceApp

Assim como no esquema de URL comgooglemaps://, primeiro verifique se o app Google Maps para iOS está disponível no dispositivo e é compatível com o esquema de URL x-callback. Seu app pode verificar se o esquema de URL está disponível com o seguinte código:

Swift

UIApplication.shared.canOpenURL(URL(string:"comgooglemaps-x-callback://")!)

Objective-C

[[UIApplication sharedApplication] canOpenURL:
   [NSURL URLWithString:@"comgooglemaps-x-callback://"]];

Este é um exemplo de um URL que permite que os usuários retornem a um app depois de pesquisar o sobremesa.

comgooglemaps-x-callback://?q=dessert&center=37.759748,-122.427135
   &x-success=sourceapp://?resume=true
   &x-source=Nom+Nom

Adicionar navegação ao app

Iniciar o app Google Maps para iOS com uma solicitação de rotas é uma maneira fácil de dar aos usuários acesso à navegação passo a passo pelo app. Você pode usar os esquemas de URL comgooglemaps:// ou comgooglemaps-x-callback://.

Este snippet de código mostra como usar o esquema comgooglemaps-x-callback:// para solicitar rotas e retornar ao seu app quando o usuário estiver pronto. O código fará o seguinte:

  1. Verifique se o esquema de URL comgooglemaps-x-callback:// está disponível.
  2. Inicie o app Google Maps para iOS e solicite rotas para o Aeroporto JFK na cidade de Nova York. Deixe o endereço de início em branco para solicitar rotas a partir da localização atual do usuário.
  3. Adicione um botão chamado "quot;AirApp"" ao aplicativo do Google Maps para iOS. O rótulo do botão é definido pelo parâmetro x-source.
  4. Chame o esquema de URL fictício, sourceapp://, quando os usuários clicarem no botão "Voltar".

Swift

let testURL = URL(string: "comgooglemaps-x-callback://")!
if UIApplication.shared.canOpenURL(testURL) {
  let directionsRequest = "comgooglemaps-x-callback://" +
    "?daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York" +
    "&x-success=sourceapp://?resume=true&x-source=AirApp"

  let directionsURL = URL(string: directionsRequest)!
  UIApplication.shared.openURL(directionsURL)
} else {
  NSLog("Can't use comgooglemaps-x-callback:// on this device.")
}

Objective-C

NSURL *testURL = [NSURL URLWithString:@"comgooglemaps-x-callback://"];
if ([[UIApplication sharedApplication] canOpenURL:testURL]) {
  NSString *directionsRequest = @"comgooglemaps-x-callback://" +
      @"?daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York" +
      @"&x-success=sourceapp://?resume=true&x-source=AirApp";
  NSURL *directionsURL = [NSURL URLWithString:directionsRequest];
  [[UIApplication sharedApplication] openURL:directionsURL];
} else {
  NSLog(@"Can't use comgooglemaps-x-callback:// on this device.");
}

Iniciar o app Google Maps para iOS com um URL do Maps para computadores

Caso seu app tenha acesso a um URL preexistente do Google Maps, como em uma página da Web ou em um banco de dados, você poderá usar esse esquema para abrir o URL no app Google Maps para iOS, oferecendo aos usuários a melhor experiência nativa.

  1. Substitua o esquema http:// ou https:// por comgooglemapsurl://.
  2. Se você quiser usar um callback, inclua os parâmetros x-source e x-success. Esse esquema segue a especificação x-callback-url.

Formatos de URL compatíveis do Google Maps

O esquema comgooglemapsurl:// é compatível com URLs que correspondem a essa expressão regular, em que {TLD} refere-se a qualquer domínio de país de nível superior válido. As quebras de linha foram adicionadas para maior clareza:

(http(s?)://)?
((maps\.google\.{TLD}/)|
 ((www\.)?google\.{TLD}/maps/)|
 (goo.gl/maps/))
.*

Verificar a disponibilidade do app Google Maps

Primeiro, verifique se o app Google Maps para iOS está disponível no dispositivo e é compatível com o esquema de URL:

Swift

UIApplication.shared.canOpenURL(URL(string:"comgooglemaps-x-callback://")!)

Objective-C

[[UIApplication sharedApplication] canOpenURL:
   [NSURL URLWithString:@"comgooglemapsurl://"]];

Exemplos

Exemplo de um URL genérico do Google Maps:

URL original do Google Maps:

https://www.google.com/maps/preview/@42.585444,13.007813,6z

Uso do esquema de URL:

comgooglemapsurl://www.google.com/maps/preview/@42.585444,13.007813,6z

Exemplo de um URL genérico do Google Maps:

URL original do Google Maps:

https://maps.google.com/?q=@37.3161,-122.1836

Uso do esquema de URL:

comgooglemapsurl://maps.google.com/?q=@37.3161,-122.1836

Exemplo de solicitação de rotas para a Torre de Tóquio com x-callback:

URL original do Google Maps:

http://maps.google.com/maps?f=d&daddr=Tokyo+Tower,+Tokyo,+Japan&sll=35.6586,139.7454&sspn=0.2,0.1&nav=1

O exemplo a seguir inicia o app Google Maps para iOS e exibe um mapa com rotas para a Torre de Tóquio, conforme especificado no URL original do Google Maps (acima). O app também exibirá um botão com o rótulo "SourceApp" Quando o botão "SourceApp" for clicado, o app Google Maps para iOS emitirá um retorno de chamada para um esquema de URL fictício, sourceapp://?resume=true.

comgooglemapsurl://maps.google.com/maps?f=d&daddr=Tokyo+Tower,+Tokyo,+Japan&sll=35.6586,139.7454&sspn=0.2,0.1&nav=1
    &x-source=SourceApp
    &x-success=sourceapp://?resume=true