Service Directions

Présentation

Vous pouvez calculer un itinéraire (avec différents modes de transport) à l'aide de l'objet DirectionsService. Cet objet communique avec le service Directions de l'API Google Maps, qui reçoit les requêtes d'itinéraire et renvoie un chemin efficace. Le temps de trajet est le principal facteur optimisé, mais d'autres critères tels que la distance, le nombre de changements de direction et bien d'autres peuvent être pris en compte. Vous pouvez gérer ces résultats d'itinéraire vous-même ou utiliser l'objet DirectionsRenderer pour les afficher.

Lorsque vous spécifiez 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, États-Unis" ou "Darwin, Territoire du Nord, Australie"), une valeur LatLng ou un objet Place.

Le service Directions peut renvoyer des itinéraires multi-segments passant par une série de points de cheminement. L'itinéraire s'affiche sous la forme d'une polyligne sur la carte et d'une série de descriptions textuelles dans un élément <div> (par exemple, "Prendre à droite sur Rue Charles Dickens").

Premiers pas

Avant d'utiliser le service Directions dans l'API Maps JavaScript, assurez-vous d'abord que l'API Directions est activée dans la console Google Cloud, dans le même projet que celui configuré pour l'API Maps JavaScript.

Pour afficher la liste des API activées :

  1. Accédez à la console Google Cloud.
  2. Cliquez sur le bouton Sélectionner un projet, sélectionnez le projet que vous avez configuré pour l'API Maps JavaScript, puis cliquez sur Ouvrir.
  3. Dans la liste des API du tableau de bord, repérez l'API Directions.
  4. Si vous trouvez l'API dans la liste, vous pouvez continuer. Si l'API ne figure pas dans la liste, activez-la :
    1. En haut de la page, sélectionnez ACTIVER L'API pour afficher l'onglet Bibliothèque. Vous pouvez également sélectionner Bibliothèque dans le menu de gauche.
    2. Recherchez l'API Directions, puis sélectionnez-la dans la liste des résultats.
    3. Sélectionnez ACTIVER. Une fois le processus terminé, l'API Directions apparaît dans la liste des API du tableau de bord.

Tarifs et règles

Tarifs

Le 16 juillet 2018, un nouveau forfait de type paiement à l'usage est entré en vigueur pour les services Maps, Routes et Places. Pour en savoir plus sur les nouveaux tarifs et les nouvelles limites d'utilisation du service JavaScript Directions, consultez la page Utilisation et facturation de l'API Directions.

Règles

Le service Directions doit être utilisé conformément aux Règles de l'API Directions.

Requêtes d'itinéraires

Étant donné que l'API Google Maps doit appeler un serveur externe, l'accès au service Directions est asynchrone. Pour cette raison, vous devez transmettre 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 afficher plusieurs itinéraires possibles sous la forme d'un tableau routes[] d'éléments distincts.

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

Le littéral d'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,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

Ces champs sont décrits ci-dessous :

  • origin (obligatoire) spécifie le lieu de départ à partir duquel l'itinéraire doit être calculé. Cette valeur peut être spécifiée en tant que String (par exemple, "Paris Île-de-France"), en tant que valeur LatLng ou en tant qu'objet Place. Si vous utilisez un objet Place, vous pouvez spécifier un ID de lieu, une chaîne de requête ou un emplacement LatLng. Vous pouvez obtenir les ID de lieu via les services Geocoding, Place Search et Place Autocomplete dans l'API Maps JavaScript. Pour obtenir un exemple d'utilisation des ID de lieu de Place Autocomplete, consultez Place Autocomplete et Directions.
  • destination (obligatoire) indique la destination vers laquelle l'itinéraire est calculé. Les options sont identiques à celles du champ origin décrit 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 qui ne s'appliquent qu'aux requêtes pour lesquelles travelMode correspond à TRANSIT. Les valeurs valides sont décrites dans la section Options de transports en commun ci-dessous.
  • drivingOptions (facultatif) spécifie les valeurs qui ne s'appliquent qu'aux requêtes pour lesquelles travelMode correspond à DRIVING. Les valeurs valides sont décrites dans la section Options d'itinéraire en voiture ci-dessous.

  • unitSystem (facultatif) spécifie le système d'unités à utiliser pour afficher les 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 lieux indiqués. Un point de cheminement est spécifié en tant que littéral d'objet avec les champs présentés ci-dessous :

    • location spécifie l'emplacement du point de cheminement sous forme de LatLng, d'objet Place ou de String qui sera géocodé.
    • stopover est un booléen qui indique que le point de cheminement est un arrêt sur l'itinéraire qui est alors divisé en deux.

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

  • optimizeWaypoints (facultatif) spécifie que l'itinéraire utilisant les (waypoints) fournis peut être optimisé en réorganisant les points de cheminement dans un ordre plus judicieux. Si la valeur est true, le service Directions renvoie les waypoints réorganisés dans un champ waypoint_order. (Pour en savoir plus, consultez Utiliser des points de cheminement dans les itinéraires ci-dessous.)
  • provideRouteAlternatives (facultatif) défini sur true indique que le service Directions peut fournir plusieurs itinéraires alternatifs dans la réponse. Notez que le calcul d'itinéraires alternatifs peut augmenter le temps de réponse du serveur. Cette option n'est disponible que pour les requêtes sans points de cheminement intermédiaires.
  • avoidFerries (facultatif) défini sur true indique que le ou les itinéraires calculés doivent éviter les ferries, si possible.
  • avoidHighways (facultatif) défini sur true indique que le ou les itinéraires calculés doivent, si possible, éviter les grands axes.
  • avoidTolls (facultatif) défini sur true indique que le ou les itinéraires calculés doivent éviter les routes à péage, si possible.
  • region (facultatif) spécifie le code régional sous la forme d'une valeur ccTLD (TLD pour top-level domain, domaine de premier niveau) à deux caractères. (Pour en savoir plus, consultez Ajuster l'itinéraire en fonction de la région ci-dessous.)

Voici un exemple de DirectionsRequest :

{
  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 un itinéraire, vous devez spécifier le mode de transport à utiliser. Actuellement, les modes de transport suivants sont pris en charge :

  • DRIVING (par défaut) indique un itinéraire en voiture standard via le réseau routier.
  • BICYCLING demande un itinéraire à vélo via les pistes cyclables et les rues à privilégier.
  • TRANSIT demande un itinéraire via les réseaux de transports en commun.
  • WALKING demande un itinéraire à pied via les voies piétonnes et les trottoirs.

Consultez les détails de la couverture Google Maps Platform pour savoir dans quelle mesure les itinéraires sont disponibles dans un pays. Si vous demandez un type d'itinéraire qui n'est pas disponible dans la région, la réponse renvoie DirectionsStatus="ZERO_RESULTS".

Remarque : Les itinéraires à pied n'incluront peut-être pas de voies piétonnes claires. Ils renvoient donc des avertissements dans le DirectionsResult. Ces avertissements doivent toujours s'afficher. Si vous n'utilisez pas la valeur par défaut DirectionsRenderer, vous devez vérifier que les avertissements s'affichent.

Options de transports en commun

Les options disponibles pour les requêtes d'itinéraire dépendent du mode de transport. Lorsque vous demandez un 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 d'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 d'objet TransitOptions contient les champs suivants :

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

Ces champs sont décrits ci-dessous :

  • arrivalTime (facultatif) spécifie 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) spécifie l'heure de départ souhaitée en tant qu'objet Date. departureTime sera ignoré si arrivalTime est spécifié. La valeur par défaut est "now" (c'est-à-dire l'heure actuelle) si aucune valeur n'est spécifiée pour departureTime ni arrivalTime.
  • modes[] (facultatif) est un tableau contenant un ou plusieurs littéraux d'objet TransitMode. Vous ne pouvez inclure ce champ que si la requête comprend une clé API. Chaque TransitMode spécifie un mode de transport à privilégier. 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 pour les itinéraires en transports en commun. Cette option vous permet d'ajuster 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é API. Les valeurs suivantes sont autorisées :
    • FEWER_TRANSFERS indique que l'itinéraire calculé doit utiliser un nombre limité de correspondances.
    • LESS_WALKING indique que l'itinéraire calculé doit limiter le plus possible la marche.

Voici un exemple de DirectionsRequest en transports en commun :

{
  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 en voiture

Vous pouvez spécifier des options pour les itinéraires en voiture via l'objet DrivingOptions.

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 d'objet drivingOptions soit valide) spécifie 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, mais pas 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 du forfait Premium Google Maps Platform, si vous incluez departureTime dans la requête, l'API renvoie le meilleur itinéraire en fonction des conditions de circulation prévues à l'heure indiquée et inclut le temps de trajet (duration_in_traffic) dans la réponse. Si vous ne spécifiez pas d'heure de départ (si la requête n'inclut pas drivingOptions), l'itinéraire renvoyé est satisfaisant de manière générale. Les conditions de circulation ne sont pas prises en compte.
  • trafficModel (facultatif) spécifie les hypothèses à utiliser pour calculer le temps de trajet. Ce paramètre influe sur la valeur renvoyée dans le champ duration_in_traffic de la réponse, qui contient le temps de trajet prévu en fonction des moyennes historiques. La valeur par défaut est bestguess. Les valeurs suivantes sont autorisées :
    • bestguess (par défaut) indique que le duration_in_traffic renvoyé doit correspondre à la meilleure estimation du temps de trajet compte tenu des conditions de circulation historiques et en temps réel. Plus departureTime est proche de l'heure actuelle, plus la circulation en temps réel devient importante.
    • pessimistic indique que le duration_in_traffic renvoyé doit être supérieur à la durée réelle du trajet la plupart du temps. Toutefois, les jours où la circulation est particulièrement difficile, le temps de trajet peut être plus long.
    • optimistic indique que la duration_in_traffic renvoyée doit être inférieure à la durée réelle du trajet la plupart du temps. Toutefois, les jours où la circulation est particulièrement fluide, le temps de trajet peut être plus court.

Vous trouverez ci-dessous 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 : lorsque le lieu de départ est exprimé à l'aide de coordonnées de latitude/longitude au lieu d'adresses, les unités métriques sont toujours utilisées par défaut.) Par exemple, un itinéraire de "Chicago, Illinois" à "Toronto, Ontario" affichera les résultats en miles, tandis que l'itinéraire inverse les affichera en kilomètres. Vous pouvez ignorer ce système d'unités en définissant explicitement celui que vous souhaitez utiliser dans la requête à l'aide de 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'influe que sur le texte présenté à l'utilisateur. Le résultat de l'itinéraire contient également des valeurs de distance, non présentées à l'utilisateur, qui sont toujours exprimées en mètres.

Ajuster l'itinéraire en fonction de la région

Le service Directions de l'API Google Maps renvoie des résultats d'adresses qui dépendent du domaine (région ou pays) à partir duquel vous avez chargé le bootstrap JavaScript. (Étant donné que la plupart des utilisateurs chargent https://maps.googleapis.com/, un domaine implicite est défini sur les États-Unis.) Si vous chargez le bootstrap depuis un autre domaine pris en charge, vous obtiendrez des résultats ajustés en conséquence. Par exemple, les recherches "San Francisco" peuvent renvoyer des résultats différents dans les applications qui chargent https://maps.googleapis.com/ (États-Unis) et http://maps.google.es/ (Espagne).

Vous pouvez ajuster les résultats du service Directions en fonction d'une région spécifique à l'aide du paramètre region. Ce paramètre prend un code de région, spécifié comme sous-tag de région à deux caractères (non numériques) Unicode. Dans la plupart des cas, ces tags sont directement mappés sur des valeurs ccTLD (domaine de premier niveau) à deux caractères telles que "uk" dans "co.uk". Dans certains cas, le tag region prend également en charge les codes ISO-3166-1, qui diffèrent parfois des valeurs ccTLD ("GB" pour "Grande-Bretagne", par exemple).

Lorsque vous utilisez le paramètre region :

  • Ne spécifiez qu'un seul pays ou qu'une seule région. Les valeurs multiples sont ignorées et peuvent entraîner l'échec de la requête.
  • N'utilisez que des sous-tags de région à deux caractères (format CLDR Unicode). Toutes les autres entrées entraîneront des erreurs.

L'ajustement en fonction de la région n'est disponible que pour les pays et régions dans lesquels les itinéraires sont disponibles. Pour connaître la couverture internationale de l'API Directions, consultez Détails de la couverture Google Maps Platform.

Afficher des itinéraires

Pour envoyer une requête d'itinéraire à DirectionsService avec la méthode route(), vous devez transmettre un rappel qui s'exécute une fois la demande de service terminée. Ce rappel renvoie un DirectionsResult et un code DirectionsStatus dans la réponse.

État de la requête d'itinéraire

DirectionsStatus peut renvoyer les valeurs suivantes :

  • OK indique que la réponse contient un DirectionsResult valide.
  • NOT_FOUND indique qu'au moins un des lieux spécifiés dans la requête comme point de départ, destination ou point de cheminement n'a pas pu être géocodé.
  • ZERO_RESULTS indique qu'aucun itinéraire n'a été trouvé entre le point de départ et la destination.
  • MAX_WAYPOINTS_EXCEEDED indique que trop de champs DirectionsWaypoint ont été fournis dans DirectionsRequest. Consultez la section ci-dessous sur les limites des points de cheminement.
  • MAX_ROUTE_LENGTH_EXCEEDED indique que l'itinéraire demandé est trop long et ne peut pas être traité. Cette erreur se produit lorsque des itinéraires plus complexes sont renvoyés. Essayez de réduire le nombre de points de cheminement, de changement de direction ou d'instructions.
  • INVALID_REQUEST indique que la 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 de 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 du 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.

Afficher le DirectionsResult

DirectionsResult contient le résultat de la requête d'itinéraire. Vous pouvez le traiter vous-même ou transmettre à un objet DirectionsRenderer, qui peut afficher automatiquement le résultat sur une carte.

Pour afficher un DirectionsResult avec un DirectionsRenderer, procédez 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 en lui transmettant le DirectionsResult comme indiqué ci-dessus. Le moteur de rendu étant un MVCObject, il détectera automatiquement toute modification de ses propriétés et mettra à jour la carte lorsque l'itinéraire associé sera modifié.

L'exemple suivant calcule l'itinéraire entre deux emplacements sur la route 66, où le point de départ et la destination sont définis par les valeurs "start" et "end" indiquées dans les listes déroulantes. Le DirectionsRenderer gère l'affichage de la polyligne entre les emplacements indiqués, et le placement des repères des points de départ, de destination et de cheminement, s'il y en a.

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.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') {
      directionsRenderer.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 un exemple

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 :

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.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') {
      directionsRenderer.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 un exemple

Un DirectionsRenderer gère non seulement l'affichage de la polyligne et de tous les repères associés, mais il peut également afficher l'itinéraire sous la forme d'une série d'étapes textuelle. Pour ce faire, appelez setPanel() sur votre DirectionsRenderer en lui transmettant le <div> dans lequel vous souhaitez 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.

L'itinéraire textuel utilisera le paramètre de langue préférée du navigateur ou la langue spécifiée lors du chargement de l'API JavaScript avec le paramètre language. (Pour en savoir plus, consultez Localisation.) Dans le cas des itinéraires en transports en commun, l'heure est affichée dans le fuseau horaire de l'arrêt concerné.

L'exemple suivant est identique à celui ci-dessus, mais inclut un panneau <div> dans lequel l'itinéraire doit s'afficher :

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.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') {
      directionsRenderer.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 un exemple

Objet DirectionsResult

Lorsque vous envoyez une requête d'itinéraire au DirectionsService, vous recevez une réponse composée d'un code d'état et d'un résultat, qui est un objet DirectionsResult. DirectionsResult est un littéral d'objet contenant les champs suivants :

  • geocoded_waypoints[] contient un tableau d'objets DirectionsGeocodedWaypoint, chacun contenant des détails sur le geocoding du point de départ, de la destination et des points de cheminement.
  • routes[] contient un tableau d'objets DirectionsRoute. Chaque itinéraire indique un moyen d'aller du point de départ à la destination indiqués dans la DirectionsRequest. En règle générale, un seul itinéraire est renvoyé par requête, sauf si le champ provideRouteAlternatives de la requête est défini sur true, auquel cas plusieurs itinéraires peuvent être renvoyés.

Remarque : La propriété via_waypoint est obsolète dans les itinéraires alternatifs. La version 3.27 est la dernière version de l'API qui ajoute des points de cheminement supplémentaires dans les itinéraires alternatifs. Pour les versions 3.28 et ultérieures de l'API, vous pouvez continuer à implémenter un itinéraire déplaçable à l'aide du service Directions en désactivant le déplacement des itinéraires alternatifs. Seul l'itinéraire principal doit être déplaçable. Les utilisateurs peuvent déplacer l'itinéraire principal jusqu'à ce qu'il corresponde à un itinéraire alternatif.

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

Un objet DirectionsGeocodedWaypoint contient des détails sur le geocoding des points de départ, de destination et de cheminement.

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

  • geocoder_status indique le code d'état résultant de l'opération de geocoding. Ce champ peut contenir les valeurs suivantes :
    • "OK" indique qu'aucune erreur ne s'est produite, que l'adresse a bien été analysée et qu'au moins un geocode a été renvoyé.
    • "ZERO_RESULTS" indique que le géocode a abouti, mais n'a renvoyé aucun résultat. Cela peut se produire si le geocoder a reçu un address inexistant.

  • partial_match indique que le geocoder n'a pas renvoyé de correspondance exacte pour la requête d'origine, bien qu'il ait 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, "Hillpar St, Bristol, UK" renvoie une correspondance partielle pour Henry Street et Henrietta Street. Notez que si une requête comprend un composant d'adresse mal saisi, le service de geocoding 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, qui peut être utilisé avec d'autres API Google. Par exemple, vous pouvez utiliser place_id avec la bibliothèque de l'API Google Places pour obtenir des informations sur un établissement local, comme son numéro de téléphone, ses horaires d'ouverture, les avis des utilisateurs, etc. Consultez la présentation des ID de lieu.
  • types[] est un tableau qui indique le type du résultat renvoyé. Ce tableau contient un ensemble de tags (zéro, un ou plusieurs) qui identifie le type d'élément géographique renvoyé dans le résultat. Par exemple, le géocode de "Chicago" renvoie "locality", qui signifie que "Chicago" est une ville, et "political", qui indique qu'il s'agit d'une entité politique.

Itinéraires

Remarque : 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, et non plus à une section d'un trajet parent.

Un DirectionsRoute contient un seul résultat pour le point de départ et la destination spécifiés. Cet itinéraire peut être constitué d'une ou de plusieurs sections (de type DirectionsLeg) selon que des points de cheminement ont été spécifiés. Il contient également les informations sur les droits d'auteur et les avertissements qui doivent être présentées à l'utilisateur en plus des informations d'itinéraire.

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

  • legs[] contient un tableau d'objets DirectionsLeg, chacun contenant des informations sur une section de l'itinéraire entre un lieu et un autre. Une section séparée est présente pour chaque point de cheminement ou de destination spécifié. (Un itinéraire sans point de cheminement contient exactement un DirectionsLeg.) Chaque section consiste en une série de DirectionStep.
  • waypoint_order contient un tableau indiquant l'ordre des points de cheminement dans l'itinéraire calculé. L'ordre dans ce tableau peut être modifié si optimizeWaypoints: true a été transmis à DirectionsRequest.
  • overview_path contient un tableau de plusieurs LatLng représentant un chemin approximatif (lissé) de l'itinéraire obtenu.
  • overview_polyline contient un seul objet points qui comprend une représentation de l'itinéraire sous forme de polyligne encodée. Cette polyligne est un tracé approximatif (lissé) de l'itinéraire obtenu.
  • bounds contient un LatLngBounds indiquant les limites de la polyligne le long de cet itinéraire.
  • copyrights contient le texte sur les droits d'auteur à afficher pour cet itinéraire.
  • warnings[] contient un tableau d'avertissements à afficher lors de l'affichage de cet itinéraire. Si vous n'utilisez pas l'objet DirectionsRenderer fourni, vous devez traiter et afficher vous-même ces avertissements.
  • fare contient le tarif 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 incluent :
    • currency : code de devise ISO 4217 indiquant la devise dans laquelle le montant est exprimé.
    • value : tarif total exprimé dans la devise spécifiée ci-dessus.

Sections d'itinéraire

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

Un DirectionsLeg définit une section unique d'un trajet entre le point de départ et la destination dans l'itinéraire calculé. Les itinéraires sans point de cheminement se composent d'une seule section ("leg"). En revanche, les itinéraires où un ou plusieurs points de cheminement sont définis en ont plusieurs.

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

  • steps[] contient un tableau d'objets DirectionsStep qui comportent des informations sur chaque étape distincte de la section du trajet.

  • distance indique la distance totale couverte par cette section dans un objet Distance qui se présente comme suit :

    • value indique la distance en mètres.
    • text contient une représentation de la distance sous forme de chaîne, qui est affichée par défaut en 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 ignorer ce système d'unités en définissant spécifiquement un UnitSystem dans la requête d'origine. 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 dans un objet Duration qui se présente comme suit :

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

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

  • duration_in_traffic indique la durée totale de cette section, en tenant compte des conditions de circulation actuelles. duration_in_traffic n'est renvoyé que si toutes les conditions suivantes sont remplies :

    • La requête n'inclut pas de points de cheminement avec arrêt. Autrement dit, elle n'inclut pas les points de cheminement où stopover est défini sur true.
    • La requête porte spécifiquement sur un itinéraire en voiture (mode est défini sur driving).
    • departureTime est inclus dans le champ drivingOptions de la requête.
    • Les conditions de circulation sont disponibles pour l'itinéraire demandé.

    duration_in_traffic contient les champs suivants :

    • value indique la durée en secondes.
    • text contient une représentation de la durée lisible par l'humain.
  • arrival_time contient l'heure d'arrivée prévue pour cette section. Cette propriété n'est renvoyée que pour les itinéraires en transports en commun. Le résultat est renvoyé dans 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 de transports en commun.
    • time_zone contient le fuseau horaire de cette station. La valeur correspond au nom du fuseau horaire, tel que 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 estimée pour cette section, spécifiée en tant qu'objet Time. departure_time n'est disponible que pour les itinéraires en transports en commun.
  • start_location contient le LatLng du point de départ de cette section. Étant donné que le service Web Directions calcule l'itinéraire entre deux lieux à l'aide de l'option de transport la plus proche des points de départ et d'arrivée (il s'agit généralement d'une route), start_location peut être différent du point de départ fourni pour cette section. Par exemple, c'est le cas si le point de départ n'est pas à proximité d'une route.
  • end_location contient le LatLng de la destination de cette section. Étant donné que DirectionsService calcule l'itinéraire entre deux lieux à l'aide de l'option de transport la plus proche des points de départ et d'arrivée (il s'agit généralement d'une route), end_location peut être différent de la destination fournie pour cette section. Par exemple, c'est le cas si la destination n'est pas à proximité d'une route.
  • start_address contient l'adresse lisible par l'humain (généralement une adresse postale) du début de la section.

    Ce contenu est destiné à être lu tel quel. N'analysez pas par programmation l'adresse formatée.
  • end_address contient l'adresse lisible par l'humain (généralement une adresse postale) de la fin de la section.

    Ce contenu est destiné à être lu tel quel. N'analysez pas par programmation l'adresse formatée.

É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 au cours du trajet. Par exemple, "Tourner à gauche vers Pl. Rol Tanguy" Cette étape décrit non seulement l'instruction, mais contient également des informations de distance et de durée entre cette étape et la suivante. Par exemple, une étape "Rejoindre Rue Armand Rousseau" peut contenir une durée de "60 kilomètres" et "40 minutes", indiquant que l'étape suivante se trouve à 60 kilomètres/40 minutes de cette étape.

Lorsque vous utilisez le service Directions pour rechercher un itinéraire en transports en commun, le tableau des étapes inclut d'autres informations spécifiques aux transports en commun dans un objet transit. Si l'itinéraire comprend plusieurs modes de transport, des indications détaillées (pour les étapes à pied ou en voiture) seront fournies dans un tableau steps[]. Par exemple, une étape à pied inclura des indications : "Marcher jusqu'à Pl. Jeanne Laurent". Cette étape inclut des indications à pied détaillées pour cet itinéraire dans le tableau steps[], par exemple : "Prendre la direction nord-ouest", "Tourner à gauche Rue Roger-Henri Guerrand" et "Tourner à gauche sur Av. Jules Maniez".

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

  • instructions contient des instructions pour cette étape dans une chaîne de texte.
  • distance contient, dans un objet Distance, la distance couverte par cette étape jusqu'à l'étape suivante. (Voir la description dans DirectionsLeg ci-dessus.) Ce champ peut être non défini si la distance est inconnue.
  • duration contient, dans un objet Duration, une estimation du temps nécessaire pour suivre cette étape jusqu'à la suivante. (Voir la description dans DirectionsLeg ci-dessus.) Ce champ peut être non défini si la durée est inconnue.
  • start_location contient le LatLng géocodé du point de départ de cette étape.
  • end_location contient le LatLng du point d'arrivée de cette étape.
  • polyline contient un seul objet points qui comprend une représentation de l'étape sous forme de polyligne encodée. Cette polyligne est un tracé approximatif (lissé) de l'étape.
  • steps[] est un littéral d'objet DirectionsStep qui contient des instructions détaillées pour 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é à 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 cette étape.
  • transit contient des informations spécifiques aux transports en commun, comme les heures d'arrivée et de départ, et le nom de la ligne de transports en commun.

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 exposées via l'objet TransitDetails, renvoyé en tant que 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, comme décrit ci-dessous.

Détails sur les transports en commun

L'objet TransitDetails expose les propriétés suivantes :

  • arrival_stop contient un objet TransitStop représentant la station/l'arrêt d'arrivée avec les propriétés suivantes :
    • name est le nom de la station/l'arrêt de transports en commun, par exemple, "Jean Jaurès".
    • location correspond à l'emplacement de la station/l'arrêt de transports en commun, représenté par LatLng.
  • departure_stop contient un objet TransitStop représentant la station/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 de transports en commun.
    • time_zone contient le fuseau horaire de cette station. La valeur correspond au nom du fuseau horaire, tel que 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 le sens du trajet sur cette ligne tel qu'indiqué sur le véhicule ou à l'arrêt de départ. Il s'agit souvent du terminus.
  • headway, lorsqu'il est disponible, indique le nombre de secondes estimé entre deux départs depuis le même arrêt à l'heure actuelle. Par exemple, si la valeur de headway est de 600, vous attendrez environ 10 minutes si vous manquez votre bus.
  • line contient un littéral d'objet TransitLine comportant des informations sur la ligne de transports en commun utilisée à cette étape. 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 de TransitLine.
  • num_stops indique le nombre d'arrêts pour cette étape. L'arrêt d'arrivée est inclus, mais pas celui de départ. Par exemple, si votre itinéraire consiste à partir de l'arrêt A pour arriver à l'arrêt D en passant par les arrêts B et C, num_stops renvoie 3.

Ligne de transports en commun

L'objet TransitLine expose les propriétés suivantes :

  • name contient le nom complet de la ligne de transports en commun. Exemple : "9 Mairie de Montreuil" ou "82 Hopital Americain".
  • short_name contient le nom court de cette ligne de transports en commun. Il s'agit généralement d'un numéro de ligne tel que "2" ou "M14".
  • agencies est un tableau contenant un seul objet TransitAgency. L'objet TransitAgency fournit des informations sur l'exploitant de cette ligne, y compris les propriétés suivantes :
    • name contient le nom complet de l'agence de transports en commun.
    • phone contient le numéro de téléphone de l'agence de transports en commun.
    • url contient l'URL de l'agence de transports en commun.

    Remarque : Si vous affichez manuellement les itinéraires en transports en commun au lieu d'utiliser l'objet DirectionsRenderer, vous devez afficher le nom et l'URL des agences de transports en commun incluses dans les résultats du trajet.

  • url contient l'URL de cette ligne de transports en commun fournie par l'agence de transports en commun.
  • icon contient l'URL de l'icône associée à cette ligne. La plupart des villes utilisent des icônes génériques qui varient selon le type de véhicule. Certaines lignes de transports en commun ont des icônes spécifiques, comme le réseau de métro de New York.
  • color contient la couleur couramment utilisée pour désigner cette ligne. La couleur est spécifiée par une chaîne hexadécimale comme #FF0033.
  • text_color contient la couleur du texte généralement utilisée pour désigner cette 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, "Métro".
    • type contient le type de véhicule utilisé sur cette ligne. Consultez la documentation sur les types de véhicule pour obtenir la liste complète des valeurs acceptées.
    • 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 d'après la signalétique locale pour les transports en commun.

Type de véhicule

L'objet VehicleType expose les propriétés suivantes :

Valeur Définition
VehicleType.RAIL Train.
VehicleType.METRO_RAIL Métro léger.
VehicleType.SUBWAY Métro léger souterrain.
VehicleType.TRAM Métro léger en surface.
VehicleType.MONORAIL Monorail.
VehicleType.HEAVY_RAIL Métro.
VehicleType.COMMUTER_TRAIN Train 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 son trajet.
VehicleType.FERRY Ferry.
VehicleType.CABLE_CAR Véhicule tracté par un câble, généralement en surface. Les téléphériques peuvent être de type VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Téléphérique.
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.

Inspecter DirectionsResults

Les composants DirectionsResults (DirectionsRoute, DirectionsLeg, DirectionsStep et TransitDetails) peuvent être inspectés et utilisés lors de l'analyse d'une réponse d'itinéraire.

Important : Si vous affichez les itinéraires en transports en commun manuellement au lieu d'utiliser l'objet DirectionsRenderer, vous devez afficher les noms et les URL des agences de transports en commun incluses dans les résultats du trajet.

L'exemple suivant trace l'itinéraire à pied vers certaines attractions touristiques à New York. Nous inspectons le DirectionsStep de l'itinéraire pour ajouter des repères à chaque étape et joignons des informations dans une InfoWindow avec un texte d'instructions pour cette étape.

Remarque : Comme nous calculons l'itinéraire à pied, nous affichons également les avertissements dans un panneau <div> distinct.

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

function initMap() {
  // 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
  }
  directionsRenderer = 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 + "";
      directionsRenderer.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 un exemple

Utiliser des points de cheminement dans les itinéraires

Comme indiqué dans DirectionsRequest, vous pouvez également spécifier des points de cheminement (de type DirectionsWaypoint) lorsque vous calculez un itinéraire à pied, à vélo ou en voiture via le service Directions. 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 itinéraires passant par des lieux supplémentaires, renvoyés sous forme de points de cheminement.

Un waypoint comprend les champs suivants :

  • location (obligatoire) spécifie l'adresse du point de cheminement.
  • stopover (facultatif) indique si ce point de cheminement est un arrêt réel sur l'itinéraire (true) ou s'il s'agit simplement d'un endroit par lequel l'itinéraire doit passer de préférence (false). La valeur par défaut est true.

Par défaut, le service Directions calcule un itinéraire passant par les points de cheminement dans l'ordre fourni. Vous pouvez facultativement transmettre optimizeWaypoints: true dans la DirectionsRequest pour 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 efficace. 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 des points de cheminement, cet ordre sera renvoyé dans le champ waypoint_order de l'objet DirectionsResult.

L'exemple suivant calcule des itinéraires traversant les États-Unis avec divers points de départ, de destination et de cheminement. (Pour sélectionner plusieurs points de cheminement, appuyez sur Ctrl+clic lorsque vous sélectionnez des éléments dans la liste.) Notez que nous inspectons routes.start_address et routes.end_address pour obtenir le texte des points de départ et d'arrivée de chaque itinéraire.

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const 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>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

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

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let 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: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const 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>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;
index.js

Limites et restrictions applicables aux points de cheminement

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

  • Le nombre maximal de points de cheminement autorisé lorsque vous utilisez le service Directions dans l'API Maps JavaScript est de 25, en plus du point de départ et de la destination. Les limites sont identiques pour le service Web de l'API Directions.
  • Avec le service Web de l'API Directions, les clients peuvent ajouter 25 points de cheminement en plus des points de départ et de destination.
  • Les clients du forfait Premium Google Maps Platform peuvent ajouter 25 points de cheminement en plus des points de départ et de destination.
  • Les points de cheminement ne sont pas pris en charge pour les itinéraires en transports en commun.

Itinéraire déplaçable

Les utilisateurs peuvent modifier un itinéraire à vélo, à pied ou en voiture affiché dynamiquement avec un DirectionsRenderer, dès lors qu'il est déplaçable. Ils peuvent ainsi sélectionner et modifier un itinéraire en faisant glisser le trajet sur la carte. Vous pouvez indiquer si le moteur de rendu autorise les itinéraires déplaçables en définissant la 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) du trajet affiché et déplacer le composant indiqué à un nouvel endroit. Le DirectionsRenderer sera mis à jour dynamiquement pour afficher le trajet modifié. Lorsque l'utilisateur termine le déplacement, un point de cheminement transitoire est ajouté à la carte (indiqué par un petit repère blanc). Sélectionner et déplacer un segment du trajet modifie la section de l'itinéraire correspondante, alors que sélectionner et déplacer un repère de point de cheminement (y compris les points de départ et les destinations) modifie les sections de l'itinéraire passant par ce point de cheminement.

Étant donné que les itinéraires déplaçables sont modifiés et affichés côté client, si vous souhaitez être informé lorsque l'utilisateur modifie un itinéraire affiché, vous devez surveiller et traiter l'événement directions_changed sur le DirectionsRenderer.

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 trajet.

TypeScript

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

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
index.js
Voir l'exemple

Essayer l'exemple