Esquema de URL do Google Maps para iOS

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

Você pode usar o esquema de URL do Google Maps para abrir o app Google Maps para iOS e fazer pesquisas, receber solicitações de direção e mostrar visualizações de mapa. Quando você inicia o Google Maps, o identificador do pacote é enviado automaticamente como parte da solicitação.

Você não precisa de uma chave da API Google para usar o esquema de URL do Google Maps.

Links universais e Google Maps

O Google Maps para iOS oferece suporte a links universais em dispositivos com o iOS 9 ou mais recente.

Se o URL corresponder à expressão regular abaixo e o dispositivo estiver executando o iOS 9 ou mais recente, use o método openURL: diretamente.

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

Por exemplo,

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

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

Visão geral

Um esquema de URL permite iniciar um aplicativo iOS nativo de outro app iOS ou de um aplicativo da Web. É possível definir opções no URL que serão transmitidas para o aplicativo iniciado. O app Google Maps para iOS oferece suporte aos 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, a pé, bicicleta e transporte público.
  • Adicione a navegação ao app.
  • No iOS 8, emita um callback quando o app for concluído usando comgooglemaps-x-callback://. Os callbacks costumam ser usados para retornar um usuário ao app que abriu o Google Maps para iOS originalmente. 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 para iOS usando um URL derivado do site do Google Maps para computador. Isso significa que você pode oferecer aos usuários uma experiência nativa para dispositivos móveis em vez de simplesmente carregar o site do Google Maps.

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

Como iniciar o app Google Maps para iOS e executar 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 deste formato:

comgooglemaps://?parameters

ou

comgooglemaps-x-callback://?parameters

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

Como verificar a disponibilidade do app Google Maps no dispositivo

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

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

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

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

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://");
}

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 vai abrir o app Google Maps para iOS.

• center: é o ponto central da visualização do mapa. Formatado como uma string de latitude,longitude separada por vírgulas.
• mapmode: define o tipo de mapa mostrado. 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 limpas.
• zoom: especifica o nível de zoom do mapa.

Este URL de exemplo mostra o mapa centralizado em Nova York com zoom 14 e a visualização de tráfego ativada:

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

Confira outros exemplos:

comgooglemaps://?center=37.788463,-122.392545&zoom=12

comgooglemaps://?center=46.414382,10.013988&mapmode=streetview

Pesquisar

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 mostrar um mapa, a Pesquisa oferece suporte ao parâmetro q.

• q: a string de consulta da pesquisa.

Este é um exemplo de URL para pesquisar "Pizza" no local especificado:

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

Confira 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

Mostrar 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 trajeto. 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 será selecionado. Se o valor for deixado em branco, o local atual do usuário será usado.
• daddr: define o ponto final das pesquisas de trajeto. Tem o mesmo formato e comportamento de saddr.
• directionsmode: modo de transporte. Pode ser definido como: driving, transit, bicycling ou walking.

O URL de exemplo mostra as rotas de transporte público entre o Google NYC 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

Confira 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 adere à especificação x-callback-url. Quando você chama o app Google Maps para iOS com esse esquema, ele mostra um botão na parte de cima da tela. Tocar nesse botão vai emitir um callback para um URL que você especificou.

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

comgooglemaps-x-callback://?parameters

Parâmetros

O esquema de URL x-callback aceita os mesmos parâmetros do esquema de URL comgooglemaps://, com os seguintes parâmetros adicionais. 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 a operação for concluída. Muitas vezes, esse é um esquema de URL para seu próprio app, permitindo que os usuários retornem ao aplicativo original.

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

1. Verifique se o app 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 vai abrir o app Google Maps para iOS e mostrar um mapa centralizado em Nova York. O app também vai mostrar um botão com o rótulo "SourceApp". Quando o botão "SourceApp" é clicado, o app Google Maps para iOS emite um callback 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 oferece suporte ao esquema de URL x-callback. Seu app pode verificar se o esquema de URL está disponível com o seguinte código:

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

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

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

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

Como 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 no 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 direções e, em seguida, retornar ao app quando o usuário estiver pronto. O código vai fazer o seguinte:

1. Verifique se o esquema de URL comgooglemaps-x-callback:// está disponível.
2. Abra o app Google Maps para iOS e peça direções para o Aeroporto JFK, em Nova York. Deixe o endereço de partida em branco para solicitar direções do local atual do usuário.
3. Adicione um botão com a etiqueta "AirApp" ao app 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".

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.")
}

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.");
}

Como iniciar o app Google Maps para iOS usando um URL do Google Maps para computadores

Se o app tiver acesso a um URL do Google Maps que já existe, como em uma página da Web ou em um banco de dados, use 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 adere à especificação x-callback-url.

Formatos de URL do Google Maps compatíveis

O esquema comgooglemapsurl:// oferece suporte a URLs que correspondem a esta expressão regular, em que {TLD} se refere 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 oferece suporte ao esquema de URL:

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

[[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 direções 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 mostra um mapa com direções para a Tokyo Tower, conforme especificado no URL original do Google Maps (acima). O app também vai mostrar um botão com o rótulo "SourceApp". Quando o botão "SourceApp" é clicado, o app Google Maps para iOS emitirá um callback 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