Service Distance Matrix

Présentation

Le service Distance Matrix de Google calcule les distances et les durées des trajets entre plusieurs points de départ et destinations avec un mode de transport donné.

Ce service ne renvoie pas d'informations détaillées sur l'itinéraire. Pour obtenir les informations d'itinéraire, y compris les polylignes et les itinéraires textuels, transmettez le point de départ et la destination souhaités au service Directions.

Commencer

Avant d'utiliser le service Distance Matrix de l'API Maps JavaScript, vérifiez que cette API est activée dans la console Google Cloud, dans le même projet que vous avez 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 Distance Matrix.
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 Distance Matrix, puis sélectionnez-la dans la liste des résultats.
   3. Sélectionnez ACTIVER. Une fois le processus terminé, l'API Distance Matrix 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 Distance Matrix, consultez la page Utilisation et facturation de l'API Distance Matrix.

Remarque : Chaque requête envoyée au service Distance Matrix est limitée par le nombre d'éléments autorisés. Le nombre d'éléments de la requête est obtenu en multipliant le nombre de points de départ par le nombre de destinations.

Règles

Le service Distance Matrix doit être utilisé conformément aux Règles décrites pour l'API Distance Matrix.

Requêtes Distance Matrix

L'API Google Maps devant appeler un serveur externe, l'accès au service Distance Matrix est asynchrone. Pour cette raison, vous devez transmettre une méthode de rappel à exécuter à la fin de la requête, afin de traiter les résultats.

Vous pouvez accéder au service Distance Matrix depuis votre code via l'objet constructeur google.maps.DistanceMatrixService. La méthode DistanceMatrixService.getDistanceMatrix() envoie une requête au service Distance Matrix, en lui transmettant un littéral d'objet DistanceMatrixRequest contenant les points de départ, les destinations et le mode de transport, ainsi qu'une méthode de rappel à exécuter à la réception de la réponse.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

Voir un exemple

La DistanceMatrixRequest contient les champs suivants :

• origins (obligatoire) : tableau contenant une ou plusieurs chaînes d'adresse, des objets google.maps.LatLng ou des objets Place à utiliser comme points de départ pour calculer des distances et des durées.
• destinations (obligatoire) : tableau contenant une ou plusieurs chaînes d'adresse, des objets google.maps.LatLng ou des objets Place à utiliser comme destinations pour calculer des distances et des durées.
• travelMode (facultatif) : mode de transport à utiliser pour calculer l'itinéraire. Consultez la section sur les modes de transport.
• transitOptions (facultatif) : options 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.
• 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.
• unitSystem (facultatif) : système d'unités à utiliser pour afficher des distances. Voici les valeurs acceptées :
  • google.maps.UnitSystem.METRIC (par défaut)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (facultatif) : si la valeur est true, les itinéraires entre les points de départ et les destinations sont calculés de manière à éviter les autoroutes dans la mesure du possible.
• avoidTolls (facultatif) : si la valeur est true, les itinéraires entre les points sont calculés en évitant les sections à péage, dans la mesure du possible.

Modes de transport

Lorsque vous calculez des durées et des distances, vous pouvez spécifier le mode de transport à utiliser. Actuellement, les modes de transport suivants sont pris en charge :

• BICYCLING demande un itinéraire à vélo via les pistes cyclables et les rues à privilégier (actuellement disponible uniquement aux États-Unis et dans certaines villes du Canada).
• DRIVING (par défaut) indique un itinéraire en voiture standard via le réseau routier.
• TRANSIT demande un itinéraire via les réseaux de transports en commun. Vous ne pouvez spécifier cette option que si la requête comprend une clé API. Pour connaître les options disponibles avec ce type de requête, consultez la section sur les options de transports en commun.
• WALKING demande un itinéraire à pied via les voies piétonnes et les trottoirs (dans la mesure du possible).

Options de transports en commun

Le service Transports en commun se trouve actuellement au stade expérimental. Dans cette phase, nous implémentons des limites de taux pour éviter une utilisation abusive de l'API. Finalement, nous imposerons un plafond qui limitera le nombre total de requêtes par chargement de carte, en nous basant sur une utilisation raisonnable de l'API.

Les options disponibles pour les requêtes Distance Matrix dépendent du mode de transport. Dans les requêtes de transport en commun, les options avoidHighways et avoidTolls 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 requêtes de transport en commun dépendent du facteur temps. Les calculs ne sont effectués que pour des horaires futurs.

Le littéral d'objet TransitOptions contient les champs suivants :

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  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.

Options d'itinéraire en voiture

Utilisez l'objet drivingOptions pour spécifier une heure de départ afin de calculer le meilleur itinéraire vers votre destination en fonction des conditions de circulation prévues. Vous pouvez également indiquer si l'estimation de la durée du trafic doit être pessimiste, optimiste ou aussi fidèle que possible en fonction des conditions de circulation historiques et du trafic en temps réel.

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.) 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 qui s'affiche est généralement satisfaisant (sans tenir compte des conditions de circulation).
• trafficModel (facultatif) spécifie les hypothèses à utiliser pour calculer le temps de trajet selon le trafic. 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 best_guess. 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 le duration_in_traffic renvoyé doit être inférieur à 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 DistanceMatrixRequest pour un itinéraire en voiture, avec une heure de départ et un modèle de trafic :

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Réponses Distance Matrix

Un appel valide au service Distance Matrix renvoie un objet DistanceMatrixResponse et un objet DistanceMatrixStatus. Ces derniers sont transmis à la fonction de rappel que vous avez spécifiée dans la requête.

L'objet DistanceMatrixResponse contient les informations de distance et de durée de chaque paire point de départ-destination pour laquelle l'itinéraire a pu être calculé.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

Résultats Distance Matrix

Les champs pris en charge dans les réponses sont expliqués ci-dessous.

• originAddresses est un tableau contenant les lieux transmis dans le champ origins de la requête Distance Matrix. Les adresses sont renvoyées telles qu'elles sont formatées par le geocoder.
• destinationAddresses est un tableau contenant les lieux transmis dans le champ destinations, au format renvoyé par le geocoder.
• rows est un tableau d'objets DistanceMatrixResponseRow dans lequel chaque ligne correspond à un point de départ.
• Les elements sont des enfants des rows et correspondent à une paire point de départ-destination. Ils contiennent l'état, la durée, la distance et les informations tarifaires (si elles sont disponibles) pour chaque paire point de départ-destination.
• Chaque objet element contient les champs suivants :
  • status : consultez la section Codes d'état pour obtenir la liste des codes d'état possibles.
  • duration : durée du trajet pour cet itinéraire, exprimée en secondes (champ value) et au format text. La valeur textuelle est formatée selon le unitSystem spécifié dans la requête (ou au format métrique, si aucune préférence n'est indiquée).
  • duration_in_traffic : durée du trajet pour cet itinéraire en tenant compte de l'état actuel du trafic, exprimée en secondes (champ value) et au format text. La valeur textuelle est formatée selon le unitSystem spécifié dans la requête (ou au format métrique, si aucune préférence n'est indiquée). La duration_in_traffic n'est renvoyé que lorsque les données de trafic sont disponibles, mode est défini sur driving ; departureTime est inclus dans le distanceMatrixOptions dans la requête.
  • distance : distance totale de l'itinéraire, exprimée en mètres (value) et au format text. La valeur textuelle est formatée selon le unitSystem spécifié dans la requête (ou au format métrique, si aucune préférence n'est indiquée).
  • 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 transport en commun et uniquement si les informations tarifaires sont disponibles pour les fournisseurs de transport en commun impliqués. 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.

Codes d'état

La réponse Distance Matrix inclut un code d'état pour la réponse globale, ainsi qu'un état pour chaque élément.

Codes d'état des réponses

Les codes d'état qui s'appliquent à DistanceMatrixResponse sont transmis dans l'objet DistanceMatrixStatus et peuvent prendre les valeurs suivantes :

• OK : la requête est valide. Cet état peut être renvoyé même si aucun itinéraire n'a été identifié entre aucune paire point de départ-destination. Consultez Codes d'état des éléments pour en savoir plus sur les états au niveau de l'élément.
• INVALID_REQUEST : la requête fournie n'était pas valide. Cela indique généralement qu'il manque des champs obligatoires. Consultez la liste des champs pris en charge ci-dessus.
• MAX_ELEMENTS_EXCEEDED : le produit du nombre de points de départ par le nombre de destinations dépasse la limite par requête.
• MAX_DIMENSIONS_EXCEEDED : votre requête contenait plus de 25 points de départ ou destinations.
• OVER_QUERY_LIMIT : votre application a demandé trop d'éléments au cours de la période autorisée. Si vous essayez à nouveau après un délai raisonnable, la requête devrait aboutir.
• REQUEST_DENIED : le service a refusé l'utilisation du service Distance Matrix par votre page Web.
• UNKNOWN_ERROR : une requête Distance Matrix n'a pas pu être traitée en raison d'une erreur du serveur. Si vous essayez à nouveau, la requête pourrait aboutir.

Codes d'état des éléments

Les codes d'état suivants s'appliquent à des objets DistanceMatrixElement spécifiques :

• NOT_FOUND : le point de départ et/ou la destination de cet élément n'ont pas pu être géocodés.
• OK : la réponse contient un résultat valide.
• ZERO_RESULTS : aucun itinéraire n'a pu être identifié entre le point de départ et la destination.

Analyse des résultats

L'objet DistanceMatrixResponse contient une valeur row pour chaque point de départ transmis dans la requête. Chaque ligne contient un champ element pour chaque paire constituée de ce point de départ et de la ou des destinations transmises.

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}