Vous êtes prêt !

Pour passer à l'étape de développement, accédez à notre documentation pour les développeurs.

Activer Google Maps Android API

Pour commencer, nous allons vous guider à travers la console Google Developers et effectuer deux ou trois petites choses :

  1. Créer ou choisir un projet
  2. Activer Google Maps Android API
  3. Créer les clés appropriées
Continuer

Appareil photo et vue

Dans Google Maps Android API, il est possible d'incliner et de faire pivoter les cartes avec des gestes simples, ce qui permet aux utilisateurs d'ajuster la carte avec une orientation plus parlante pour eux. À n'importe quel niveau de zoom, vous pouvez effectuer un panorama sur la carte ou modifier sa perspective avec une latence très faible grâce au format réduit des tuiles de carte vectorielles.

Échantillons de code

Le référentiel ApiDemos sur GitHub inclut un échantillon qui illustre les fonctionnalités de l'appareil photo :

Introduction

À l'instar de Google Maps sur le Web, Google Maps Android API effectue une représentation de la surface de la terre (sphère) sur l'écran de votre appareil (surface plane) en utilisant une projection de Mercator. Vers l'est et vers l'ouest, la carte est répétée à l'infini car la terre tourne sur elle-même. Vers le nord et le sud, la carte est limitée à environ 85 degrés nord et 85 degrés sud.

Remarque : Une projection de Mercator a une largeur finie sur le plan longitudinal, mais une hauteur infinie sur le plan latitudinal. Nous « coupons » l'image de la carte de base en utilisant la projection de Mercator à environ +/- 85 degrés pour rendre carrée la carte qui en résulte et ainsi simplifier la logique de sélection des tuiles.

Google Maps Android API vous permet de changer le point de vue de l'utilisateur de la carte en modifiant l'appareil photo de la carte.

Les modifications apportées à l'appareil photo ne modifieront pas les marqueurs, les superpositions ou tout autre élément graphique que vous avez ajouté, mais vous pouvez néanmoins modifier ces ajouts pour qu'ils s'intègrent mieux à la nouvelle vue.

Étant donné que vous pouvez écouter les gestes de l'utilisateur sur la carte, vous pouvez modifier la carte en réponse aux requêtes de l'utilisateur. Par exemple, la méthode de rappel OnMapClickListener.onMapClick() répond à un seul toucher sur la carte. Étant donné que la méthode reçoit la latitude et la longitude de l'emplacement du toucher, vous pouvez répondre en effectuant un panorama ou un zoom sur ce point. Des méthodes similaires sont disponibles pour répondre aux touchers sur la bulle d'un marqueur ou pour répondre à un geste de glissement sur un marqueur.

Vous pouvez également écouter les mouvements de l'appareil photo, afin que votre application reçoive une notification lorsque l'appareil photo commence à bouger, est en train de bouger ou arrête de bouger. Pour plus de détails, voir le guide Événements de changement de l'appareil photo.

Bâtiments en 3D sur la carte

De nombreuses villes, vues en gros plan, permettront d'afficher les bâtiments en 3D, comme sur l'image ci-dessous de Vancouver au Canada. Vous pouvez désactiver les bâtiments en 3D en appelant GoogleMap.setBuildingsEnabled(false).

A map of Vancouver, Canada

Position de l'appareil photo

La vue de la carte est modélisée comme un appareil photo orienté vers le bas sur une surface plane. La position de l'appareil photo (et par conséquent le rendu de la carte) est indiquée par les propriétés suivantes : position cible (latitude/longitude), zoom, orientation et inclinaison.

Point géographique cible

La cible de l'appareil photo est la position du centre de la carte, spécifiée en tant que coordonnées de latitude et longitude.

Zoom

Le niveau de zoom de l'appareil photo détermine l'échelle de la carte. Plus le niveau de zoom est élevé, plus on peut voir de détails sur la carte ; et inversement, plus le niveau de zoom est faible, plus la partie du monde affichée à l'écran est grande. À un niveau de zoom 0, l'échelle de la carte est telle que le monde entier a une largeur d'environ 256dp (pixels indépendants de la densité).

Augmenter le niveau de zoom de 1 double la largeur du monde à l'écran. Ainsi, à un niveau de zoom N, la largeur du monde est environ de 256 * 2N dp, par exemple, à un niveau de zoom de 2, le monde entier mesure environ 1024dp de large. Notez que le niveau de zoom doit être un nombre entier. La fourchette de niveaux de zoom autorisée par la carte dépend d'un certain nombre de facteurs, notamment le lieu, le type de carte et la taille de l'écran. La liste suivante indique le niveau approximatif de détail que vous pouvez vous attendre à voir à chaque niveau de zoom :

  • 1 : Monde
  • 5 : Masse continentale/continent
  • 10 : Ville
  • 15 : Rues
  • 20 : Immeubles

Les images suivantes montrent à quoi ressemblent les différents niveaux de zoom :

Screenshot of a map at a zoom level of 5
Carte au niveau de zoom 5.
Screenshot of a map at a zoom level of 15
Carte au niveau de zoom 15.
Screenshot of a map at zoom level 20
Carte au niveau de zoom 20.

Direction (orientation)

La direction de l'appareil photo est le cap vers lequel pointe une ligne verticale sur la carte, mesurée en degrés dans le sens horaire à partir du nord. Un conducteur tourne souvent sa carte routière pour l'aligner dans le sens de la route, tandis qu'un randonneur utilisant une carte et une boussole oriente généralement la carte afin qu'une ligne verticale pointe vers le nord. Maps API vous permet de modifier l'alignement ou l'orientation d'une carte. Par exemple, avec une direction de 90 degrés, l'orientation vers le haut de la carte pointe vers l'est.

Inclinaison (angle de vue)

L'inclinaison définit la position de l'appareil photo sur un arc directement au-dessus du point central de la carte et de la surface de la Terre, mesurée en degrés à partir du nadir (direction qui pointe directement sous l'appareil photo). Lorsque vous modifiez l'angle de vue, la carte apparaît en perspective, avec les caractéristiques lointaines semblant plus petites, et les plus proches semblant plus grandes. Les images suivantes illustrent ce principe.

Dans les images ci-dessous, l'angle de vue est de 0 degré. La première image correspond à un plan schématisé ; la position 1 correspond à la position de l'appareil photo et la position 2 à la position actuelle de la carte. La carte qui en résulte est présentée juste en dessous.

Screenshot of a map with a camera positioned at 0 degrees viewing angle, at a zoom level of 18.
Carte affichée avec l'angle de vue par défaut de l'appareil photo.
Diagram that shows the default position of the camera, directly over the map position, at an angle of 0 degrees.
Angle de vue par défaut de l'appareil photo.

Sur les images ci-dessous, l'angle de vue est de 45 degrés. Notez que l'appareil photo n'est pas incliné à 45 degrés ; il se déplace à mi-chemin le long d'un arc entre une ligne verticale perpendiculaire (0 degré) et le sol (90 degrés), jusqu'à la position 3. L'appareil photo pointe toujours vers le point central de la carte, mais la zone représentée par la ligne en position 4 est désormais visible.

Screenshot of a map with a camera positioned at 45 degrees viewing angle, at a zoom level of 18.
Carte affichée avec un angle de vue de 45 degrés.
Diagram that shows the camera's viewing angle set to 45 degrees, with the zoom level still set to 18.
Angle de vue de 45 degrés de l'appareil photo.

Sur cette capture d'écran, la carte est toujours centrée sur le même point que sur la carte d'origine, mais davantage de caractéristiques sont apparues en haut de la carte. À mesure que vous augmentez l'angle au-delà de 45 degrés, les caractéristiques situées entre l'appareil photo et la position de la carte apparaissent proportionnellement plus grandes, tandis que les caractéristiques situées au-delà de la position de la carte apparaissent proportionnellement plus petites, ce qui donne un effet tridimensionnel.

Déplacer l'appareil photo

Maps API vous permet de modifier la partie du monde visible sur la carte. Pour cela, vous devez changer la position de l'appareil photo (au lieu de déplacer la carte).

Lorsque vous déplacez l'appareil photo, vous avez la possibilité d'animer le mouvement de l'appareil photo qui en résulte. L'animation effectue une interpolation entre les attributs d'appareil photo actuels et les nouveaux attributs. Vous pouvez également contrôler la durée de l'animation.

Remarque : Tous les mouvements programmés de l'appareil photo sont calculés par rapport à la taille de l'objet GoogleMap après avoir pris en compte toute marge extérieure qui a été ajoutée à la carte. Par exemple, ajouter une marge extérieure de 100 pixels sur le bord gauche de votre carte décale le centre de la carte de 50 pixels vers la droite. Vous trouverez plus d'informations dans la documentation sur l'[ajout d'une marge extérieure à une carte].

Pour changer la position de l'appareil photo, vous devez indiquer où vous souhaitez le déplacer à l'aide d'un paramètre CameraUpdate. Maps API vous permet de créer de nombreux types de CameraUpdate en utilisant CameraUpdateFactory. Les options suivantes sont disponibles :

Changer le niveau de zoom et définir le niveau de zoom minimum/maximum

CameraUpdateFactory.zoomIn() et CameraUpdateFactory.zoomOut() vous donnent un CameraUpdate qui change le niveau de zoom de 1.0, tout en laissant les autres propriétés inchangées.

CameraUpdateFactory.zoomTo(float) donne un CameraUpdate qui change le niveau de zoom à la valeur donnée, tout en laissant les autres propriétés inchangées.

CameraUpdateFactory.zoomBy(float) et CameraUpdateFactory.zoomBy(float, Point) donnent un CameraUpdate qui augmente (ou diminue, si la valeur est négative) le niveau de zoom de la valeur donnée. Le second fixe le point donné sur l'écran afin qu'il reste à la même position (latitude/longitude) et dans ce cas, il peut déplacer l'appareil photo pour y parvenir.

Il peut parfois s'avérer utile de définir un niveau de zoom minimum et/ou maximum idéal. Vous pouvez par exemple définir ce niveau de zoom pour contrôler l'expérience utilisateur si votre application affiche une zone définie autour d'un point d'intérêt, ou si vous utilisez une superposition de tuile personnalisée avec un ensemble limité de niveaux de zoom.

private GoogleMap mMap;
// Set a preference for minimum and maximum zoom.
mMap.setMinZoomPreference(6.0f);
mMap.setMaxZoomPreference(14.0f);

Notez que certaines considérations techniques peuvent empêcher l'API d'autoriser les utilisateurs à faire un zoom avant trop proche ou un zoom arrière trop éloigné. Par exemple, une carte satellite ou de terrain peut avoir un niveau de zoom maximum moins élevé que les tuiles de la carte de base.

Changer la position de l'appareil photo

Il existe deux méthodes pour les changements de position courants. CameraUpdateFactory.newLatLng(LatLng) donne un CameraUpdate qui change la latitude et la longitude de l'appareil photo, tout en conservant les autres propriétés. CameraUpdateFactory.newLatLngZoom(LatLng, float) donne un CameraUpdate qui change la latitude, la longitude et le zoom de l'appareil photo, tout en conservant les autres propriétés.

Pour plus de souplesse dans le changement de position de l'appareil photo, utilisez CameraUpdateFactory.newCameraPosition(CameraPosition) qui donne un CameraUpdate qui déplace l'appareil photo sur la position donnée. Un CameraPosition peut être obtenu soit directement, en utilisant new CameraPosition(), soit avec un CameraPosition.Builder en utilisant new CameraPosition.Builder().

Défilement

CameraUpdateFactory.scrollBy(float, float) vous donne un CameraUpdate qui change la latitude et la longitude de l'appareil photo de sorte que la carte se déplace du nombre de pixels spécifié. Une valeur x positive déplace l'appareil photo vers la droite, de sorte que la carte semble avoir bougé vers la gauche. Une valeur y positive déplace l'appareil photo vers le bas, de sorte que la carte semble avoir bougé vers le haut. Inversement, des valeurs x négatives déplacent l'appareil photo vers la gauche, de sorte que la carte semble avoir bougé vers la droite, et des valeurs y négatives déplacent l'appareil photo vers le haut. Le défilement est effectué par rapport à l'orientation actuelle de l'appareil photo. Par exemple, si l'appareil photo est orienté à 90 degrés, alors l'est est « en haut ».

Définir des limites

Définir les limites de la carte

Il peut parfois être utile de déplacer l'appareil photo pour que la totalité d'une zone d'intérêt soit visible au plus haut niveau de zoom possible. Par exemple, si vous affichez toutes les stations-service dans un rayon de 5 km autour de la position actuelle de l'utilisateur, vous pouvez déplacer l'appareil photo afin qu'elles soient toutes visibles sur l'écran. Pour ce faire, vous devez d'abord calculer la limite LatLngBounds qui doit être visible à l'écran. Vous pouvez ensuite utiliser CameraUpdateFactory.newLatLngBounds(LatLngBounds bounds, int padding) pour obtenir un CameraUpdate qui change la position de l'appareil photo de sorte que la LatLngBounds tienne entièrement dans la carte, en tenant compte de la marge extérieure (en pixels) indiquée. Le CameraUpdate obtenu garantit que l'espace (en pixels) qui sépare la limite donnée et le bord de la carte est au moins égal à la marge extérieure indiquée. Notez que l'inclinaison et la direction de la carte seront toutes deux égales à 0.

private GoogleMap mMap;
// Create a LatLngBounds that includes Australia.
private LatLngBounds AUSTRALIA = new LatLngBounds(
  new LatLng(-44, 113), new LatLng(-10, 154));

// Set the camera to the greatest possible zoom level that includes the
// bounds
mMap.moveCamera(CameraUpdateFactory.newLatLngBounds(AUSTRALIA, 0));

Centrer la carte dans une zone donnée

Dans certains cas, vous pouvez vouloir centrer votre appareil photo dans des limites au lieu d'inclure les bordures extrêmes. Par exemple, pour centrer l'appareil photo sur un pays tout en conservant un zoom constant. Dans ce cas, vous pouvez utiliser une méthode similaire, en créant un LatLngBounds et en utilisant CameraUpdateFactory.newLatLngZoom(LatLng latLng, float zoom) avec la méthode LatLngBounds.getCenter(). La méthode getCenter() renvoie le centre géographique de LatLngBounds.

private GoogleMap mMap;
private LatLngBounds AUSTRALIA = new LatLngBounds(
  new LatLng(-44, 113), new LatLng(-10, 154));

mMap.moveCamera(CameraUpdateFactory.newLatLngZoom(AUSTRALIA.getCenter(), 10));

Une surcharge de la méthode, newLatLngBounds(boundary, width, height, padding) vous permet d'indiquer la largeur et la hauteur en pixels d'un rectangle, avec l'intention que celles-ci correspondent aux dimensions de la carte. Le rectangle est positionné de telle sorte que son centre est identique à celui de la vue de la carte (de sorte que si les dimensions spécifiées sont les mêmes que celles de la vue de la carte, le rectangle coïncide avec la vue de la carte). La valeur CameraUpdate obtenue déplacera l'appareil photo de sorte que les limites LatLngBounds indiquées soient centrées sur l'écran au sein du rectangle donné au plus haut niveau de zoom possible, en tenant compte de la marge extérieure nécessaire.

Remarque : Utilisez uniquement la méthode plus simple newLatLngBounds(boundary, padding) pour générer un CameraUpdate si cela permet de déplacer l'appareil photo une fois que la disposition de la carte est effectuée. Au cours de la disposition, l'API calcule les limites d'affichage de la carte qui sont nécessaires pour projeter correctement la zone de délimitation. En comparaison, vous pouvez utiliser le CameraUpdate renvoyé par la méthode plus complexe newLatLngBounds(boundary, width, height, padding) à tout moment, même avant que la disposition de la carte soit terminée, car l'API calcule les limites d'affichage à partir des arguments que vous transmettez.

Limiter le panoramique à une zone donnée

Dans les scénarios ci-dessus, vous définissez les limites de la carte, mais les utilisateurs peuvent ensuite faire défiler la carte ou effectuer un panoramique au-delà de ces limites. Vous pouvez toutefois fixer des limites au centre lat/lng du point focal de la carte (la cible de l'appareil photo) pour que les utilisateurs puissent uniquement faire défiler la carte ou effectuer un panoramique à l'intérieur de ces limites. Cela pourrait, par exemple, s'avérer utile pour une application de vente au détail dans un centre commercial ou un aéroport, afin que les utilisateurs ne puissent pas faire défiler la carte ou effectuer un panoramique au-delà des limites ainsi définies.

private GoogleMap mMap;
// Create a LatLngBounds that includes the city of Adelaide in Australia.
private LatLngBounds ADELAIDE = new LatLngBounds(
  new LatLng(-35.0, 138.58), new LatLng(-34.9, 138.61));
// Constrain the camera target to the Adelaide bounds.
mMap.setLatLngBoundsForCameraTarget(ADELAIDE);

Le diagramme ci-dessous illustre le scénario suivant : la cible de l'appareil photo est limitée à une zone légèrement plus grande que la fenêtre d'affichage. L'utilisateur peut faire défiler la carte ou effectuer un panoramique, sous réserve que la cible de l'appareil photo reste dans la zone délimitée. La croix représente la cible de l'appareil photo :

Diagram showing a camera LatLngBounds that is larger than the
      viewport.

La carte remplit toujours la fenêtre d'affichage, même si cela se traduit par l'affichage de zones qui se trouvent en dehors des limites définies. Par exemple, si vous positionnez la cible de l'appareil photo à un angle de la zone délimitée, la zone située au-delà de l'angle est visible dans la fenêtre d'affichage, mais les utilisateurs ne peuvent pas faire défiler la carte jusque dans cette zone. Le diagramme suivant illustre ce scénario. La croix représente la cible de l'appareil photo :

Diagram showing the camera target positioned at bottom right corner of
      the camera LatLngBounds.

Dans le diagramme suivant, la cible de l'appareil photo est particulièrement réduite, ce qui offre à l'utilisateur peu de liberté pour faire défiler la carte ou effectuer un panoramique. La croix représente la cible de l'appareil photo :

Diagram showing a camera LatLngBounds that is smaller than the
      viewport.

Actualiser la vue de l'appareil photo

Pour appliquer un CameraUpdate à la carte, vous pouvez au choix déplacer l'appareil photo instantanément ou l'animer doucement. Pour déplacer l'appareil photo instantanément avec le CameraUpdate donné, vous pouvez appeler GoogleMap.moveCamera(CameraUpdate).

Pour rendre l'expérience utilisateur plus agréable, surtout pour les déplacements courts, vous pouvez animer ce changement. Pour ce faire, au lieu d'appeler GoogleMap.moveCamera, appelez GoogleMap.animateCamera. La carte se déplacera lentement vers les nouveaux attributs. La forme la plus détaillée de cette méthode, GoogleMap.animateCamera(cameraUpdate, duration, callback), offre trois arguments :

cameraUpdate
Argument CameraUpdate décrivant où déplacer l'appareil photo.
callback
Objet qui implémente GoogleMap.CancellableCallback. Cette interface généralisée pour la gestion des tâches définit deux méthodes `onCancel()` et `onFinished()`. Pour l'animation, les méthodes sont appelées dans les cas suivants :
onFinish()
Est appelée si l'animation arrive à la fin sans interruption.
onCancel()

Est appelée si l'animation est interrompue en appelant stopAnimation() ou en initiant un nouveau mouvement de l'appareil photo.

Cela peut aussi se produire si vous appelez GoogleMap.stopAnimation().

duration
Durée souhaitée de l'animation, en millisecondes, sous forme de int.

Les extraits de code suivants illustrent quelques-unes des méthodes les plus utilisées pour déplacer l'appareil photo.

private static final LatLng SYDNEY = new LatLng(-33.88,151.21);
private static final LatLng MOUNTAIN_VIEW = new LatLng(37.4, -122.1);

private GoogleMap map;
... // Obtain the map from a MapFragment or MapView.

// Move the camera instantly to Sydney with a zoom of 15.
map.moveCamera(CameraUpdateFactory.newLatLngZoom(SYDNEY, 15));

// Zoom in, animating the camera.
map.animateCamera(CameraUpdateFactory.zoomIn());

// Zoom out to zoom level 10, animating with a duration of 2 seconds.
map.animateCamera(CameraUpdateFactory.zoomTo(10), 2000, null);

// Construct a CameraPosition focusing on Mountain View and animate the camera to that position.
CameraPosition cameraPosition = new CameraPosition.Builder()
    .target(MOUNTAIN_VIEW)      // Sets the center of the map to Mountain View
    .zoom(17)                   // Sets the zoom
    .bearing(90)                // Sets the orientation of the camera to east
    .tilt(30)                   // Sets the tilt of the camera to 30 degrees
    .build();                   // Creates a CameraPosition from the builder
map.animateCamera(CameraUpdateFactory.newCameraPosition(cameraPosition));

Envoyer des commentaires concernant…

Google Maps Android API
Google Maps Android API
Besoin d'aide ? Consultez notre page d'assistance.