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 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 (les polylignes et la description textuelle), transmettez le point de départ et la destination souhaités au service Directions.

Premiers pas

Avant d'utiliser le service Distance Matrix dans Google Maps JavaScript API, assurez-vous que Google Maps Distance Matrix API est activée dans la 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 Distance Matrix 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 Distance Matrix API, puis sélectionnez-la dans la liste des résultats.
    3. Sélectionnez ENABLE. Une fois le processus terminé, Google Maps Distance Matrix API apparaît dans la liste des API sur le Dashboard.

Limites d'utilisation et politiques

Quotas

Le service Distance Matrix est soumis aux limites d'utilisation suivantes :

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.

Utilisation du service Distance Matrix avec le plan Standard

  • 2 500 éléments gratuits 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 éléments supplémentaires, jusqu'à 100 000 éléments par jour.
  • 25 points de départ ou 25 destinations maximum par requête.
  • 100 éléments maximum par requête.
  • 100 éléments maximum par seconde (en additionnant les requêtes côté client et côté serveur).

Utilisation du service Distance Matrix 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.
  • 25 points de départ ou 25 destinations maximum par requête.
  • 625 éléments maximum par requête. Remarque : toute requête utilisant le paramètre facultatif departure_time lorsque mode=driving est limitée à 100 éléments.
  • Illimité éléments côté client par seconde et par projet. Notez que l'API côté serveur est limitée à 1 000 éléments 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 Distance Matrix API.

Politiques

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

Requêtes Distance Matrix

Étant donné que Google Maps API doit appeler un serveur externe, l'accès au service Distance Matrix est asynchrone. Vous devez donc indiquer une méthode de rappel à exécuter à la fin de la requête pour traiter les résultats.

Pour accéder au service Distance Matrix depuis votre code, utilisez l'objet google.maps.DistanceMatrixService. La méthode DistanceMatrixService.getDistanceMatrix() envoie une requête au service Distance Matrix, en lui transmettant un littéral 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 l'exemple (distance-matrix.html)

Le littéral objet DistanceMatrixRequest contient les champs suivants :

  • origins (obligatoire) — Tableau contenant une ou plusieurs chaînes (adresses), un ou plusieurs objets google.maps.LatLng ou un ou plusieurs objets google.maps.LatLng, à utiliser comme points de départ pour le calcul des distances et des durées.
  • destinations (obligatoire) — Tableau contenant une ou plusieurs chaînes (adresses), un ou plusieurs objets google.maps.LatLng ou un ou plusieurs objets google.maps.LatLng, à utiliser comme destinations pour le calcul des distances et des durées.
  • travelMode (facultatif) — Mode de transport à utiliser pour calculer l'itinéraire. Voir la section sur les modes de transport.
  • transitOptions (facultatif) — Options applicables uniquement aux requêtes dans lesquelles travelMode est défini sur TRANSIT. Les valeurs valides sont décrites dans la section sur les options de transport en commun.
  • 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 sur les options d'itinéraire routier.
  • unitSystem (facultatif) — Système d'unités à utiliser pour l'affichage des distances. Les valeurs acceptées sont les suivantes :
    • google.maps.UnitSystem.METRIC (valeur par défaut)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (facultatif) — Si ce champ est défini sur 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 ce champ est défini sur 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 permet de rechercher un itinéraire pour un cycliste qui emprunterait les pistes cyclables et les rues privilégiées (actuellement disponible uniquement aux États-Unis et dans certaines villes canadiennes).
  • DRIVING (mode par défaut) indique l'itinéraire en voiture standard via le réseau routier.
  • TRANSIT permet de rechercher un itinéraire empruntant les transports en commun. Vous ne pouvez spécifier cette option que si la requête inclut une clé d'API. Pour connaître les options disponibles avec ce type de requête, reportez-vous à la section sur les options de transport en commun.
  • WALKING permet de rechercher un itinéraire pour un piéton qui emprunterait les voies piétonnes et les trottoirs (dans la mesure du possible).

Options de transport en commun

Le service Transit 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. Le littéral objet TransitOptions permet de spécifier des options d'itinéraire spécifiques aux transports en commun.

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 objet TransitOptions contient les champs suivants :

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

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

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

Vous trouverez ci-dessous un exemple de requête DistanceMatrixRequest pour un itinéraire routier, 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 points géographiques transmis dans le champ origins de la requête Distance Matrix. Les adresses sont renvoyées telles qu'elles sont formatées par le géocodeur.
  • destinationAddresses est un tableau contenant les points géographiques transmis dans le champ destinations, au format renvoyé par le géocodeur.
  • rows est un tableau d'objets DistanceMatrixResponseRow dans lequel chaque ligne correspond à un point de départ.
  • Les champs elements sont les enfants de rows. Chaque élément est une paire point de départ-destination. Ils contiennent le statut, la durée, la distance et les informations tarifaires (si elles sont disponibles) pour chaque paire point de départ-destination.
  • Chaque champ element se compose des champs suivants :
    • status : Pour obtenir la liste des codes de statut possibles, voir Codes de statut.
    • duration : Durée du trajet pour cet itinéraire, exprimée en secondes (champ value) et au format texte (champ text). La valeur textuelle est formatée selon le système d'unités spécifié dans le champ unitSystem de la requête (ou au format métrique, si aucune préférence n'a été spécifié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 texte (champ text). La valeur textuelle est formatée selon le système d'unités spécifié dans le champ unitSystem de la requête (ou au format métrique, si aucune préférence n'a été spécifiée). Le champ duration_in_traffic n'est renvoyé aux clients Google Maps APIs Premium Plan que si les données de trafic sont disponibles, mode est défini sur driving, et departureTime est inclus dans le champ distanceMatrixOptions de la requête.
    • distance : Distance totale de l'itinéraire, exprimée en mètres (value) et au format texte (text). La valeur textuelle est formatée selon le système d'unités spécifié dans le champ unitSystem de la requête (ou au format métrique, si aucune préférence n'a été spécifiée).
    • 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 transport en commun et uniquement si les informations tarifaires sont disponibles pour les fournisseurs de transport en commun impliqués. Ces informations se composent des 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.

Codes de statut

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

Codes de statut des réponses

Les codes de statut applicables à DistanceMatrixResponse sont transmis dans l'objet DistanceMatrixStatus. Ils peuvent prendre les valeurs suivantes :

  • OK — La requête est valide. Ce statut peut être renvoyé même si aucun itinéraire n'a été identifié entre aucune paire point de départ-destination. Pour plus d'informations sur les statuts au niveau des éléments, voir Codes de statut des éléments.
  • INVALID_REQUEST — La requête fournie n'est pas valide. Cela indique généralement qu'il manque des champs obligatoires. Voir 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 valeur spécifiée dans le champ per-query limit.
  • MAX_DIMENSIONS_EXCEEDED — La requête contient plus de 25 points de départ ou plus de 25 destinations.
  • OVER_QUERY_LIMIT — L'application a demandé trop d'éléments dans les limites 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 n'a pas autorisé votre page Web à utiliser le service Distance Matrix.
  • UNKNOWN_ERROR — Une requête Distance Matrix n'a pas pu être traitée en raison d'une erreur de serveur. Si vous essayez à nouveau, la requête pourrait aboutir.

Codes de statut des éléments

Les codes de statut ci-dessous 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 ligne (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];
      }
    }
  }
}

Envoyer des commentaires concernant…

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