Esquema de URL do Google Maps

Use o esquema de URL do Google Maps para iniciar o aplicativo do Google Maps para iOS e executar pesquisas, obter solicitações de rotas e exibir visualizações de mapas. Quando você inicia o Google Maps, o identificador de pacote é enviado automaticamente como parte da solicitação.

O uso do esquema de URL do Google Maps não exige uma chave de API do Google.

Visão geral

Um esquema de URL permite iniciar um aplicativo iOS nativo de outro aplicativo iOS ou de um aplicativo web. Essas opções podem ser definidas no URL passado ao aplicativo iniciado. O aplicativo do Google Maps para iOS permite os seguintes esquemas de URL:

• comgooglemaps:// e comgooglemaps-x-callback:// - esses esquemas permitem iniciar o aplicativo do Google Maps para iOS e executar uma dentre várias ações:

  • Exibir um mapa em uma localização e com o nível de zoom especificados.
  • Pesquisar localizações e locais e exibi-los em um mapa.
  • Solicitar rotas entre uma localização e outra. As rotas são retornadas para quatro modos de transporte: condução, caminhada, bicicleta e transporte público.
  • Adicionar navegação ao aplicativo.
  • Até o iOS 8, emitir um retorno de chamada na conclusão do aplicativo usando comgooglemaps-x-callback://. Os retornos de chamada são usados com frequência para retornar um usuário ao aplicativo que iniciou originalmente o Google Maps para iOS. Observe que, no iOS 9, o sistema fornece automaticamente um link "Back to" no canto inferior esquerdo da barra de status.

• comgooglemapsurl:// - esse esquema permite iniciar o aplicativo do Google Maps para iOS usando um URL derivado do site do Google Maps para desktops. Isso significa que é possível oferecer aos usuários uma experiência móvel nativa em vez de simplesmente carregar o site do Google Maps.

  • O URL original pode ser o URL de maps.google.com, de google.com/maps ou usando qualquer domínio de nível superior do país, em vez de com. Também é possível passar URLs de redirecionamento goo.gl/maps.
  • Você pode emitir um retorno de chamada usando os parâmetros x-source e x-success com o esquema de URL comgooglemapsurl://.

Iniciar o aplicativo do Google Maps para iOS e executar uma função específica

Observação: A partir do iOS 9, o aplicativo deve declarar os esquemas de URL que abrirá. Consulte Primeiros passos para obter mais informações.

Para iniciar o aplicativo do Google Maps para iOS e, opcionalmente, 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 aplicativo do Google Maps no dispositivo

Antes de apresentar um desses URLs a um usuário no aplicativo, verifique antes se o aplicativo está instalado. O aplicativo pode verificar a disponibilidade do esquema de URL 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. Também é possível sobrepor outras visualizações sobre o mapa ou exibir imagens do Street View.

Parâmetros

Todos os parâmetros a seguir são opcionais. Se nenhum parâmetro é definido, o esquema de URL simplesmente inicia o aplicativo do Google Maps para iOS.

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

Veja a seguir um exemplo de URL, que exibe o mapa centralizado em Nova York com zoom 14 e com a visualização de trânsito ativada:

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

Veja a seguir alguns exemplos adicionais:

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

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

Pesquisar

Use esse esquema para exibir consultas de pesquisa em uma localização de porta de visualização especificada.

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 a pesquisa.

Veja a seguir um exemplo de URL para pesquisar "Pizza" perto da localização especificada:

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

Veja a seguir alguns exemplos adicionais:

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. Também é possível especificar o modo de transporte.

Parâmetros

• saddr: Define o ponto de partida para as pesquisas de rotas. Esse ponto pode ser uma latitude, uma longitude ou um endereço formatado para consulta. Se ele for uma string de consulta que retorna mais de um resultado, o primeiro resultado será selecionado. Se o valor está em branco, a localização atual do usuário é usada.
• daddr: Define o ponto de chegada 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.

Veja a seguir um exemplo de URL para exibir rotas de transporte público entre a 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

Veja a seguir alguns exemplos adicionais:

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 retorno de chamada

Para especificar um URL de retorno de chamada, é necessário usar o esquema de URL comgooglemaps-x-callback://. Esse esquema é compatível com a [especificação x-callback-url]. Quando o aplicativo do Google Maps para iOS é chamado com esse esquema, o aplicativo exibe um botão na parte superior da tela. O toque nesse botão emite um retorno de chamada para o URL especificado.

As solicitações para comgooglemaps-x-callback:// devem 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 x-callback. Recomendamos usar nomes curtos.
• x-success — o URL a ser chamado na conclusão. Frequentemente, é um esquema de URL para o próprio aplicativo, permitindo que os usuários retornem ao aplicativo original.

Observe que o aplicativo precisa registrar o próprio esquema de URL para poder responder ao URL de retorno de chamada.

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

O exemplo a seguir inicia o aplicativo do Google Maps para iOS e exibe um mapa centralizado em Nova York. O aplicativo também exibe um botão com o rótulo "SourceApp". Quando o botão "SourceApp" é clicado, o aplicativo do Google Maps para iOS emite 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

Da mesma forma que no esquema de URL comgooglemaps://, é necessário antes verificar se o aplicativo do Google Maps para iOS está disponível no dispositivo e permite o esquema de URL x-callback. O aplicativo pode verificar a disponibilidade do esquema de URL com o seguinte código:

Swift

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

Objective-C

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

Veja a seguir um exemplo de URL que permite aos usuários retornar ao aplicativo após pesquisar uma sobremesa.

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

Adicionar navegação ao aplicativo

A inicialização de um aplicativo do Google Maps para iOS com uma solicitação de rotas é uma forma fácil de oferecer aos usuários acesso à navegação curva a curva no aplicativo. É possível usar os esquemas de URL comgooglemaps:// ou comgooglemaps-x-callback://.

Observação: Os botões adicionados pelo parâmetro x-source não são exibidos na IU de navegação curva a curva.

O fragmento de código abaixo mostra como usar o esquema comgooglemaps-x-callback:// para solicitar rotas e retornar ao aplicativo quando o usuário estiver pronto. O código faz o seguinte:

1. Verifica a disponibilidade do esquema de URL comgooglemaps-x-callback://.
2. Inicia o aplicativo do Google Maps para iOS e solicita rotas para o aeroporto JFK na cidade de Nova York. Deixe o endereço de partida em branco para solicitar rotas a partir da localização atual do usuário.
3. Adiciona um botão com o rótulo "AirApp" ao aplicativo do Google Maps para iOS. O rótulo do botão é definido pelo parâmetro x-source.
4. Chama o esquema de URL fictício sourceapp://, quando o usuário clica no botão "Back".

O código é mostrado a seguir.

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 aplicativo do Google Maps para iOS em um URL do Google Maps para desktop

Se o aplicativo tem acesso a um URL existente do Google Maps, como em uma página ou em um banco de dados, use o esquema abaixo para abrir o URL no aplicativo do Google Maps para iOS, oferecendo dessa forma a melhor experiência nativa aos usuários.

1. Substitua o esquema de http:// ou https:// por comgooglemapsurl://.
2. Para usar um retorno de chamada, inclua os parâmetros x-source e x-success. Esse esquema é compatível com a [especificação x-callback-url].

Formatos permitidos de URL do Google Maps

O esquema comgooglemapsurl:// permite URLs que correspondem à expressão regular a seguir, onde {TLD} é qualquer domínio de nível superior de país válido. O texto foi dividido em várias linhas para maior clareza:

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

Verificar a disponibilidade do aplicativo do Google Maps

Verifique antes se o aplicativo do Google Maps para iOS está disponível no dispositivo e permite 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 Tokyo Tower 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 aplicativo do Google Maps para iOS e exibe um mapa com rotas para a Tokyo Tower, como especificado no URL original do Google Maps (acima). O aplicativo também exibe um botão com o rótulo "SourceApp". Quando o botão "SourceApp" é clicado, o aplicativo do Google Maps para iOS emite 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