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

Service Directions

Présentation

Vous pouvez calculer des itinéraires (en utilisant divers moyens de transport) à l'aide de l'objet DirectionsService. Cet objet communique avec le service Directions de Google Maps API, qui reçoit les demandes d'itinéraire et renvoie le résultat des calculs. Vous pouvez utiliser ces résultats d'itinéraire vous-même ou utiliser l'objet DirectionsRenderer pour en effectuer le rendu.

Lorsque vous indiquez le point de départ ou la destination dans une requête d'itinéraire, vous pouvez spécifier une chaîne de requête (par exemple, « Chicago, Illinois » ou « Darwin, Nouvelle-Galles du Sud, Australie »), une valeur LatLng ou un objet google.maps.Place.

Le service Directions peut renvoyer des itinéraires multi-segments passant par une série de points de cheminement. L'itinéraire est affiché sous forme de polyligne qui représente le trajet sur une carte, ou en outre comme une série de descriptions textuelles dans un élément <div> (par exemple, « Tourner à droite sur la bretelle d'accès à Williamsburg Bridge »).

Premiers pas

Avant d'utiliser le service Directions dans Google Maps JavaScript API, assurez-vous que Google Maps Directions API est activé dans Google API Console, dans le projet que vous avez configuré pour Google Maps JavaScript API.

Pour afficher la liste des API activées :

  1. Allez à la Google API Console.
  2. Cliquez sur le bouton Select a project, sélectionnez le projet que vous avez configuré pour Google Maps JavaScript API et cliquez sur Open.
  3. Recherchez Google Maps Directions API dans la liste des API affichées dans le Dashboard.
  4. Si vous trouvez l'API dans la liste, vous pouvez continuer. Si l'API ne figure pas dans la liste, vous devez l'activer :
    1. En haut de la page, sélectionnez ENABLE API pour afficher l'onglet Library. Vous pouvez également sélectionner Library dans le menu de gauche.
    2. Recherchez Google Maps Directions API, puis sélectionnez-la dans la liste des résultats.
    3. Sélectionnez ENABLE. Une fois le processus terminé, Google Maps Directions API apparaît dans la liste des API sur le Dashboard.

Limites d'utilisation et politiques

Quotas

Le service Directions est soumis aux limites d'utilisation suivantes :

Utilisation du service Directions avec le plan Standard

  • 2 500 requêtes gratuites par jour (en additionnant les requêtes côté client et côté serveur). activer la facturation pour bénéficier de quotas journaliers supérieurs, facturés à 0,50 USD / 1 000 requêtes supplémentaires, jusqu'à 100 000 requêtes par jour.
  • Jusqu'à 23 points de cheminement par requête, en plus du point de départ et de la destination.
  • 50 requêtes par seconde (en additionnant les requêtes côté client et côté serveur).

Utilisation du service Directions avec le plan Premium

  • Quota journalier gratuit partagé de 100 000 requêtes par tranche de 24 heures ; requêtes supplémentaires dans le cadre de l'achat annuel de crédits Maps API.
  • Jusqu'à 23 points de cheminement autorisés par requête, en plus du point de départ et de la destination.
  • Illimité requêtes côté client par seconde et par projet. Notez que l'API côté serveur est limitée à 50 requêtes par seconde.

La limite du taux est appliquée par session utilisateur, indépendamment du nombre d'utilisateurs qui partagent le même projet.

La limite du taux par session évite que les services côté client soient utilisés pour des requêtes groupées. Pour les requêtes groupées, utilisez le service Web Google Maps Directions API.

Politiques

Le service Directions doit être utilisé conformément aux politiques de Google Maps Directions API.

Requêtes Directions

Étant donné que Google Maps API doit appeler un serveur externe, l'accès au service Directions est asynchrone. Pour cette raison, vous devez définir une méthode de rappel à exécuter à la fin de la requête. Cette méthode de rappel doit traiter le ou les résultats. Notez que le service Directions peut renvoyer plusieurs itinéraires possibles sous forme de tableau d'éléments routes[] distincts.

Pour utiliser des itinéraires dans Google Maps JavaScript API, créez un objet de type DirectionsService et appelez DirectionsService.route() pour lancer une requête au service Directions, en lui spécifiant un littéral objet DirectionsRequest contenant les termes d'entrée et une méthode de rappel à exécuter à la réception de la réponse.

Le littéral objet DirectionsRequest contient les champs suivants :

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

Ces champs sont décrits ci-dessous :

  • origin (obligatoire) indique le point géographique de départ à partir duquel l'itinéraire est calculé. Cette valeur peut être spécifiée comme une String (par exemple, « Chicago, IL »), une valeur LatLng ou un objet google.maps.Place. Si vous utilisez un objet google.maps.Place, vous pouvez spécifier un paramètre place ID, une chaîne de requête ou un point géographique LatLng. Vous pouvez récupérer des identifiants de lieu grâce aux services Geocoding, Place Search et Place Autocomplete dans Google Maps JavaScript API. Pour consulter un exemple d'utilisation des identifiants de lieu à partir de Place Autocomplete, voir Place Autocomplete et Directions.
  • destination (obligatoire) indique la destination vers laquelle l'itinéraire est calculé. Les options sont les mêmes que celles du champ origin décrites ci-dessus.
  • travelMode (obligatoire) spécifie le mode de transport à utiliser pour calculer l'itinéraire. Les valeurs valides sont spécifiées dans la section Modes de transport ci-dessous.
  • transitOptions (facultatif) spécifie les valeurs applicables uniquement aux requêtes dans lesquelles travelMode est défini sur TRANSIT. Les valeurs valides sont décrites dans la section Options de transport en commun ci-dessous.
  • drivingOptions (facultatif) spécifie les valeurs applicables uniquement aux requêtes dans lesquelles travelMode est défini sur DRIVING. Les valeurs valides sont décrites dans la section Options d'itinéraire routier ci-dessous.
  • unitSystem (facultatif) spécifie le système d'unités à utiliser pour l'affichage des résultats. Les valeurs valides sont spécifiées dans la section Systèmes d'unités ci-dessous.

  • waypoints[] (facultatif) spécifie un tableau de DirectionsWaypoint. Les points de cheminement modifient un itinéraire en le faisant passer par le ou les points géographiques indiqués. Un point de cheminement est spécifié en tant que littéral objet avec les champs présentés ci-dessous :

    • location spécifie la localisation du point de cheminement, sous forme de coordonnées LatLng, d'un objet google.maps.Place ou d'une chaîne String qui sera géocodée.
    • stopover est une valeur booléenne qui indique que le point de cheminement est un arrêt sur le trajet, ce qui a pour effet de diviser l'itinéraire en deux.

    (Pour plus d'informations sur les points de cheminement, voir Utilisation des points de cheminement dans les itinéraires ci-dessous.)

  • optimizeWaypoints (facultatif) indique qu'il est possible d'optimiser l'itinéraire basé sur les points de cheminement fournis en réorganisant ces derniers de manière plus efficace. S'il est défini sur true, le service Directions renvoie les waypoints réordonnés dans un champ waypoint_order. (Pour plus d'informations, voir Utilisation des points de cheminement dans les itinéraires ci-dessous.)
  • provideRouteAlternatives (facultatif). S'il est défini sur true, il spécifie que le service Directions peut proposer plusieurs itinéraires possibles dans la réponse. Notez que le calcul d'itinéraires alternatifs peut augmenter le temps de réponse du serveur.
  • avoidHighways (facultatif). S'il est défini sur true, il indique que les itinéraires calculés doivent éviter les grands axes routiers, si possible.
  • avoidTolls (facultatif). S'il est défini sur true, il indique que les itinéraires calculés doivent éviter les autoroutes à péage, si possible.
  • region (facultatif) spécifie le code de région, indiqué sous forme de valeur ccTLD (« domaine de premier niveau ») à deux caractères. (Pour plus d'informations, voir Limiter les résultats à une région ci-dessous).

Voici un exemple de DirectionsRequest ci-dessous :

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Modes de transport

Lorsque vous calculez des itinéraires, vous devez spécifier le mode de transport à utiliser. Actuellement, les modes de transport suivants sont pris en charge :

  • DRIVING (mode par défaut) indique l'itinéraire en voiture standard via le réseau routier.
  • BICYCLING permet de rechercher un itinéraire pour un cycliste qui emprunterait les pistes cyclables et les rues privilégiées.
  • TRANSIT permet de rechercher un itinéraire empruntant les transports en commun.
  • WALKING permet de rechercher un itinéraire pour un piéton qui emprunterait les voies piétonnes et les trottoirs.

Consultez les données de couverture de Google Maps pour savoir dans quelle mesure un pays prend en charge ces différents itinéraires. Si vous demandez un itinéraire dans une région où ce type d'itinéraires n'est pas disponible, la réponse renvoie DirectionsStatus="ZERO_RESULTS".

Parfois, les itinéraires à pied ne comprennent pas de voies piétonnes. Dans ce cas, le résultat renvoyé contient des avertissements dans DirectionsResult que vous devez afficher si vous n'utilisez pas le DirectionsRenderer par défaut.

Options de transport en commun

Les options disponibles pour les requêtes d'itinéraire dépendent du mode de transport. Lors d'une demande d'itinéraire en transports en commun, les options avoidHighways, avoidTolls, waypoints[] et optimizeWaypoints sont ignorées. Vous pouvez spécifier des options d'itinéraire spécifiques aux transports en commun via le littéral objet TransitOptions.

Les itinéraires en transports en commun dépendent du facteur temps. Les itinéraires ne sont renvoyés que pour des horaires futurs.

Le littéral objet TransitOptions contient les champs suivants :

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  routingPreference: TransitRoutePreference
}

Ces champs sont décrits ci-dessous :

  • arrivalTime (facultatif) permet d'indiquer l'heure d'arrivée souhaitée en tant qu'objet Date. Si l'heure d'arrivée est spécifiée, l'heure de départ est ignorée.
  • departureTime (facultatif) permet d'indiquer l'heure de départ souhaitée en tant qu'objet Date. Le champ departureTime est ignoré si une valeur est spécifiée dans le champ arrivalTime. Il est défini par défaut sur l'heure actuelle si aucune valeur n'est spécifiée pour departureTime ni pour arrivalTime.
  • modes[] (facultatif) est un tableau contenant un ou plusieurs littéraux objets TransitMode. Vous ne pouvez inclure ce champ que si la requête comprend une clé d'API. Chaque littéral objet TransitMode spécifie un moyen de transport en commun privilégié. Les valeurs suivantes sont autorisées :
    • BUS indique que l'itinéraire calculé doit privilégier les trajets en bus.
    • RAIL indique que l'itinéraire calculé doit privilégier les trajets en train, en tramway, en métro léger et en métro.
    • SUBWAY indique que l'itinéraire calculé doit privilégier les trajets en métro.
    • TRAIN indique que l'itinéraire calculé doit privilégier les trajets en train.
    • TRAM indique que l'itinéraire calculé doit privilégier les trajets en tramway et en métro léger.
  • routingPreference (facultatif) spécifie les préférences des itinéraires en transports en commun. Cette option vous permet de biaiser les options renvoyées, plutôt que d'accepter le meilleur itinéraire choisi par défaut par l'API. Vous ne pouvez spécifier ce champ que si la requête comprend une clé d'API. Les valeurs suivantes sont autorisées :
    • FEWER_TRANSFERS indique que l'itinéraire calculé doit s'efforcer de limiter le nombre de correspondances.
    • LESS_WALKING indique que l'itinéraire calculé doit s'efforcer de limiter la distance parcourue à pied.

Un exemple d'objet DirectionsRequest en transports en commun est illustré ci-dessous :

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Options d'itinéraire routier

Vous pouvez spécifier des options spécifiques aux itinéraires routiers par le biais de l'objet DrivingOptions. Vous devez fournir un ID client Google Maps APIs Premium Plan lorsque vous chargez l'API si vous souhaitez inclure un champ drivingOptions dans DirectionsRequest.

L'objet DrivingOptions contient les champs suivants :

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Ces champs sont décrits ci-dessous :

  • departureTime (obligatoire pour que le littéral objet drivingOptions soit valide) permet d'indiquer l'heure de départ souhaitée en tant qu'objet Date. Ce champ doit être défini sur l'heure actuelle ou sur une heure future. Il ne peut pas être défini sur une heure passée. (L'API convertit toutes les dates et heures à l'échelle UTC pour en assurer une gestion homogène sur l'ensemble des fuseaux horaires.) Pour les clients de Google Maps APIs Premium Plan : si vous spécifiez le champ departureTime dans la requête, l'API renvoie le meilleur itinéraire selon l'état prévu du trafic à l'heure spécifiée et inclut la durée prévue en fonction du trafic (duration_in_traffic) dans la réponse. Si vous ne spécifiez pas l'heure de départ (c'est-à-dire, si la requête n'inclut pas de champ drivingOptions), l'itinéraire renvoyé est un itinéraire globalement de bonne qualité, hors conditions de trafic.
  • trafficModel (facultatif) spécifie les hypothèses à utiliser pour calculer la durée en fonction du trafic. Ce paramètre a un impact sur la valeur renvoyée dans le champ duration_in_traffic de la réponse, lequel contient la durée prévue en fonction du trafic d'après les moyennes historiques. Sa valeur par défaut est bestguess. Les valeurs suivantes sont autorisées :
    • bestguess (valeur par défaut) indique que la valeur duration_in_traffic renvoyée doit être la meilleure estimation de la durée du trajet, d'après les éléments connus sur les conditions de circulation historiques et actuelles. Plus la valeur du paramètre departureTime est proche de l'heure actuelle, plus le trafic actuel a d'importance.
    • pessimistic indique que la valeur duration_in_traffic renvoyée doit être supérieure à la durée du trajet observée la plupart des jours, même si certains jours, lorsque l'état du trafic est particulièrement mauvais, la durée observée peut dépasser cette valeur.
    • optimistic indique que la valeur duration_in_traffic renvoyée doit être inférieure à la durée du trajet observée la plupart des jours, même si certains jours, lorsque l'état du trafic est particulièrement bon, la durée observée peut être inférieure à cette valeur.

Voici un exemple de DirectionsRequest pour un itinéraire en voiture :

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Systèmes d'unités

Par défaut, les itinéraires qui sont calculés et affichés utilisent le système d'unités du pays ou de la région de départ. (Remarque : les points de départ exprimés à l'aide de coordonnées de latitude/longitude au lieu d'adresses utilisent toujours des unités métriques par défaut.) Par exemple, un itinéraire allant de « Chicago, Illinois » à « Toronto, Ontario » affiche les résultats en miles alors que l'itinéraire inverse affiche des résultats en kilomètres. Vous pouvez modifier ce système d'unités en définissant explicitement un dans la requête, en indiquant l'une des valeurs UnitSystem suivantes :

  • UnitSystem.METRIC spécifie l'utilisation du système métrique. Les distances affichées sont exprimées en kilomètres.
  • UnitSystem.IMPERIAL spécifie l'utilisation du système impérial (anglais). Les distances affichées sont exprimées en miles.

Remarque : ce paramètre de système d'unités n'a d'impact que sur le texte affiché à l'utilisateur. Le résultat de l'itinéraire contient également des valeurs de distance, non affichées à l'utilisateur, qui sont toujours exprimées en mètres.

Limiter les résultats à une région pour l'itinéraire

Le service Directions de Google Maps API renvoie des résultats d'adresse influencés par le domaine (région ou pays) à partir duquel vous avez chargé la requête bootstrap JavaScript. (Étant donné que la plupart des utilisateurs chargent https://maps.google.com/, le domaine défini implicitement est les États-Unis.) Si vous chargez le bootstrap depuis un autre domaine pris en charge, vous obtiendrez des résultats influencés par ce domaine. Par exemple, les recherches pour « San Francisco » peuvent renvoyer des résultats différents selon que les applications chargent https://maps.google.com/ (États-Unis) ou http://maps.google.es/ (Espagne).

Vous pouvez également configurer le service Directions pour renvoyer des résultats privilégiant une région en particulier, en utilisant le paramètre region. Ce paramètre utilise un code de région, indiqué sous forme d'une balise secondaire region en langage IANA. Dans la plupart des cas, ces balises sont directement mappées sur des valeurs ccTLD (« domaine de premier niveau ») à deux caractères, par exemple « uk » dans « co.uk ». Dans certains cas, la balise region prend également en charge les codes ISO-3166-1, qui parfois diffèrent des valeurs ccTLD (« GB » pour « Grande-Bretagne », par exemple).

Consultez les données de couverture de Google Maps pour savoir dans quelle mesure un pays prend en charge ces différents itinéraires.

Rendu d'itinéraires

Le lancement d'une requête d'itinéraire à DirectionsService avec la méthode route() nécessite de transmettre un rappel qui est exécuté à la fin de la requête de service. Ce rappel renvoie un code DirectionsResult et DirectionsStatus dans la réponse.

Statut de la requête d'itinéraire

DirectionsStatus peut renvoyer les valeurs suivantes :

  • OK indique que la réponse contient une valeur DirectionsResult valide.
  • NOT_FOUND indique qu'au moins l'un des points géographiques spécifiés dans le point de départ, la destination ou les points de cheminement de la requête n'a pas pu être géocodé.
  • ZERO_RESULTS indique qu'aucun itinéraire n'a pu être identifié entre le point de départ et la destination.
  • MAX_WAYPOINTS_EXCEEDED indique qu'un trop grand nombre de champs DirectionsWaypoint ont été fournis dans DirectionsRequest. Voir la section ci-dessous sur les limites applicables aux points de cheminement.
  • INVALID_REQUEST indique que la valeur DirectionsRequest fournie n'est pas valide. Ce code d'erreur est généralement le résultat de requêtes sans point de départ ou destination, ou est provoqué par des requêtes de transports en commun incluant des points de cheminement.
  • OVER_QUERY_LIMIT indique que la page Web a envoyé trop de requêtes au cours de la période autorisée.
  • REQUEST_DENIED indique que la page Web n'est pas autorisée à utiliser le service Directions.
  • UNKNOWN_ERROR indique qu'une requête d'itinéraire n'a pas pu être traitée en raison d'une erreur de serveur. Si vous essayez à nouveau, la requête pourrait aboutir.

Vous devez vous assurer que la requête d'itinéraire a renvoyé des résultats valides en vérifiant cette valeur avant de traiter le résultat.

Affichage de DirectionsResult

DirectionsResult contient le résultat d'une requête d'itinéraire, que vous pouvez gérer vous-même ou transmettre à un objet DirectionsRenderer, lequel peut gérer automatiquement l'affichage du résultat sur une carte.

Pour afficher un résultat DirectionsResult à l'aide de DirectionsRenderer, il vous suffit de procéder comme suit :

  1. Créez un objet DirectionsRenderer.
  2. Appelez setMap() sur le moteur de rendu pour le lier à la carte transmise.
  3. Appelez setDirections() sur le moteur de rendu, et transmettez cet élément à DirectionsResult comme précisé ci-dessus. Le moteur de rendu est un MVCObject, c'est pourquoi il détecte automatiquement toute modification de ses propriétés et met à jour la carte lorsque l'itinéraire associé a été modifié.

L'exemple suivant calcule l'itinéraire entre deux points géographiques sur la Route 66, où le point de départ et la destination sont définis par les valeurs "start" et "end" données dans les listes déroulantes. Le DirectionsRenderer gère l'affichage de la polyligne entre les points géographiques indiqués, et le positionnement de marqueurs au point de départ, à la destination et aux points de cheminement, le cas échéant.

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsDisplay.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsDisplay.setDirections(result);
    }
  });
}

Dans le corps HTML :

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

Voir l'exemple (directions-simple.html)

L'exemple suivant présente l'itinéraire à l'aide de plusieurs modes de transport entre Haight-Ashbury et Ocean Beach à San Francisco, en Californie :

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;
var haight = new google.maps.LatLng(37.7699298, -122.4469157);
var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsDisplay.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that Javascript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsDisplay.setDirections(response);
    }
  });
}

Dans le corps HTML :

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

Voir l'exemple (directions-travel-modes.html)

Un DirectionsRenderer prend non seulement en charge l'affichage de la polyligne et de tout marqueur associé, mais il peut également gérer l'affichage textuel de l'itinéraire sous forme d'une série d'étapes. Pour ce faire, il vous suffit d'appeler setPanel() sur votre DirectionsRenderer, en indiquant le <div> où vous voulez afficher ces informations. Ainsi, vous êtes sûr d'afficher les informations appropriées sur les droits d'auteur et les avertissements qui peuvent être associés au résultat.

Les itinéraires textuels seront renvoyés en utilisant le paramètre de langue défini pour le navigateur ou la langue spécifiée lors du chargement de l'API JavaScript au moyen du paramètre language. (Pour plus d'informations, voir Localisation.) Dans le cas des itinéraires en transports en commun, l'heure est affichée dans le fuseau horaire de cet arrêt de transport en commun.

L'exemple suivant est identique à celui affiché ci-dessus, mais il inclut un panneau <div> où afficher l'itinéraire :

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsDisplay.setMap(map);
  directionsDisplay.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsDisplay.setDirections(response);
    }
  });
}

Dans le corps HTML :

<div id="map" style="float:left;width:70%; height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height 100%"></div>

Voir l'exemple (directions-panel.html)

L'objet DirectionsResult

Lorsque vous envoyez une requête d'itinéraire à DirectionsService, vous recevez une réponse qui se compose d'un code de statut et d'un résultat sous forme d'objet DirectionsResult. DirectionsResult est un littéral objet contenant les champs suivants :

  • geocoded_waypoints[] contient un tableau d'objets DirectionsGeocodedWaypoint, où chaque objet comporte des détails sur le géocodage du point de départ, de la destination et des points de cheminement.
  • routes[] contient un tableau d'objets DirectionsRoute. Chaque itinéraire décrit une manière d'aller du point de départ à la destination dans DirectionsRequest. En général, seul un itinéraire est renvoyé pour toute requête, sauf si le champ provideRouteAlternatives de la requête est défini sur true. Dans ce cas, plusieurs itinéraires peuvent être affichés.

Points de cheminement d'itinéraire géocodés

DirectionsGeocodedWaypoint contient des détails sur le géocodage du point de départ, de la destination et des points de cheminement.

DirectionsGeocodedWaypoint est un littéral objet contenant les champs suivants :

  • geocoder_status indique le code de statut résultant de l'opération de géocodage. Ce champ peut contenir les valeurs suivantes :
    • "OK" indique qu'aucune erreur n'est survenue, que l'adresse a été analysée et qu'au moins un géocode a été trouvé.
    • "ZERO_RESULTS" indique que le géocode a réussi mais n'a renvoyé aucun résultat. Cela peut se produire si le géocodeur a reçu un paramètre address inexistant.
  • partial_match indique que le géocodeur n'a pas renvoyé de correspondance exacte pour la requête d'origine, mais qu'il a pu trouver une partie de l'adresse demandée. Nous vous recommandons d'examiner la requête d'origine pour vérifier qu'elle ne contient pas d'erreur de syntaxe et/ou que l'adresse est bien complète.

    Les correspondances partielles sont souvent renvoyées lorsque l'adresse postale n'existe pas dans la localité que vous avez indiquée dans la requête. Les correspondances partielles peuvent aussi être renvoyées lorsqu'une requête correspond à plusieurs lieux au sein de la même localité. Par exemple, « 21 Henr St, Bristol, UK » renvoie une correspondance partielle à la fois pour Henry Street et pour Henrietta Street. Notez que si une requête comprend un composant d'adresse mal saisi, le service de géocodage peut suggérer une autre adresse. Les suggestions déclenchées de cette façon sont également signalées comme des correspondances partielles.

  • place_id est l'identifiant unique d'un lieu et peut être utilisé avec d'autres API Google. Vous pouvez par exemple utiliser place_id avec la bibliothèque Google Places API pour obtenir des détails sur une entreprise locale, comme son numéro de téléphone, ses horaires d'ouverture, les avis des utilisateurs, etc. Voir la présentation des identifiants de lieu.
  • types[] est un tableau indiquant le type du résultat renvoyé. Ce tableau contient un ensemble de zéro, une ou plusieurs balises identifiant le type de caractéristique renvoyé dans le résultat. Par exemple, le géocode de Chicago renvoie « locality » qui indique que Chicago est une ville, et renvoie également « political » qui indique qu'il s'agit d'une entité politique.

Itinéraires Directions

L'ancien objet DirectionsTrip a été renommé DirectionsRoute. Notez qu'un itinéraire fait désormais référence à un trajet complet, du début à la fin de celui-ci, plutôt qu'à une section d'un trajet parent.

Un objet DirectionsRoute contient un seul résultat à partir du point de départ et de la destination spécifiés. Cet itinéraire peut se composer d'une ou de plusieurs sections (de type DirectionsLeg), en fonction des points de cheminement spécifiés le cas échéant. L'itinéraire contient également des informations relatives aux droits d'auteur et aux avertissements qui doivent être affichées à l'utilisateur en plus des informations d'itinéraire.

DirectionsRoute est un littéral objet contenant les champs suivants :

  • legs[] contient un tableau d'objets DirectionsLeg, où chaque objet comporte des informations sur une section de l'itinéraire, entre deux points géographiques de l'itinéraire donné. Une section séparée est présente pour chaque point de cheminement ou destination spécifiée. (Un itinéraire sans point de cheminement contient exactement une section DirectionsLeg.) Chaque section se compose d'une série d'objets DirectionStep.
  • waypoint_order contient un tableau indiquant l'ordre des points de cheminement de l'itinéraire calculé. Ce tableau peut contenir un ordre modifié si optimizeWaypoints: true a été défini pour DirectionsRequest.
  • overview_path contient un tableau d'éléments LatLng qui représentent un tracé approximatif (lissé) de l'itinéraire obtenu.
  • overview_polyline comporte un seul objet points qui contient une représentation sous forme de polyligne encodée de l'itinéraire. Cette polyligne est un tracé approximatif (lissé) de l'itinéraire obtenu.
  • bounds contient un élément LatLngBounds qui indique les limites de la polyligne le long de l'itinéraire.
  • copyrights contient le texte relatif aux droits d'auteur à afficher pour cet itinéraire.
  • warnings[] contient un tableau d'avertissements devant apparaître lorsque l'itinéraire est affiché. Si vous n'utilisez pas l'objet DirectionsRenderer fourni, vous devez gérer et afficher vous-même ces avertissements.
  • fare contient le coût total de l'itinéraire (c'est-à-dire le total des prix des billets). Cette propriété n'est renvoyée que pour les requêtes de transports en commun et uniquement si les informations tarifaires sont disponibles pour toutes les sections en transports en commun. Ces informations comprennent les données suivantes :
    • currency : Code de devise ISO 4217 qui indique la devise dans laquelle le montant est exprimé.
    • value : Prix total, exprimé dans la devise spécifiée ci-dessus.

Sections d'itinéraire

L'ancien objet DirectionsRoute a été renommé DirectionsLeg.

Un objet DirectionsLeg spécifie une section unique d'un trajet allant du point de départ à la destination dans l'itinéraire calculé. Les itinéraires sans point de cheminement se composent d'une seule « section ». En revanche, les itinéraires où un ou plusieurs points de cheminement sont définis se composent d'une ou de plusieurs sections de trajet.

DirectionsLeg est un littéral objet contenant les champs suivants :

  • steps[] contient un tableau d'objets DirectionsStep comportant des informations sur chaque étape de la section du trajet.
  • distance indique la distance totale couverte par cette section, en tant qu'objet Distance sous la forme suivante :

    • value indique la distance en mètres.
    • text contient une représentation sous forme de chaîne de la distance, affichée par défaut dans les unités utilisées au point de départ. Par exemple, des miles sont utilisés pour tout point de départ aux États-Unis. Vous pouvez modifier ce système d'unités en définissant spécifiquement un UnitSystem dans la requête d'origine. Notez que, quel que soit le système d'unités utilisé, le champ distance.value contient toujours une valeur exprimée en mètres.

    Ce champ peut être non défini si la distance est inconnue.

  • duration indique la durée totale de cette section, en tant qu'objet Duration sous la forme suivante :

    • value indique la durée en secondes.
    • text contient une représentation sous forme de chaîne de la durée.

    Ces champs peuvent être non définis si la durée est inconnue.

  • duration_in_traffic indique la durée totale de la section, en tenant compte de l'état du trafic actuel. La valeur duration_in_traffic n'est renvoyée que si toutes les conditions suivantes sont remplies :

    • La requête inclut un ID client Google Maps APIs Premium Plan valide.
    • La requête n'inclut pas de points de cheminement avec arrêt. En d'autres termes, elle ne contient aucun point de cheminement dont le champ stopover est défini sur true.
    • La requête porte spécifiquement sur un itinéraire en voiture (le champ mode est défini sur driving).
    • Le champ departureTime est inclus dans le champ drivingOptions de la requête.
    • L'état du trafic est disponible pour l'itinéraire demandé.

    L'élément duration_in_traffic se compose des champs suivants :

    • value indique la durée en secondes.
    • text contient une représentation lisible de la durée.
  • arrival_time contient l'heure d'arrivée prévue pour la section. Cette propriété est renvoyée uniquement pour les itinéraires en transports en commun. Le résultat est renvoyé sous forme d'objet Time avec trois propriétés :
    • value est l'heure spécifiée en tant qu'objet Date JavaScript.
    • text est l'heure spécifiée sous forme de chaîne. L'heure est affichée dans le fuseau horaire de l'arrêt du transport en commun.
    • time_zone contient le fuseau horaire de cet arrêt. La valeur est le nom du fuseau horaire tel qu'il est défini dans la base de données des fuseaux horaires de l'IANA. Par exemple, « America/New_York ».
  • departure_time contient l'heure de départ prévue pour la section, spécifiée sous la forme d'un objet Time. Le champ departure_time est uniquement disponible pour les itinéraires en transports en commun.
  • start_location contient les coordonnées LatLng du point de départ de la section. Étant donné que le service Web Directions calcule l'itinéraire entre des points géographiques en utilisant l'option de transport la plus proche (généralement une route) au point de départ et à la destination, le champ start_location peut différer du point de départ fourni pour la section si, par exemple, aucune route ne se trouve à proximité de celui-ci.
  • end_location contient les coordonnées LatLng de la destination de la section. Étant donné que DirectionsService calcule l'itinéraire entre des points géographiques en utilisant l'option de transport la plus proche (généralement une route) au point de départ et à la destination, le champ end_location peut différer de la destination fournie pour la section si, par exemple, aucune route ne se trouve à proximité de celle-ci.
  • start_address contient l'adresse lisible (généralement une adresse postale) du début de la section.
  • end_address contient l'adresse lisible (généralement une adresse postale) de la fin de la section.

Étapes d'itinéraire

Une DirectionsStep est l'unité la plus petite d'un itinéraire et décrit une instruction unique et spécifique sur le trajet. Par exemple, « Tourner à gauche à W. 4th St. » Cette étape décrit non seulement l'instruction mais contient également des informations de distance et de durée concernant la relation entre cette étape et la suivante. Par exemple, une étape telle que « S'insérer sur l'I-80 West » peut contenir une durée de « 37 miles » et de « 40 minutes », indiquant que l'étape suivante se trouve à 37 miles/40 minutes de l'étape actuelle.

Lorsque vous utilisez le service Directions pour rechercher un itinéraire en transports en commun, le tableau d'étapes inclut des informations spécifiques sur les transports en commun supplémentaires, sous la forme d'un objet transit. Si l'itinéraire inclut plusieurs modes de transport, des indications détaillées sont fournies pour les étapes à pied ou en voiture dans un tableau steps[]. Par exemple, une étape à pied inclut des indications à partir des points de départ et de destination : « Marcher jusqu'à Innes Avenue et Fitch Street. » Cette étape inclut des indications à pied détaillées pour cet itinéraire dans le tableau steps[] comme : « Prendre la direction nord-est. », « Prendre à gauche sur Arelious Walker » et « Prendre à gauche sur Innes Avenue. »

DirectionsStep est un littéral objet contenant les champs suivants :

  • instructions contient des instructions pour cette étape dans une chaîne de texte.
  • distance contient la distance couverte par cette étape jusqu'à l'étape suivante, sous forme d'objet Distance. (Voir la description dans DirectionsLeg ci-dessus.) Ce champ peut être non défini si la distance est inconnue.
  • duration contient une estimation de la durée nécessaire pour effectuer l'étape, jusqu'à l'étape suivante, sous la forme d'un objet Duration. (Voir la description dans DirectionsLeg ci-dessus.) Ce champ peut être non défini si la durée est inconnue.
  • start_location contient les coordonnées LatLng géocodées du point de départ de l'étape.
  • end_location contient les coordonnées LatLng de la destination de l'étape.
  • polyline comporte un seul objet points qui contient une représentation sous forme de polyligne encodée de l'étape. Cette polyligne est un tracé approximatif (lissé) de l'étape.
  • steps[] est un littéral objet DirectionsStep qui contient des indications détaillées sur les étapes à pied ou en voiture dans les itinéraires en transports en commun. Les sous-étapes sont uniquement disponibles pour les itinéraires en transports en commun.
  • travel_mode contient le TravelMode utilisé dans cette étape. Les itinéraires en transports en commun peuvent inclure une combinaison d'itinéraires à pied et en transports en commun.
  • path contient un tableau de LatLngs décrivant le tracé de l'étape.
  • transit contient des informations spécifiques aux transports en commun, comme les heures de départ et d'arrivée, et le nom de la ligne de transport.

Informations spécifiques aux transports en commun

Les itinéraires en transports en commun renvoient des informations supplémentaires qui ne sont pas pertinentes pour les autres modes de transport. Ces propriétés supplémentaires sont détaillées dans l'objet TransitDetails, renvoyé sous forme de propriété de DirectionsStep. À partir de l'objet TransitDetails, vous pouvez accéder à des informations supplémentaires pour les objets TransitStop, TransitLine, TransitAgency et VehicleType décrits ci-après.

Détails sur les transports en commun

L'objet TransitDetails présente les propriétés suivantes :

  • arrival_stop contient un objet TransitStop qui représente la station ou l'arrêt d'arrivée avec les propriétés suivantes :
    • name est le nom de la station ou de l'arrêt du transport en commun. Par exemple, « Union Square ».
    • location est la localisation de la station ou de l'arrêt du transport en commun, représentée par des coordonnées LatLng.
  • departure_stop contient un objet TransitStop qui représente la station ou l'arrêt de départ.
  • arrival_time contient l'heure d'arrivée, spécifiée en tant qu'objet Time avec trois propriétés :
    • value est l'heure spécifiée en tant qu'objet Date JavaScript.
    • text est l'heure spécifiée sous forme de chaîne. L'heure est affichée dans le fuseau horaire de l'arrêt du transport en commun.
    • time_zone contient le fuseau horaire de cet arrêt. La valeur est le nom du fuseau horaire tel qu'il est défini dans la base de données des fuseaux horaires de l'IANA. Par exemple, « America/New_York ».
  • departure_time contient l'heure de départ, spécifiée en tant qu'objet Time.
  • headsign spécifie la direction de voyage sur la ligne, telle qu'elle est signalée sur le véhicule ou à l'arrêt de départ. Il s'agit souvent du terminus.
  • headway spécifie, lorsqu'il est disponible, le nombre de secondes prévues entre les départs depuis le même arrêt à l'heure actuelle. Par exemple, si la valeur headway est de 600, une attente de dix minutes est prévue si vous ratez votre bus.
  • line contient un littéral objet TransitLine qui contient des informations sur la ligne de transport en commun utilisée pour cette étape. Le littéral objet TransitLine fournit le nom et l'exploitant de la ligne, ainsi que d'autres propriétés décrites dans la documentation de référence TransitLine.
  • num_stops contient le nombre d'arrêts de l'étape. L'arrêt d'arrivée est inclus mais pas celui de départ. Par exemple, si votre itinéraire consiste à monter à l'arrêt A, à passer par les arrêts B et D, et à descendre à l'arrêt D, num_stops renvoie 3.

Ligne de transport en commun

L'objet TransitLine présente les propriétés suivantes :

  • name contient le nom complet de la ligne de transport en commun. Par exemple, « 7 Avenue Express » ou « 14th Street Crosstown ».
  • short_name contient le nom court de la ligne de transport en commun. Il s'agit généralement d'un numéro de ligne, comme « 2 » ou « M14 ».
  • agencies contient un tableau de type TransitAgency. Chaque objet TransitAgency fournit des informations sur l'exploitant de la ligne, y compris les propriétés suivantes :
    • name contient le nom de la société de transports en commun.
    • url contient l'URL de la société de transports en commun.
    • phone contient le numéro de téléphone de la société de transports en commun.

    Si vous effectuez le rendu d'itinéraires en transports en commun manuellement au lieu d'utiliser l'objet DirectionsRenderer, vous devez afficher les noms et les URL des sociétés de transports en commun desservant les résultats du trajet.

  • url contient l'URL de la ligne de transport fournie par la société de transports en commun.
  • icon contient l'URL de l'icône associée à la ligne. La plupart des villes utilisent des icônes génériques qui varient selon le type de véhicule. Certaines lignes de transport en commun ont des icônes spécifiques, comme le système de métro de New York.
  • color contient la couleur généralement utilisée pour signaliser ce transport en commun. La couleur est spécifiée par une chaîne hexadécimale comme #FF0033.
  • text_color contient la couleur de texte généralement utilisée pour la signalisation de la ligne. La couleur est spécifiée par une chaîne hexadécimale.
  • vehicle contient un objet Vehicle qui inclut les propriétés suivantes :
    • name contient le nom du véhicule sur cette ligne. Par exemple, « Subway » (métro).
    • type contient le type de véhicule utilisé sur cette ligne. Voir la documentation sur le type de véhicule pour consulter la liste complète des valeurs prises en charge.
    • icon contient l'URL de l'icône généralement associée à ce type de véhicule.
    • local_icon contient l'URL de l'icône associée à ce type de véhicule, en fonction de la signalisation de transport locale.

Type de véhicule

L'objet VehicleType présente les propriétés suivantes :

Valeur Définition
VehicleType.RAIL Transport ferroviaire.
VehicleType.METRO_RAIL Métro léger.
VehicleType.SUBWAY Métro léger souterrain.
VehicleType.TRAM Train léger en surface (tramway).
VehicleType.MONORAIL Monorail.
VehicleType.HEAVY_RAIL Métro.
VehicleType.COMMUTER_TRAIN Réseau ferré de banlieue.
VehicleType.HIGH_SPEED_TRAIN Train à grande vitesse.
VehicleType.BUS Bus.
VehicleType.INTERCITY_BUS Bus interurbain.
VehicleType.TROLLEYBUS Trolleybus.
VehicleType.SHARE_TAXI Type de bus pouvant faire monter et descendre des passagers n'importe où sur la ligne.
VehicleType.FERRY Ferry.
VehicleType.CABLE_CAR Véhicule tracté par un câble, généralement en surface. Lorsqu'ils sont aériens, ces véhicules peuvent être de type GONDOLA_LIFT (télécabine).
VehicleType.GONDOLA_LIFT Télécabine.
VehicleType.FUNICULAR Véhicule tracté par un câble le long d'une pente prononcée. Un funiculaire se compose généralement de deux rames, chacune agissant comme contrepoids de l'autre.
VehicleType.OTHER Ce type est renvoyé pour tous les autres véhicules.

Examen de DirectionsResults

Les composants de DirectionsResults, à savoir DirectionsRoute, DirectionsLeg, DirectionsStep et TransitDetails, peuvent être examinés et utilisés lors de l'analyse des réponses d'itinéraire.

Important : Si vous effectuez le rendu d'itinéraires en transports en commun manuellement au lieu d'utiliser l'objet DirectionsRenderer, vous devez afficher les noms et les URL des sociétés de transports en commun desservant les résultats du trajet.

L'exemple suivant retrace l'itinéraire à pied vers certaines attractions touristiques à New York. Nous examinons le composant DirectionsStep du trajet pour ajouter des marqueurs pour chaque étape et nous joignons des informations à une fenêtre InfoWindow contenant des instructions textuelles pour chaque étape.

Étant donné que nous calculons un itinéraire à pied, nous affichons également des avertissements dans un panneau <div> séparé.

var map;
var directionsDisplay;
var directionsService;
var stepDisplay;
var markerArray = [];

function initialize() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsDisplay = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsDisplay.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

Dans le corps HTML :

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

Voir l'exemple (directions-complex.html)

Utilisation des points de cheminement dans les itinéraires

Comme nous l'avons précisé dans DirectionsRequest, vous pouvez également spécifier des points de cheminement (de type DirectionsWaypoint) lors du calcul d'itinéraires en utilisant le service Directions pour les trajets à pied, à vélo ou en voiture. Les points de cheminement ne sont pas disponibles pour les itinéraires en transports en commun. Les points de cheminement vous permettent de calculer des trajets via des points géographiques supplémentaires, auquel cas l'itinéraire renvoyé passe par les points de cheminement fournis.

Un waypoint est composé des champs suivants :

  • location (obligatoire) spécifie l'adresse du point de cheminement.
  • stopover (facultatif) indique si ce point de cheminement est un arrêt effectif sur le trajet (true) ou simplement le souhait de passer par le point géographique indiqué (false). Les arrêts (stopover) sont définis sur true par défaut.

Par défaut, le service Directions calcule un itinéraire passant par les points de cheminement dans l'ordre fourni. Vous pouvez également spécifier optimizeWaypoints: true dans DirectionsRequest afin de permettre au service Directions d'optimiser l'itinéraire fourni en réorganisant les points de cheminement dans un ordre plus efficace. (Cette optimisation est une application du problème du voyageur de commerce.) La durée du trajet est le principal facteur optimisé, mais d'autres facteurs (tels que la distance, le nombre de bifurcations et bien d'autres) peuvent être pris en compte lors du choix de l'itinéraire le plus rapide. Tous les points de cheminement doivent être des arrêts pour que le service Directions optimise l'itinéraire.

Si vous demandez au service Directions d'optimiser l'ordre de ses points de cheminement, leur ordre est renvoyé dans le champ waypoint_order de l'objet DirectionsResult.

L'exemple suivant calcule des itinéraires traversant les États-Unis à l'aide de divers points de départ, destinations et points de cheminement. (Pour sélectionner plusieurs points de cheminement, appuyez sur Ctrl-clic lorsque vous choisissez des éléments dans la liste.) Notez que nous examinons les éléments routes.start_address et routes.end_address afin de disposer du texte pour chaque point de départ et chaque destination de l'itinéraire.

function initMap() {
  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer;
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 6,
    center: {lat: 41.85, lng: -87.65}
  });
  directionsDisplay.setMap(map);

  document.getElementById('submit').addEventListener('click', function() {
    calculateAndDisplayRoute(directionsService, directionsDisplay);
  });
}

function calculateAndDisplayRoute(directionsService, directionsDisplay) {
  var waypts = [];
  var checkboxArray = document.getElementById('waypoints');
  for (var i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true
      });
    }
  }

  directionsService.route({
    origin: document.getElementById('start').value,
    destination: document.getElementById('end').value,
    waypoints: waypts,
    optimizeWaypoints: true,
    travelMode: 'DRIVING'
  }, function(response, status) {
    if (status === 'OK') {
      directionsDisplay.setDirections(response);
      var route = response.routes[0];
      var summaryPanel = document.getElementById('directions-panel');
      summaryPanel.innerHTML = '';
      // For each route, display summary information.
      for (var i = 0; i < route.legs.length; i++) {
        var routeSegment = i + 1;
        summaryPanel.innerHTML += '<b>Route Segment: ' + routeSegment +
            '</b><br>';
        summaryPanel.innerHTML += route.legs[i].start_address + ' to ';
        summaryPanel.innerHTML += route.legs[i].end_address + '<br>';
        summaryPanel.innerHTML += route.legs[i].distance.text + '<br><br>';
      }
    } else {
      window.alert('Directions request failed due to ' + status);
    }
  });
}
<div id="map"></div>
<div id="right-panel">
<div>
<b>Start:</b>
<select id="start">
  <option value="Halifax, NS">Halifax, NS</option>
  <option value="Boston, MA">Boston, MA</option>
  <option value="New York, NY">New York, NY</option>
  <option value="Miami, FL">Miami, FL</option>
</select>
<br>
<b>Waypoints:</b> <br>
<i>(Ctrl+Click or Cmd+Click for multiple selection)</i> <br>
<select multiple id="waypoints">
  <option value="montreal, quebec">Montreal, QBC</option>
  <option value="toronto, ont">Toronto, ONT</option>
  <option value="chicago, il">Chicago</option>
  <option value="winnipeg, mb">Winnipeg</option>
  <option value="fargo, nd">Fargo</option>
  <option value="calgary, ab">Calgary</option>
  <option value="spokane, wa">Spokane</option>
</select>
<br>
<b>End:</b>
<select id="end">
  <option value="Vancouver, BC">Vancouver, BC</option>
  <option value="Seattle, WA">Seattle, WA</option>
  <option value="San Francisco, CA">San Francisco, CA</option>
  <option value="Los Angeles, CA">Los Angeles, CA</option>
</select>
<br>
  <input type="submit" id="submit">
</div>
<div id="directions-panel"></div>
</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%;
  float: left;
  width: 70%;
  height: 100%;
}
#right-panel {
  margin: 20px;
  border-width: 2px;
  width: 20%;
  height: 400px;
  float: left;
  text-align: left;
  padding-top: 0;
}
#directions-panel {
  margin-top: 10px;
  background-color: #FFEE77;
  padding: 10px;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer;
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 6,
    center: {lat: 41.85, lng: -87.65}
  });
  directionsDisplay.setMap(map);

  document.getElementById('submit').addEventListener('click', function() {
    calculateAndDisplayRoute(directionsService, directionsDisplay);
  });
}

function calculateAndDisplayRoute(directionsService, directionsDisplay) {
  var waypts = [];
  var checkboxArray = document.getElementById('waypoints');
  for (var i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true
      });
    }
  }

  directionsService.route({
    origin: document.getElementById('start').value,
    destination: document.getElementById('end').value,
    waypoints: waypts,
    optimizeWaypoints: true,
    travelMode: 'DRIVING'
  }, function(response, status) {
    if (status === 'OK') {
      directionsDisplay.setDirections(response);
      var route = response.routes[0];
      var summaryPanel = document.getElementById('directions-panel');
      summaryPanel.innerHTML = '';
      // For each route, display summary information.
      for (var i = 0; i < route.legs.length; i++) {
        var routeSegment = i + 1;
        summaryPanel.innerHTML += '<b>Route Segment: ' + routeSegment +
            '</b><br>';
        summaryPanel.innerHTML += route.legs[i].start_address + ' to ';
        summaryPanel.innerHTML += route.legs[i].end_address + '<br>';
        summaryPanel.innerHTML += route.legs[i].distance.text + '<br><br>';
      }
    } else {
      window.alert('Directions request failed due to ' + status);
    }
  });
}

Voir l'exemple (directions-waypoints.html)

Limites et restrictions applicables aux points de cheminement

Les points de cheminement sont soumis aux restrictions et limites d'utilisation suivantes :

  • Lorsque le service Directions est utilisé dans Google Maps JavaScript API, le nombre maximum de points de cheminement autorisés est de 23, en plus du point de départ et de la destination. Les limites sont identiques pour le service Web Google Maps Directions API.
  • Pour le service Web Google Maps Directions API, les clients peuvent utiliser 23 points de cheminement, en plus du point de départ et de la destination.
  • Les clients Google Maps APIs Premium Plan peuvent utiliser 23 points de cheminement, plus le point de départ et la destination.
  • Les points de cheminement ne sont pas pris en charge pour les itinéraires en transports en commun.

Itinéraires déplaçables

Les utilisateurs peuvent modifier des itinéraires à vélo, à pied ou en voiture affichés en utilisant un DirectionsRenderer dynamiquement s'ils sont déplaçables. Les utilisateurs peuvent ainsi sélectionner et modifier des itinéraires en cliquant et en faisant glisser les tracés obtenus sur la carte. Pour indiquer si l'affichage d'un moteur de rendu autorise les itinéraires déplaçables, définissez sa propriété draggable sur true. Les itinéraires en transports en commun ne peuvent pas être rendus déplaçables.

Lorsqu'un itinéraire est déplaçable, l'utilisateur peut sélectionner n'importe quel point (ou point de cheminement) sur le tracé du résultat affiché et déplacer le composant indiqué jusqu'à une nouvelle localisation. Le DirectionsRenderer effectue une mise à jour de manière dynamique pour afficher le tracé modifié. Lorsque l'utilisateur relâche, un point de cheminement transitoire est ajouté à la carte (indiqué par un petit marqueur blanc). La sélection et le déplacement d'un segment du tracé modifient cette section de l'itinéraire, alors que la sélection et le déplacement d'un marqueur de point de cheminement (y compris les points de départ et les destinations) modifient les sections de l'itinéraire passant par ce point de cheminement.

Les itinéraires déplaçables étant modifiés et rendus côté client, il est conseillé de surveiller et de gérer l'événement directions_changed sur DirectionsRenderer afin d'être notifié lorsqu'un utilisateur a modifié l'itinéraire affiché.

Le code ci-dessous affiche un trajet de Perth (côte ouest de l'Australie) à Sydney (côte est). Le code surveille l'événement directions_changed pour mettre à jour la distance totale de toutes les sections du voyage.

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

  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer({
    draggable: true,
    map: map,
    panel: document.getElementById('right-panel')
  });

  directionsDisplay.addListener('directions_changed', function() {
    computeTotalDistance(directionsDisplay.getDirections());
  });

  displayRoute('Perth, WA', 'Sydney, NSW', directionsService,
      directionsDisplay);
}

function displayRoute(origin, destination, service, display) {
  service.route({
    origin: origin,
    destination: destination,
    waypoints: [{location: 'Adelaide, SA'}, {location: 'Broken Hill, NSW'}],
    travelMode: 'DRIVING',
    avoidTolls: true
  }, function(response, status) {
    if (status === 'OK') {
      display.setDirections(response);
    } else {
      alert('Could not display directions due to: ' + status);
    }
  });
}

function computeTotalDistance(result) {
  var total = 0;
  var myroute = result.routes[0];
  for (var i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }
  total = total / 1000;
  document.getElementById('total').innerHTML = total + ' km';
}
<div id="map"></div>
<div id="right-panel">
  <p>Total Distance: <span id="total"></span></p>
</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%;
  float: left;
  width: 63%;
  height: 100%;
}
#right-panel {
  float: right;
  width: 34%;
  height: 100%;
}
.panel {
  height: 100%;
  overflow: auto;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -24.345, lng: 134.46}  // Australia.
  });

  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer({
    draggable: true,
    map: map,
    panel: document.getElementById('right-panel')
  });

  directionsDisplay.addListener('directions_changed', function() {
    computeTotalDistance(directionsDisplay.getDirections());
  });

  displayRoute('Perth, WA', 'Sydney, NSW', directionsService,
      directionsDisplay);
}

function displayRoute(origin, destination, service, display) {
  service.route({
    origin: origin,
    destination: destination,
    waypoints: [{location: 'Adelaide, SA'}, {location: 'Broken Hill, NSW'}],
    travelMode: 'DRIVING',
    avoidTolls: true
  }, function(response, status) {
    if (status === 'OK') {
      display.setDirections(response);
    } else {
      alert('Could not display directions due to: ' + status);
    }
  });
}

function computeTotalDistance(result) {
  var total = 0;
  var myroute = result.routes[0];
  for (var i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }
  total = total / 1000;
  document.getElementById('total').innerHTML = total + ' km';
}

Voir l'exemple (directions-draggable.html)

Envoyer des commentaires concernant…

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