Obtenir un itinéraire

Un itinéraire est un chemin navigable entre un point de départ (ou origine) et un point d'arrivée (ou destination). Vous pouvez choisir d'obtenir un itinéraire pour différents modes de transport, comme la marche, le vélo ou différents types de véhicules. Vous pouvez également demander des informations sur l'itinéraire, comme la distance, la durée estimée du trajet, les péages prévus et les instructions détaillées pour suivre l'itinéraire.

Appelez la méthode computeRoutes() pour demander un itinéraire entre deux lieux. L'exemple suivant montre comment définir une requête, puis appeler computeRoutes() pour obtenir un itinéraire. 

  // Import the Routes library.
  const { Route } = await google.maps.importLibrary('routes');

  // Define a computeRoutes request.
  const request = {
    origin: 'Mountain View, CA',
    destination: 'San Francisco, CA',
  };

  // Call the computeRoutes() method to get routes.
  const {routes} = await Route.computeRoutes(request);

Choisir les champs à renvoyer

Lorsque vous demandez un itinéraire, vous devez utiliser un masque de champ pour spécifier les informations que la réponse doit renvoyer. Vous pouvez spécifier les noms des propriétés de la classe Route dans le masque de champ.

L'utilisation d'un masque de champ permet également de s'assurer de ne pas demander de données inutiles, ce qui contribue à réduire la latence des réponses et à éviter de renvoyer des informations dont votre système n'a pas besoin.

Spécifiez la liste des champs dont vous avez besoin en définissant la propriété ComputeRoutesRequest.fields, comme indiqué dans l'extrait suivant : 

// Define a routes request.
const request = {
  origin: 'Mountain View, CA',
  destination: 'San Francisco, CA',
  fields: ['path'], // Request fields needed to draw polylines.
};

Spécifier des lieux pour un itinéraire

Pour calculer un itinéraire, vous devez spécifier au minimum les emplacements du point de départ et de la destination, ainsi qu'un masque de champ. Vous pouvez également spécifier des points de cheminement intermédiaires le long d'un itinéraire et les utiliser pour ajouter des arrêts ou des points de passage, par exemple.

Dans ComputeRoutesRequest, vous pouvez spécifier un emplacement de l'une des manières suivantes :

Vous pouvez spécifier des lieux pour tous les points de cheminement d'une requête de la même manière ou les combiner. Par exemple, vous pouvez utiliser des coordonnées de latitude/longitude pour le point de cheminement d'origine et un objet Place pour le point de cheminement de destination.

Pour plus d'efficacité et de précision, utilisez des objets Place au lieu de coordonnées de latitude/longitude ou de chaînes d'adresse. Les ID de lieux sont explicitement uniques et offrent des avantages de géocodage pour le routage, tels que les points d'accès et les variables de trafic. Ils permettent d'éviter les situations suivantes qui peuvent résulter d'autres méthodes de spécification d'un emplacement :

  • L'utilisation de coordonnées de latitude/longitude peut entraîner l'ancrage de la position sur la route la plus proche de ces coordonnées, qui peut ne pas être un point d'accès à la propriété, ni même une route menant rapidement ou en toute sécurité à la destination.
  • Les chaînes d'adresse doivent d'abord être géocodées par l'API Routes pour être converties en coordonnées de latitude/longitude avant de pouvoir calculer un itinéraire. Cette conversion peut avoir un impact sur les performances.

Spécifier un lieu en tant qu'objet Place (recommandé)

Pour spécifier un lieu à l'aide d'un lieu, créez une instance Place. L'extrait suivant montre comment créer des instances Place pour origin et destination, puis comment les utiliser dans un ComputeRoutesRequest : 

// Create a new Place for the origin.
const originPlace = new Place({
  id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
});

// Create a new Place for the destination.
const destinationPlace = new Place({
  id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
});

// Define a computeRoutes request.
const request = {
  origin: originPlace,
  destination: destinationPlace,
  fields: ['path'],
};

Coordonnées de latitude/longitude

Pour spécifier un lieu sous forme de coordonnées de latitude/longitude, créez une instance google.maps.LatLngLiteral, google.maps.LatLngAltitude ou google.maps.LatLngAltitudeLiteral. L'extrait suivant montre comment créer des instances google.maps.LatLngLiteral pour origin et destination, puis les utiliser dans un computeRoutesRequest : 

// Create new LatLngLiteral objects for the origin and destination.
// Mountain View, CA
const originLatLng = {lat: 37.422000, lng: -122.084058};
// San Francisco, CA
const destinationLatLng = {lat: 37.774929, lng: -122.419415};

// Define a computeRoutes request.
const request = {
  origin: originLatLng,
  destination: destinationLatLng,
  fields: ['path'],
};

Chaîne d'adresse

Les chaînes d'adresse sont des adresses littérales représentées par une chaîne (par exemple, "1600 Amphitheatre Parkway, Mountain View, CA"). Le geocoding consiste à convertir une chaîne d'adresse en coordonnées de latitude et de longitude (par exemple, latitude 37.423021 et longitude -122.083739).

Lorsque vous transmettez une chaîne d'adresse comme emplacement d'un point de repère, la bibliothèque Routes géocode en interne la chaîne pour la convertir en coordonnées de latitude et de longitude.

L'extrait suivant montre comment créer un ComputeRoutesRequest avec une chaîne d'adresse pour origin et destination : 

// Define a computeRoutes request.
const request = {
  origin: '1600 Amphitheatre Parkway, Mountain View, CA',
  destination: '345 Spear Street, San Francisco, CA',
  fields: ['path'],
};

Définir la région de l'adresse

Si vous transmettez une chaîne d'adresse incomplète comme emplacement d'un point de repère, l'API peut utiliser les mauvaises coordonnées de latitude/longitude géocodées. Par exemple, vous envoyez une requête spécifiant "Toledo" comme origine et "Madrid" comme destination pour un itinéraire en voiture : 

// Define a request with an incomplete address string.
const request = {
  origin: 'Toledo',
  destination: 'Madrid',
};

Dans cet exemple, "Toledo" est interprété comme une ville de l'État de l'Ohio aux États-Unis, et non en Espagne. Par conséquent, la requête renvoie un tableau vide, ce qui signifie qu'il n'existe aucun itinéraire.

Vous pouvez configurer l'API pour qu'elle renvoie des résultats pondérés en faveur d'une région en particulier en incluant le paramètre regionCode. Ce paramètre spécifie le code régional sous la forme d'une valeur ccTLD (domaine de premier niveau) à deux caractères. La plupart des codes ccTLD sont identiques aux codes ISO 3166-1, à quelques exceptions près. Par exemple, le ccTLD du Royaume-Uni est "uk" (.co.uk), tandis que son code ISO 3166-1 est "gb" (techniquement pour l'entité "Royaume-Uni de Grande-Bretagne et d'Irlande du Nord").

Une requête d'itinéraire de "Toledo" à "Madrid" qui inclut le paramètre regionCode renvoie des résultats appropriés, car "Toledo" est interprété comme une ville en Espagne :

const request = {
  origin: 'Toledo',
  destination: 'Madrid',
  region: 'es', // Specify the region code for Spain.
};

Plus Code

De nombreuses personnes ne disposent pas d'une adresse précise, ce qui peut leur rendre difficile la réception de livraisons. Les personnes disposant d'une adresse peuvent préférer recevoir leurs colis à des endroits plus spécifiques, comme une entrée arrière ou un quai de chargement.

Les Plus Codes fonctionnent comme des adresses postales pour les personnes ou les lieux qui n'en ont pas. Contrairement aux adresses avec des noms et des numéros de rue, ils sont basés sur les coordonnées de latitude et de longitude, et sont affichés sous forme de numéros et de lettres.

Google a développé les Plus Codes pour que tout le monde puisse bénéficier des avantages des adresses. Un Plus Code est une référence de lieu encodée, calculée à partir de coordonnées de latitude et de longitude, qui représente une zone : 1/8000e de degré par 1/8000e de degré (environ 14 m x 14 m à l'équateur) ou moins. Vous pouvez utiliser des Plus Codes pour remplacer les adresses postales dans les endroits où elles n'existent pas ou où les bâtiments ne sont pas numérotés ni les rues nommées.

Les Plus Codes doivent être mis en forme comme un code global ou un code composé :

  • Le code global est composé d'un indicatif de zone de 4 caractères et d'un code local à 6 caractères ou plus. Par exemple, pour l'adresse "1600 Amphitheatre Parkway, Mountain View, CA", le code mondial est "849V" et le code local est "CWC8+R9". Vous utilisez ensuite le code Plus complet de 10 caractères pour spécifier la valeur du lieu, par exemple "849VCWC8+R9".
  • Le code composé est un code local à six caractères ou plus associé à un emplacement explicite. Par exemple, l'adresse "450 Serra Mall, Stanford, CA 94305, États-Unis" a un code local "CRHJ+C3". Pour une adresse composée, combinez le code local avec la partie de l'adresse correspondant à la ville, à l'État, au code postal et au pays, sous la forme "CRHJ+C3 Stanford, CA 94305, USA".

L'extrait suivant montre comment calculer un itinéraire en spécifiant un point de cheminement pour l'origine et la destination de l'itinéraire à l'aide de codes Plus : 

const request = {
  origin: '849VCWC8+R9', // Mountain View, CA
  destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
  fields: ['path'],
};