Vous êtes prêt !

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

Activer Google Maps JavaScript API

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

  1. Créer ou sélectionner un projet
  2. Activer Google Maps JavaScript API et les services connexes
  3. Créer les clés appropriées
Continuer

Bibliothèque Geometry

  1. Présentation
  2. Concepts de géométrie sphérique
    1. Fonctions de distance et de superficie
    2. Fonctions de navigation
  3. Codage géométrique
  4. Fonctions de polygone et de polyligne
    1. containsLocation()
    2. isLocationOnEdge()

Présentation

Les concepts présentés dans ce document se rapportent aux seules fonctionnalités disponibles dans la bibliothèque google.maps.geometry. Cette bibliothèque n'est pas chargée par défaut lorsque vous chargez Maps Javascript API. Vous devez la spécifier explicitement en utilisant un paramètre bootstrap libraries.

Pour plus d'informations, voir la présentation des bibliothèques.

La bibliothèque Geometry Google Maps JavaScript API fournit des fonctions pour le calcul des données géométriques à la surface de la Terre. Cette bibliothèque comprend trois espaces de noms :

  • spherical contient des outils géométriques sphériques vous permettant de calculer des angles, des distances et des superficies à partir de latitudes et de longitudes.
  • encoding contient des outils pour l'encodage et le décodage des tracés de polylignes en fonction de l'algorithme d'encodage des polylignes.
  • poly contient des fonctions pour les calculs impliquant des polygones et des polylignes.

La bibliothèque google.maps.geometry ne contient aucune classe, mais des méthodes statiques pour les espaces de noms ci-dessus.

Concepts de géométrie sphérique

Les images fournies par Google Maps JavaScript API sont bidimensionnelles et « plates ». La Terre, par contre, est tridimensionnelle et souvent représentée soit sous la forme d'un sphéroïde aplati, soit tout simplement d'une sphère. Dans Maps API, nous utilisons une sphère, et pour représenter la Terre sur une surface plane bidimensionnelle – comme votre écran d'ordinateur – Maps API utilise une projection.

Dans les projections en 2D, les apparences peuvent parfois être trompeuses. Dans la mesure où une projection de carte implique nécessairement un certain degré de distorsion, la simple géométrie euclidienne n'est souvent pas applicable. Par exemple, la distance la plus courte entre deux points sur une sphère n'est pas la ligne droite, mais un grand cercle (un type de géodésique). Quant aux angles qui forment un triangle sur la surface d'une sphère, leur somme est supérieure à 180 degrés.

À cause de ces différences, les fonctions géométriques sur une sphère (ou sa projection) nécessitent d'utiliser la géométrie sphérique pour calculer des concepts tels qu'une distance, un cap ou une superficie. Les outils nécessaires au calcul de ces concepts géométriques sphériques sont contenus dans l'espace de nom google.maps.geometry.spherical de Maps API. Cet espace de noms fournit des méthodes statiques pour le calcul des valeurs scalaires à partir de coordonnées sphériques (latitudes et longitudes).

Fonctions de distance et de superficie

La distance entre deux points est la longueur du tracé le plus court entre ces deux points. Ce tracé le plus court est appelé une géodésique. Sur une sphère, toutes les géodésiques sont les segments d'un grand cercle. Pour calculer cette distance, appelez computeDistanceBetween() en spécifiant deux objets LatLng.

Vous pouvez aussi appeler computeLength() pour calculer la longueur d'un tracé donné si vous avez plusieurs points géographiques.

Les résultats de distance sont exprimés en mètres.

Pour calculer la superficie (en mètres carrés) d'une aire polygonale, appelez computeArea() en spécifiant le tableau des objets LatLng définissant une boucle fermée.

Lorsque l'on navigue sur une sphère, on appelle cap l'angle d'une direction à partir d'un point de référence fixe, généralement le nord géographique. Dans Google Maps API, les caps sont définis en degrés et mesurés dans le sens horaire à partir du nord géographique (0 degré). Vous pouvez mesurer le cap entre deux points géographiques avec la méthode computeHeading(), en utilisant deux objets LatLng from et to.

Avec un cap spécifique, un point géographique d'origine et la distance à parcourir (en mètres), vous pouvez calculer les coordonnées de destination en utilisant la méthode computeOffset().

Avec deux objets LatLng et une valeur entre 0 et 1, vous pouvez également calculer une destination entre eux en utilisant la méthode interpolate(), laquelle effectue une interpolation linéaire sphérique entre deux points géographiques, où la valeur indique la distance fractionnaire à parcourir le long du tracé de l'origine à la destination.

L'exemple suivant crée deux polylignes lorsque vous cliquez sur deux points de la carte (une géodésique et une ligne « droite » connectant les deux points géographiques) et calcule le cap pour se rendre d'un point à l'autre.

// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

var marker1, marker2;
var poly, geodesicPoly;

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 34, lng: -40.605}
  });

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(
      document.getElementById('info'));

  marker1 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 40.714, lng: -74.006}
  });

  marker2 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 48.857, lng: 2.352}
  });

  var bounds = new google.maps.LatLngBounds(
      marker1.getPosition(), marker2.getPosition());
  map.fitBounds(bounds);

  google.maps.event.addListener(marker1, 'position_changed', update);
  google.maps.event.addListener(marker2, 'position_changed', update);

  poly = new google.maps.Polyline({
    strokeColor: '#FF0000',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    map: map,
  });

  geodesicPoly = new google.maps.Polyline({
    strokeColor: '#CC0099',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    geodesic: true,
    map: map
  });

  update();
}

function update() {
  var path = [marker1.getPosition(), marker2.getPosition()];
  poly.setPath(path);
  geodesicPoly.setPath(path);
  var heading = google.maps.geometry.spherical.computeHeading(path[0], path[1]);
  document.getElementById('heading').value = heading;
  document.getElementById('origin').value = path[0].toString();
  document.getElementById('destination').value = path[1].toString();
}
<div id="map"></div>
<div id="floating-panel">
  Origin: <input type="text" readonly id="origin">
  Destination: <input type="text" readonly id="destination"><br>
  Heading: <input type="text" readonly id="heading"> degrees
</div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#floating-panel {
  position: absolute;
  top: 10px;
  left: 25%;
  z-index: 5;
  background-color: #fff;
  padding: 5px;
  border: 1px solid #999;
  text-align: center;
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=geometry&callback=initMap"
    async defer></script>
// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

var marker1, marker2;
var poly, geodesicPoly;

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 34, lng: -40.605}
  });

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(
      document.getElementById('info'));

  marker1 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 40.714, lng: -74.006}
  });

  marker2 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 48.857, lng: 2.352}
  });

  var bounds = new google.maps.LatLngBounds(
      marker1.getPosition(), marker2.getPosition());
  map.fitBounds(bounds);

  google.maps.event.addListener(marker1, 'position_changed', update);
  google.maps.event.addListener(marker2, 'position_changed', update);

  poly = new google.maps.Polyline({
    strokeColor: '#FF0000',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    map: map,
  });

  geodesicPoly = new google.maps.Polyline({
    strokeColor: '#CC0099',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    geodesic: true,
    map: map
  });

  update();
}

function update() {
  var path = [marker1.getPosition(), marker2.getPosition()];
  poly.setPath(path);
  geodesicPoly.setPath(path);
  var heading = google.maps.geometry.spherical.computeHeading(path[0], path[1]);
  document.getElementById('heading').value = heading;
  document.getElementById('origin').value = path[0].toString();
  document.getElementById('destination').value = path[1].toString();
}

Voir l'exemple (geometry-headings.html)

Méthodes d'encodage

Dans Google Maps JavaScript API, les tracés sont souvent définis en tant que tableau (Array) d'objets LatLng. Ce type de tableau est toutefois volumineux et son utilisation contraignante. Vous pouvez à la place utiliser l'algorithme d'encodage de polyligne de Google pour compresser un tracé donné, que vous pouvez ensuite décompresser via un décodage.

La bibliothèque geometry contient un espace de noms encoding pour l'encodage et le décodage des polylignes.

La méthode statique encodePath() encode le tracé spécifié. Vous pouvez utiliser soit un tableau de valeurs LatLng, soit un tableau MVCArray (qui est renvoyé par la méthode Polyline.getPath()).

Pour décoder un tracé encodé, il vous suffit d'appeler la méthode decodePath() en lui spécifiant la chaîne encodée.

L'exemple suivant montre un plan d'Oxford, Mississippi. Cliquer sur le plan permet d'ajouter un point à une polyligne. À mesure que la polyligne est construite, son encodage apparaît en dessous.

// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 14,
    center: {lat: 34.366, lng: -89.519}
  });
  var poly = new google.maps.Polyline({
    strokeColor: '#000000',
    strokeOpacity: 1,
    strokeWeight: 3,
    map: map
  });

  // Add a listener for the click event
  google.maps.event.addListener(map, 'click', function(event) {
    addLatLngToPoly(event.latLng, poly);
  });
}

/**
 * Handles click events on a map, and adds a new point to the Polyline.
 * Updates the encoding text area with the path's encoded values.
 */
function addLatLngToPoly(latLng, poly) {
  var path = poly.getPath();
  // Because path is an MVCArray, we can simply append a new coordinate
  // and it will automatically appear
  path.push(latLng);

  // Update the text field to display the polyline encodings
  var encodeString = google.maps.geometry.encoding.encodePath(path);
  if (encodeString) {
    document.getElementById('encoded-polyline').value = encodeString;
  }
}
<div id="map"></div>
<div id="right-panel">
  <div>Encoding:</div>
  <textarea id="encoded-polyline"></textarea>
</div>
#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  height: 100%;
  width: 50%;
  float: left;
}
#right-panel {
  width: 46%;
  float: left;
}
#encoded-polyline {
  height: 100px;
  width: 100%;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=geometry&callback=initMap"
    async defer></script>
// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 14,
    center: {lat: 34.366, lng: -89.519}
  });
  var poly = new google.maps.Polyline({
    strokeColor: '#000000',
    strokeOpacity: 1,
    strokeWeight: 3,
    map: map
  });

  // Add a listener for the click event
  google.maps.event.addListener(map, 'click', function(event) {
    addLatLngToPoly(event.latLng, poly);
  });
}

/**
 * Handles click events on a map, and adds a new point to the Polyline.
 * Updates the encoding text area with the path's encoded values.
 */
function addLatLngToPoly(latLng, poly) {
  var path = poly.getPath();
  // Because path is an MVCArray, we can simply append a new coordinate
  // and it will automatically appear
  path.push(latLng);

  // Update the text field to display the polyline encodings
  var encodeString = google.maps.geometry.encoding.encodePath(path);
  if (encodeString) {
    document.getElementById('encoded-polyline').value = encodeString;
  }
}

Voir l'exemple (geometry-encodings.html)

Fonctions de polygone et de polyligne

L'espace de noms poly de la bibliothèque Geometry contient des fonctions qui déterminent si un point donné se trouve à l'intérieur ou à proximité d'un polygone ou d'une polyligne.

containsLocation()

containsLocation(point:LatLng, polygon:Polygon)

Pour savoir si un point donné se trouve à l'intérieur d'un polygone, transmettez le point et le polygone à google.maps.geometry.poly.containsLocation(). Les fonctions renvoient la réponse « true » si le point se trouve à l'intérieur du polygone ou sur son bord.

Le code suivant affiche « true » sur la console du navigateur si l'utilisateur clique dans le triangle défini. Dans le cas contraire, il affiche « false ».

function initialize() {
  var mapOptions = {
    zoom: 5,
    center: new google.maps.LatLng(24.886, -70.269),
    mapTypeId: 'terrain'
  };

  var map = new google.maps.Map(document.getElementById('map'),
      mapOptions);

  var bermudaTriangle = new google.maps.Polygon({
    paths: [
      new google.maps.LatLng(25.774, -80.190),
      new google.maps.LatLng(18.466, -66.118),
      new google.maps.LatLng(32.321, -64.757)
    ]
  });

  google.maps.event.addListener(map, 'click', function(event) {
    console.log(google.maps.geometry.poly.containsLocation(event.latLng, bermudaTriangle));
  });
}

google.maps.event.addDomListener(window, 'load', initialize);

Une autre version de ce code dessine un cercle rouge sur la carte si le clic tombe dans le Triangle des Bermudes, et vert s'il tombe à côté :

Voir l'exemple (poly-containsLocation)

isLocationOnEdge()

isLocationOnEdge(point:LatLng, poly:Polygon|Polyline, tolerance?:number)

Pour déterminer si un point tombe sur ou à côté d'une polyligne, ou bien sur ou à côté du bord d'un polygone, transmettez le point, la polyligne/le polygone et éventuellement une valeur de tolérance en degrés à google.maps.geometry.poly.isLocationOnEdge(). La fonction renvoie « true » si la distance entre le point et le point le plus proche sur la ligne ou le bord tombe dans la tolérance spécifiée. La valeur de tolérance par défaut est de 10-9 degrés.

function initialize() {
  var myPosition = new google.maps.LatLng(46.0, -125.9);

  var mapOptions = {
    zoom: 5,
    center: myPosition,
    mapTypeId: 'terrain'
  };

  var map = new google.maps.Map(document.getElementById('map'),
      mapOptions);

  var cascadiaFault = new google.maps.Polyline({
    path: [
      new google.maps.LatLng(49.95, -128.1),
      new google.maps.LatLng(46.26, -126.3),
      new google.maps.LatLng(40.3, -125.4)
    ]
  });

  cascadiaFault.setMap(map);

  if (google.maps.geometry.poly.isLocationOnEdge(myPosition, cascadiaFault, 10e-1)) {
    alert("Relocate!");
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

Envoyer des commentaires concernant…

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