Intents Google Maps pour Android

L'application Google Maps pour Android expose plusieurs intents que vous pouvez utiliser pour lancer Google Maps en mode affichage, recherche, navigation ou Street View. Pour intégrer une carte à votre application, consultez le guide de démarrage rapide avec le SDK Maps pour Android.

Pour les plates-formes Android Automotive OS (AAOS), il existe des considérations spécifiques et des intents supplémentaires. Pour en savoir plus, consultez la documentation sur les intents Google Maps pour Android Automotive.

Présentation

Les intents vous permettent de démarrer une activité dans une autre application en décrivant une action que vous souhaitez effectuer (comme "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 lancer l'application Google Maps et d'effectuer l'une des quatre actions suivantes :

1. Afficher une carte à un emplacement et avec un niveau de zoom donnés.
2. Recherchez des lieux ou des adresses, et affichez-les sur une carte.
3. Demandez un itinéraire d'un lieu à un autre. Les itinéraires peuvent être renvoyés pour trois modes de transport : voiture, marche et 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, consultez Intents et filtres d'intent et Intents courants.

Demandes 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 : toutes les intentions Google Maps sont appelées en tant qu'action View : ACTION_VIEW.
• URI : les intents Google Maps utilisent des URI codés en URL qui spécifient une action sélectionnée, ainsi que des données permettant d'effectuer cette action.

• Package : l'appel de 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 pouvant gérer Intent. Si plusieurs applications sont disponibles, il est possible que l'utilisateur soit invité à choisir celle qu'il souhaite utiliser.

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

// 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);

// 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 parvient pas à identifier une application capable de répondre à l'intention, votre application risque de planter. Pour cette raison, vérifiez d'abord qu'une application de réception est installée avant de présenter l'une de ces intentions à 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, cela signifie qu'au moins une application peut gérer l'intention et qu'il est possible d'appeler startActivity() sans risque. Si le résultat est null, n'utilisez pas l'intention et, si possible, désactivez la fonctionnalité qui l'appelle.

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

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

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

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

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 intents Google Maps doivent être encodées en URI. Par exemple, la chaîne 1st & Pike, Seattle doit devenir 1st%20%26%20Pike%2C%20Seattle. Les espaces dans la chaîne peuvent être encodés avec %20 ou remplacés par le signe plus (+).

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

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

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

Afficher une carte

Utilisez l'intention geo: pour afficher une carte à un emplacement et avec un niveau de zoom donné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 vont de 0 (le monde entier) à 21 (bâtiments individuels). La limite supérieure peut varier en fonction des données cartographiques disponibles à l'emplacement sélectionné.

Exemples

// Creates an Intent that loads 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);

// Creates an Intent that loads 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)

Rechercher un lieu

Utilisez cet intent pour afficher les requêtes de recherche dans une fenêtre d'affichage spécifiée. Lorsque la requête ne renvoie qu'un seul résultat, vous pouvez utiliser cette intention pour afficher un repère à un endroit ou une adresse spécifiques, comme un point de repère, un établissement, une caractéristique 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 est compatible avec 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 un lieu sous la forme d'un nom ou d'une adresse. La chaîne doit être encodée au format URL. Par conséquent, une adresse telle que City Hall, New York, NY doit être convertie en City+Hall,New+York,NY.

• label vous permet de définir un libellé personnalisé pour un lieu identifié sur la carte. label doit être spécifié sous forme de chaîne.

Recherche par catégorie

Si vous transmettez un terme de recherche général, Google Maps tente de trouver un lieu proche de la latitude et de la longitude que vous avez spécifiées et qui correspond à vos critères. Si aucun emplacement n'est spécifié, Google Maps tente de trouver les fiches à proximité. Exemple :

// 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);

// 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)

Vous pouvez affiner davantage les résultats de recherche en spécifiant un paramètre de zoom en plus de la chaîne de requête. Dans l'exemple suivant, l'ajout d'un zoom de 10 tente de trouver des restaurants au niveau d'une ville plutôt qu'à proximité.

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);

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)

Recherche de lieux

Si vous recherchez une adresse spécifique, un repère s'affiche à cet emplacement.

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);

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 précédent définit une latitude et une longitude de 0,0, mais transmet une adresse en tant que chaîne de requête. Lorsque vous recherchez un lieu spécifique, la latitude et la longitude ne sont pas obligatoires. Toutefois, si vous ne connaissez pas l'adresse exacte, vous pouvez essayer de biaiser les résultats de la recherche en spécifiant une coordonnée. Par exemple, une recherche d'adresse pour "Main Street" peut renvoyer trop de résultats.

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

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

L'ajout d'une latitude et d'une longitude à l'URI d'intent biaise les résultats vers une zone spécifique :

// 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);

// 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 renvoie une seule valeur, vous pouvez transmettre un libellé facultatif. Les libellés doivent être spécifiés sous forme de chaîne et apparaître sous le repère de la carte. Notez que les libellés ne sont disponibles que lorsque q est spécifié comme coordonnée de latitude et de longitude.

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

// 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 de coordonnées de latitude et de longitude, vous pouvez afficher un repère à un emplacement connu à l'aide d'un Plus Code.

// 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 preceding examples.

// 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 preceding examples.

Lancer la navigation détaillée

Utilisez cet URI d'intent pour lancer la navigation Google Maps avec des instructions détaillées vers l'adresse ou les coordonnées spécifiées. Les itinéraires sont toujours fournis à 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 de terminaison pour les recherches de navigation. Cette valeur peut être des coordonnées de latitude et de 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 est sélectionné.

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

  • d pour la conduite (par défaut)
  • b pour le vélo
  • l pour les deux-roues
  • w pour la marche

• avoid définit les caractéristiques que l'itinéraire doit essayer d'éviter. avoid est facultatif et peut être défini sur une ou plusieurs des valeurs suivantes :

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

Exemples

Les requêtes Intent suivantes demandent une navigation guidée vers le zoo de Taronga, à Sydney en Australie :

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);

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)

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

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);

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.

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);

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 que les itinéraires incluent des routes et des chemins étroits non accessibles aux voitures. Le intent suivant renvoie un itinéraire en Inde.

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);

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'intention google.streetview pour lancer Google Street View. Google Street View offre des vues panoramiques à partir de lieux sélectionnés dans sa zone de couverture. Des photos sphériques ajouté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 cet emplacement. Comme les images Street View sont actualisées régulièrement et que les photos peuvent être prises à des positions légèrement différentes à chaque fois, il est possible que votre position soit ajustée à un autre panorama lorsque les images sont mises à jour.

• panoid est un ID de panorama spécifique. Google Maps utilise l'ID de panorama si un panoid et un cbll sont spécifiés. 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 la caméra. Le paramètre cbp accepte cinq valeurs séparées par une virgule, qui sont toutes facultatives. Les valeurs les plus importantes sont la deuxième, la quatrième et la cinquième, qui définissent respectivement le cap, 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 la direction de la boussole dans la vue de l'appareil photo 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 à
    1. Les valeurs transmises à l'orientation sont enveloppées. Autrement dit, 0°, 360° et 720° pointent toutes dans la même direction. Le cap est défini comme la deuxième des cinq valeurs séparées par une virgule.
  • 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 limité entre 0 et le niveau de zoom maximal pour le panorama actuel. Cela signifie que toute valeur en dehors de cette plage est définie sur l'extrémité la plus proche qui se trouve dans la plage. Par exemple, une valeur de -1 est définie sur 0. Le zoom est la quatrième des cinq valeurs séparées par une virgule.
  • tilt : spécifie l'angle d'inclinaison de la caméra vers le haut ou vers le bas. Les valeurs sont comprises entre -90 et 0 et entre 0 et 90, avec 90 à la verticale vers le bas, 0 centré sur l'horizon et -90 à la verticale vers le haut.

Exemples

Voici quelques exemples d'utilisation de l'intent Street View.

// 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 angles 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);

// 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 angles 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)