Esquema de URL do Google Maps para iOS

Nos dispositivos com iOS 9 e versões mais recentes, você pode usar links universais para iniciar o Google Maps quando tiver um URL do Maps.

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

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

Observação:com os URLs do Maps, você pode criar um URL universal em várias plataformas para iniciar o Google Maps e fazer pesquisas, consultar rotas, mostrar visualizações de mapa e imagens panorâmicas. É recomendável usar os URLs do Maps multiplataforma para abrir o Maps, já que esses URLs universais permitem lidar de forma mais ampla com as solicitações, independentemente da plataforma do usuário. Só use o esquema de URL do Maps específico para iOS nos recursos que só funcionam em uma plataforma para dispositivos móveis (por exemplo, navegação guiada).

Links universais e Google Maps

O Google Maps para iOS é compatível com links universais (link em inglês) em dispositivos com iOS 9 ou versões mais recentes.

Se o URL corresponder à expressão regular a seguir e o dispositivo estiver executando o iOS 9 ou versões mais recentes, use 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

Um esquema de URL permite iniciar um aplicativo iOS nativo de outro app iOS ou de um aplicativo da Web. Defina 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. Rotas podem ser retornadas para quatro modos 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://. Com frequência, callbacks são usados para retornar um usuário ao app que abriu originalmente o Google Maps para iOS. No iOS 9, o sistema fornece automaticamente um link "Voltar para" no canto esquerdo da barra de status.

• comgooglemapsurl://: este esquema permite iniciar o app Google Maps para iOS usando um URL derivado do site do Google Maps para computadores. Isso significa que você pode oferecer aos usuários uma experiência nativa em 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 usar 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.
  • Você pode 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

Observação :a partir do iOS 9, seu app precisa declarar os esquemas de URL que serão abertos. Consulte Como começar para mais informações.

Se quiser iniciar o app Google Maps para iOS e executar uma das funções compatíveis, use um esquema de URL no 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 app, verifique primeiro se o aplicativo está instalado. Seu app pode verificar se o esquema de URL 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, você pode usar 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 para iOS.

• center: é o ponto central da janela de visualização do mapa. Formatado como uma string separada por vírgulas de latitude,longitude.
• 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, com a visualização do trânsito ativada:

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

Alguns exemplos adicionais são:

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 exibir um mapa, a Pesquisa aceita o parâmetro q.

• q: a string de consulta para sua pesquisa.

Este URL de exemplo para pesquisas por "Pizza" perto do local especificado:

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

Alguns exemplos adicionais são:

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 as pesquisas de rotas. Pode ser uma latitude,uma longitude ou um endereço formatado para 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 vai ser usada.
• daddr: define o ponto final para as pesquisas de rotas. Tem o mesmo formato e comportamento que 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 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

Alguns exemplos adicionais são:

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

Especificar um URL de callback

Para especificar um URL de callback, use o esquema de URL comgooglemaps-x-callback://. Esse esquema está de acordo com a especificação x-callback-url. Quando você chamar o app Google Maps para iOS com esse esquema, ele exibirá um botão na parte superior da tela. Tocar nesse botão emitirá um retorno de chamada para um URL especificado.

As solicitações para 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 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 x-callback. Recomendamos usar nomes curtos.
• x-success: o URL a ser chamado quando concluído. Geralmente, esse é um esquema de URL para o próprio app, permitindo que os usuários retornem ao aplicativo original.

O app vai precisar registrar o próprio esquema de URL para 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 mostra um botão com o rótulo "SourceApp". Quando o usuário clica no botão "SourceApp", 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 é necessário verificar 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 URL que permite que os usuários retornem a um app depois de pesquisar uma sobremesa.

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

Como adicionar a navegação ao app

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

Observação: os botões adicionados pelo parâmetro x-source não vão aparecer na IU de navegação guiada.

Este snippet de código mostra como usar o esquema comgooglemaps-x-callback:// para solicitar rotas e retornar ao 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 partida em branco para solicitar rotas a partir do local atual do usuário.
3. Adicione um botão chamado "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.");
}

Como iniciar o app Google Maps para iOS de um URL do Google Maps para computador

Se o app tem acesso a um URL pré-existente do Google Maps, como em uma página da Web ou em um banco de dados, você pode 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 está de acordo com a especificação x-callback-url.

Formatos de URL compatíveis com o Google Maps

O esquema comgooglemapsurl:// é compatível com URLs que correspondem a essa 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 são 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 mostra um mapa com rotas até a Torre de Tóquio, conforme especificado no URL original do Google Maps (acima). O app também exibe um botão com o rótulo "SourceApp". Quando o usuário clica no botão "SourceApp", o app Google Maps para iOS emite 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