Intents Google Maps pour Android

L'application Google Maps pour Android présente plusieurs intents que vous pouvez utiliser pour lancer Google Maps en mode affichage, recherche, navigation ou Street View. Si vous souhaitez intégrer une carte à votre application, consultez le Guide de démarrage de l'API Google Maps Android.

Présentation

Les intents vous permettent de démarrer une activité dans une autre application en décrivant l'action simple que vous souhaitez effectuer (par exemple, "afficher une carte" ou "afficher l'itinéraire vers l'aéroport") dans un objet Intent. L'application Google Maps pour Android accepte plusieurs intents différents, ce qui vous permet de la lancer et d'effectuer l'une des quatre actions suivantes:

  1. Afficher une carte à un point géographique et avec un niveau de zoom donnés
  2. Recherchez des lieux ou des lieux, et affichez-les sur une carte.
  3. Demandez un itinéraire d'un lieu à un autre. Un itinéraire peut être renvoyé pour trois modes de transport: en voiture, à pied ou à vélo.
  4. Affichez des images panoramiques dans Google Street View.

Cette page décrit les intents que vous pouvez utiliser avec l'application Google Maps pour Android. Pour en savoir plus sur les intents et les filtres d'intents ou sur les intents communs à la plate-forme Android, consultez la documentation destinée aux développeurs Android.

Requêtes d'intent

Pour lancer Google Maps avec un intent, vous devez d'abord créer un objet Intent en spécifiant son action, son URI et son package.

  • Action: tous les intents Google Maps sont appelés en tant qu'action d'affichage (ACTION_VIEW).
  • URI: les intents Google Maps utilisent des URL encodées qui spécifient l'action souhaitée, ainsi que certaines données avec lesquelles effectuer l'action.
  • Package: appeler setPackage("com.google.android.apps.maps") garantit que l'application Google Maps pour Android gère l'intent. Si le package n'est pas défini, le système détermine les applications qui peuvent gérer le Intent. Si plusieurs applications sont disponibles, l'utilisateur peut être invité à choisir celle qu'il souhaite utiliser.

Après avoir créé le Intent, vous pouvez demander au système de lancer l'application associée de plusieurs manières. Une méthode courante consiste à transmettre le Intent à la méthode startActivity(). Le système lance l'application nécessaire (dans ce cas, Google Maps) et lance l'élément Activity correspondant.

Java

// Create a Uri from an intent string. Use the result to create an Intent.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");

// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");

// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

Kotlin

// Create a Uri from an intent string. Use the result to create an Intent.
val gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988")

// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps")

// Attempt to start an activity that can handle the Intent
startActivity(mapIntent)

Si le système ne peut pas identifier une application capable de répondre à l'intent, votre application risque de planter. C'est pourquoi vous devez d'abord vérifier qu'une application réceptrice est installée avant de présenter l'un de ces intents à un utilisateur.

Pour vérifier qu'une application est disponible pour recevoir l'intent, appelez resolveActivity() sur votre objet Intent. Si le résultat n'est pas nul, au moins une application peut gérer l'intent et vous pouvez appeler startActivity() en toute sécurité. Si le résultat est null, vous ne devez pas utiliser l'intent et, si possible, désactiver la fonctionnalité qui l'appelle.

Java

if (mapIntent.resolveActivity(getPackageManager()) != null) {
  ...
}

Kotlin

mapIntent.resolveActivity(packageManager)?.let {
  ...
}

Par exemple, pour afficher une carte de San Francisco, vous pouvez utiliser le code suivant :

Java

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
  startActivity(mapIntent);
}

Kotlin

val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
mapIntent.resolveActivity(packageManager)?.let {
  startActivity(mapIntent)
}

Chaînes de requête encodées au format URL

Toutes les chaînes transmises aux intentions Google Maps doivent être encodées sous forme d'URI. Par exemple, la chaîne "1st & Pike, Seattle" doit devenir 1st%20%26%20Pike%2C%20Seattle. Dans la chaîne, les espaces peuvent être encodés avec %20 ou remplacés par le signe plus (+).

Vous pouvez utiliser la méthode parse() android.net.Uri pour encoder vos chaînes. Exemple :

Java

Uri gmmIntentUri =
  Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"));

Kotlin

val gmmIntentUri =
  Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"))

Afficher une carte

Utilisez l'intent geo: pour afficher une carte à un point géographique et à un niveau de zoom spécifiés.

geo:latitude,longitude?z=zoom

Paramètres

  • latitude et longitude définissent le point central de la carte.
  • z définit éventuellement le niveau de zoom initial de la carte. Les valeurs acceptées sont comprises entre 0 (le monde entier) et 21 (bâtiments individuels). La limite supérieure peut varier en fonction des données cartographiques disponibles pour le lieu sélectionné.

Exemples

Java

// Creates an Intent that will load a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Creates an Intent that will load a map of San Francisco
val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Recherche d'un lieu

Utilisez cette intention pour afficher des requêtes de recherche au sein de la fenêtre d'affichage spécifiée. Lorsque la requête ne comporte qu'un seul résultat, vous pouvez utiliser cet intent pour afficher un repère à un lieu ou à une adresse spécifique, comme un point de repère, un établissement, un élément géographique ou une ville.

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address
geo:0,0?q=latitude,longitude(label)

Paramètres

En plus des paramètres utilisés pour afficher une carte, la recherche Google accepte les paramètres suivants:

  • q définit le ou les lieux à mettre en évidence sur la carte. Le paramètre q est obligatoire pour toutes les requêtes de recherche. Il accepte les lieux en tant que nom ou adresse de lieu. La chaîne doit être encodée en URL afin qu'une adresse telle que "City Hall, New York, NY" soit convertie en City+Hall,New+York,NY.

  • label vous permet de définir une étiquette personnalisée pour un lieu identifié sur la carte. label doit être spécifié en tant que chaîne.

Si vous indiquez un terme de recherche générique, Google Maps tente de trouver un lieu qui correspond à vos critères à proximité des coordonnées de latitude et longitude que vous avez spécifiées. Si aucun lieu n'est spécifié, Google Maps tente de trouver des fiches à proximité. Exemple :

Java

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

// Search for restaurants in San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Search for restaurants nearby
val gmmIntentUri = Uri.parse("geo:0,0?q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

// Search for restaurants in San Francisco
val gmmIntentUri =
  Uri.parse("geo:37.7749,-122.4194?q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Recherche de restaurants à San Francisco

Vous pouvez pondérer davantage les résultats de la recherche en spécifiant un paramètre de zoom avec la chaîne de requête. Dans l'exemple ci-dessous, l'ajout d'un zoom de 10 tente de trouver des restaurants au niveau de la ville plutôt que des environs.

Java

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
  Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

La recherche d'une adresse spécifique affiche un repère sur ce lieu.

Java

Uri gmmIntentUri = Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
  Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

L'exemple ci-dessus définit une latitude/longitude de 0,0, mais transmet une adresse en tant que chaîne de requête. Lorsque vous recherchez un lieu très spécifique, la latitude et la longitude ne sont pas requises. Toutefois, si vous ne connaissez pas l'adresse exacte, vous pouvez essayer de fausser les résultats de la recherche en spécifiant des coordonnées. Par exemple, une recherche d'adresse sur "Main Street" renverra un trop grand nombre de résultats.

Java

// Searching for 'Main Street' will return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

Kotlin

// Searching for 'Main Street' will return too many results
val gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street")

L'ajout d'une latitude/longitude à l'URI d'intent orientera les résultats vers une zone particulière:

Java

// Searches for 'Main Street' near San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Searches for 'Main Street' near San Francisco
val gmmIntentUri =
  Uri.parse("geo:37.7749,-122.4194?q=101+main+street")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Lorsque vous savez que votre recherche renverra une valeur unique, vous pouvez transmettre un libellé facultatif. Les libellés doivent être spécifiés en tant que chaîne et s'affichent sous le repère sur la carte. Notez que les libellés ne sont disponibles que lorsque q est spécifié en tant que coordonnée de latitude/longitude.

Java

// Display a label at the location of Google's Sydney office
Uri gmmIntentUri = Uri.parse("geo:0,0?q=Google+Sydney@-33.8666,151.1957");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Display a label at the location of Google's Sydney office
val gmmIntentUri =
  Uri.parse("geo:0,0?q=-33.8666,151.1957(Google+Sydney)")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Au lieu d'une adresse postale ou d'une latitude/longitude, vous pouvez afficher un repère à un lieu connu à l'aide d'un plus code.

Java

// Display the location of Google, San Francisco using a global plus code.
Uri gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX");
// Equivalently, define the same location using a local plus code
gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco");
// Construct and use the Intent as in the examples above

Kotlin

// Display the location of Google, San Francisco using a global plus code.
var gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX")
// Equivalently, define the same location using a local plus code
gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco")
// Construct and use the Intent as in the examples above

Lancement de la navigation détaillée

Utilisez cet intent pour lancer la navigation Google Maps avec des instructions de navigation détaillées vers l'adresse ou les coordonnées spécifiées. L'itinéraire est toujours fourni à partir de la position actuelle de l'utilisateur.

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude

Paramètres

  • q: définit le point d'arrivée des recherches de navigation. Cette valeur peut être une latitude, une longitude ou une adresse au format de requête. S'il s'agit d'une chaîne de requête qui renvoie plusieurs résultats, le premier résultat sera sélectionné.

  • mode définit le mode de transport. Le mode est facultatif et peut être défini sur l'une des valeurs suivantes:

    • d pour la conduite (par défaut)
    • b à vélo
    • l pour deux-roues
    • w pour la marche
  • avoid définit les caractéristiques que l'itinéraire doit essayer d'éviter. L'option "Éviter" est facultative et peut être définie sur une ou plusieurs des valeurs suivantes:

    • t pour les péages
    • h pour les autoroutes
    • f pour les ferries

Exemples

Le Intent ci-dessous demandera une navigation détaillée vers le zoo de Taronga, à Sydney, en Australie:

Java

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
  Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Itinéraire vers le zoo de Taronga

Si vous préférez ne pas payer de péages ni prendre le ferry, vous pouvez demander un itinéraire qui tente d'éviter ces choses.

Java

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
  Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Si vous préférez faire un peu d'exercice, vous pouvez demander un itinéraire à vélo.

Java

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
  Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Si vous préférez prendre un deux-roues motorisé, vous pouvez demander à ce que l'itinéraire inclue des routes étroites et des sentiers inaccessibles aux voitures. Le intent ci-dessous renvoie un itinéraire en Inde.

Java

Uri gmmIntentUri = Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
  Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Afficher un panorama Street View

Utilisez l'intent google.streetview pour lancer Google Street View. Google Street View offre des vues panoramiques à partir de lieux désignés dans sa zone de couverture. Des photo-sphères importées par les utilisateurs et des collections spéciales Street View sont également disponibles.

google.streetview:cbll=latitude,longitude&cbp=0,bearing,0,zoom,tilt
google.streetview:panoid=id&cbp=0,bearing,0,zoom,tilt

Paramètres

Tous les URI google.streetview doivent inclure un paramètre cbll ou panoid.

  • cbll accepte une latitude et une longitude sous forme de valeurs séparées par une virgule (46.414382,10.013988). L'application affiche le panorama photographié le plus proche de ce lieu. Étant donné que les images Street View sont régulièrement actualisées et que les photos peuvent être prises à des positions légèrement différentes à chaque fois, il est possible que votre position affiche un panorama différent lorsque les images sont mises à jour.

  • panoid est un identifiant de panorama spécifique. Google Maps utilisera l'identifiant de panorama si panoid et cbll sont spécifiés à la fois. Les ID de panorama sont disponibles pour une application Android à partir de l'objet StreetViewPanoramaLocation.

  • cbp est un paramètre facultatif qui ajuste l'orientation initiale de l'appareil photo. Le paramètre cbp accepte cinq valeurs séparées par une virgule, toutes facultatives. Les valeurs les plus significatives sont la deuxième, la quatrième et la cinquième, qui définissent respectivement la direction, le zoom et l'inclinaison. Les première et troisième valeurs ne sont pas acceptées et doivent être définies sur 0.

    • bearing: indique l'orientation de la boussole de la caméra en degrés dans le sens des aiguilles d'une montre à partir du nord. Le nord géographique est à 0, l'est à 90, le sud à 180 et l'ouest à 270. Les valeurs transmises à la direction s'encapsulent. Autrement dit, les valeurs 0°, 360° et 720° pointent toutes dans la même direction. Le relèvement est défini comme la deuxième des cinq valeurs séparées par des virgules.
    • zoom: définit le niveau de zoom de la caméra. Le niveau de zoom par défaut est défini sur 0. Un zoom de 1 doublerait le grossissement. Le zoom est compris entre 0 et le niveau de zoom maximal pour le panorama actuel. Cela signifie que toute valeur en dehors de cette plage sera définie sur la valeur la plus proche dans la plage. Par exemple, une valeur de -1 sera définie sur 0. Le zoom est la quatrième des cinq valeurs séparées par une virgule.
    • tilt: spécifie l'angle, vers le haut ou vers le bas, de la caméra. La plage va de -90 à 0 à 90, 90 à la verticale vers le bas, 0 centré sur l'horizon et -90 à la verticale vers le haut.

Exemples

Vous trouverez ci-dessous quelques exemples d'utilisation de l'intention Street View.

Java

// Displays an image of the Swiss Alps
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia
Uri gmmIntentUri = Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter will angle the camera slightly up, and towards the east.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Displays an image of the Swiss Alps
val gmmIntentUri =
  Uri.parse("google.streetview:cbll=46.414382,10.013988")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia
val gmmIntentUri =
  Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter will angle the camera slightly up, and towards the east.
val gmmIntentUri =
  Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Les pyramides dans Street View