L'API Routes est actuellement en version bêta (avant la mise à disposition générale). Il est possible que les produits et fonctionnalités pré-DG présentent une compatibilité limitée, et que les modifications apportées aux produits et fonctionnalités pré-DG ne soient pas compatibles avec d'autres versions pré-DG. Les Offres de pré-DG sont couvertes par les Conditions spécifiques au service Google Maps Platform. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Guide de migration de l'API Routes

Actuellement, Google Maps Platform est compatible avec l'API Directions et l'API Distance Matrix. Cette version de la nouvelle API Routes contient la version améliorée nouvelle génération de l'API Directions et de l'API Distance Matrix, nouvelle génération optimisée pour les performances:

  • Calculer les routes : calculez les itinéraires entre les lieux à l'aide de données de routage complètes et en temps réel, et du trafic en temps réel.
  • Matrice de routes de calcul: calculez la distance et le temps de trajet pour une liste de paires point de départ-destination.

L'API Routes inclut de nombreuses nouvelles fonctionnalités, parmi lesquelles:

  • Routage de TWO_WHEELER
  • Calcul des frais de péage
  • Polyligne tenant compte du trafic
  • Contrôle qualité de la polyligne
  • Contrôles de la latence de la qualité
  • Streaming de résultats (matrice de route de calcul avec gRPC uniquement)
  • Compatibilité avec gRPC

Pour plus d'informations sur l'API Routes, consultez la section API Routes.

Ce guide explique comment migrer vos applications existantes qui utilisent les API Directions et Distance Matrix pour utiliser la nouvelle API Routes.

Modifications apportées aux fonctionnalités de la nouvelle API Routes

De manière générale, l'API Routes apporte les modifications suivantes à l'API Directions et à l'API Distance Matrix:

  • Regrouper les routes Compute et la matrice Compute Route sous un seul service appelé API Routes

    Vous devez activer l'API Routes dans la console API avant de pouvoir utiliser les routes et la matrice de routage de Compute. Actuellement, vous activez les API Directions et Distance Matrix en tant que services distincts dans la console API.

    Pour en savoir plus, consultez la page Configurer dans la console Google APIs.

  • La nouvelle API Routes utilise des requêtes HTTP POST

    Dans la nouvelle API Routes, vous transmettez des paramètres dans le corps de la requête ou dans les en-têtes dans le cadre d'une requête HTTP POST. En revanche, avec les API Directions et Distance Matrix, vous transmettez des paramètres d'URL à l'aide d'une requête HTTP GET.

    Exemples:

  • Le masquage du champ est obligatoire

    Lorsque vous appelez la nouvelle API Routes pour calculer une route ou une matrice de routage, vous devez spécifier les champs à renvoyer dans la réponse. Il n'existe pas de liste par défaut de champs renvoyés. Si vous omettez cette liste, les méthodes renvoient une erreur.

    Spécifiez la liste des champs en créant un masque de champ de réponse. Vous devez ensuite transmettre le masque de champ de réponse à chaque méthode à l'aide du paramètre d'URL $fields ou fields, ou de l'en-tête HTTP/gRPC X-Goog-FieldMask.

    Le masquage des champs est une bonne pratique de conception qui vous permet de ne pas demander de données inutiles, ce qui permet d'éviter des temps de traitement inutiles et des frais de facturation.

    Pour en savoir plus, consultez Choisir les champs à renvoyer.

  • Nouvelles limites de requêtes pour la matrice de routage Compute

    L'API Distance Matrix applique les limites de requêtes suivantes:

    • 25 origines ou 25 destinations maximum par requête
    • 100 éléments au maximum (nombre d'origines × nombre de destinations) par requête côté serveur.

    La matrice de routage Compute applique les limites de requêtes suivantes:

    • Le nombre d'éléments ne peut pas dépasser 625.

    • Si vous spécifiez TRAFFIC_AWARE_OPTIMAL, le nombre d'éléments ne peut pas dépasser 100. Pour en savoir plus sur TRAFFIC_AWARE_OPTIMAL, consultez Configurer la qualité et la latence.

    • Le nombre maximal de points de cheminement (origines et destinations) que vous pouvez spécifier à l'aide d'un ID de lieu est de 50.

  • Nouvelles options de configuration de la qualité et de la latence

    La nouvelle API Routes est compatible avec trois préférences de routage que vous pouvez utiliser pour configurer explicitement la qualité des routes et la latence des réponses:

    • TRAFFIC_UNAWARE (par défaut) : calcule la route de manière à minimiser la latence en utilisant des données de trafic moyennes indépendantes du temps, et non en temps réel. Ce paramètre équivaut à ne pas utiliser le trafic dans les API Directions et Distance Matrix.

    • TRAFFIC_AWARE : qualité du trafic en direct optimisée pour les performances, pour une latence réduite. Ce paramètre est nouveau pour l'API Routes. Il n'a pas d'équivalent dans les API Directions et Distance Matrix.

      Contrairement à TRAFFIC_AWARE_OPTIMAL, certaines optimisations sont appliquées pour réduire considérablement la latence.

    • TRAFFIC_AWARE_OPTIMAL : données de trafic complètes et de haute qualité sans appliquer la plupart des optimisations de performances. Ce paramètre produit la latence la plus élevée et équivaut au paramètre de departure_time dans les API Directions et Distance Matrix.

      La préférence de routage TRAFFIC_AWARE_OPTIMAL équivaut au mode utilisé par maps.google.com et par l'application mobile Google Maps.

    Dans les API Directions et Distance Matrix, nous fournissons uniquement l'équivalent des options TRAFFIC_AWARE_OPTIMAL et TRAFFIC_UNAWARE. Ces options ont été définies implicitement selon que vous avez défini ou non departure_time.

    Le tableau suivant compare les options actuelles de Directions et Distance Matrix avec les nouvelles options de l'API Routes:

    Mode Actuel API Routes Remarques
    Pas de trafic en temps réel departure_time propriété non définie TRAFFIC_UNAWARE Latence la plus rapide des trois modes.
    Conditions de circulation en temps réel appliquées Aucun équivalent TRAFFIC_AWARE

    Nouveau mode ajouté par l'API Routes. Il offre une latence légèrement supérieure à celle de TRAFFIC_UNAWARE avec un faible coût en termes de qualité d'ATA.

    Sa latence est bien inférieure à celle de TRAFFIC_AWARE_OPTIMAL.
    Données de trafic en direct complètes et de haute qualité appliquées departure_time propriété définie TRAFFIC_AWARE_OPTIMAL

    Équivaut au mode utilisé par maps.google.com et par l'application mobile Google Maps.

    Pour la matrice de route de calcul, le nombre d'éléments dans une requête (nombre d'origines × nombre de destinations) ne peut pas dépasser 100.

    L'API Routes modifie également la manière dont la propriété de réponse duration est définie, ainsi que les propriétés renvoyées dans la réponse actuelle, comme indiqué dans le tableau suivant:

    Type de voyage ETA Actuel API Routes
    Trafic sans heure d'arrivée estimé, indépendant de l'heure

    Correspond à departure_time qui n'est pas défini dans la requête.

    • Heure d'arrivée prévue contenue dans la propriété de réponse duration.
    • La propriété de réponse duration_in_traffic n'est pas renvoyée.

    Correspond à TRAFFIC_UNAWARE.

    • Heure d'arrivée prévue contenue dans la propriété de réponse duration.
    • Les propriétés de réponse duration et staticDuration contiennent la même valeur.
    qui tient compte du trafic en temps réel.

    Correspond au paramètre departure_time dans la requête.

    • L'heure d'arrivée prévue en tenant compte du trafic en temps réel est contenue dans la propriété de réponse duration_in_traffic.

    Correspond à TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL.

    • L'heure d'arrivée prévue en tenant compte du trafic en temps réel est contenue dans la propriété de réponse duration.
    • La propriété de réponse staticDuration contient la durée du trajet sans tenir compte des conditions de circulation.
    • La propriété duration_in_traffic n'est plus renvoyée.

    Pour en savoir plus, consultez la section Configurer la qualité et la latence.

Fonctionnalités existantes non compatibles avec l'API Routes

Les fonctionnalités suivantes ne sont pas compatibles avec l'API Routes:

  • XML comme format de réponse. Seuls les formats JSON et gRPC sont compatibles.

  • Géocodage inversé

    Vous utilisez maintenant l'API Geocoding inversé pour cette fonctionnalité, qui est conçue pour ce cas d'utilisation et fournit des résultats de meilleure qualité.

API Migrate to Routes

Nous avons apporté plusieurs modifications à l'API Routes. La plupart des modifications sont rétrocompatibles avec les API actuelles, mais certaines modifications importantes répertoriées ci-dessous requièrent votre attention lors de la migration d'applications vers l'API Routes.

Mettre à jour les points de terminaison de l'API REST

Si vous utilisez l'API Directions, mettez à jour votre code pour qu'il utilise le nouveau point de terminaison de l'API Routes:

API Directions https://maps.googleapis.com/maps/api/directions/outputFormat?parameters
API Routes https://routes.googleapis.com/directions/v2:computeRoutes

Si vous utilisez l'API Distance Matrix, mettez à jour votre code pour qu'il utilise le nouveau point de terminaison de l'API Routes:

API Distance Matrix https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters
API Routes https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

Convertir les paramètres d'URL pour utiliser un corps de requête HTTP

Avec les API Directions et Distance Matrix, vous transmettez les propriétés de configuration en tant que paramètres d'URL à une requête HTTP GET. Par exemple, pour l'API Directions:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

Avec l'API Routes, vous transmettez des paramètres dans un corps de requête ou dans des en-têtes dans le cadre d'une requête HTTP POST. Exemples:

Convertir les paramètres actuels en paramètres de l'API Routes

Le tableau suivant répertorie les paramètres de l'API Directions et de l'API Distance Matrix qui ont été renommés ou modifiés, ou ceux qui ne sont pas compatibles avec la version d'aperçu. Mettez à jour votre code si vous utilisez l'un de ces paramètres.

Paramètre actuel Paramètre d'API Routes Remarques
destination destination Les adresses et les Plus Codes ne sont pas disponibles dans la version Preview.
origin origin Les adresses et les Plus Codes ne sont pas disponibles dans la version Preview.
alternatives computeAlternativeRoutes
arrival_time Non disponible, car le mode TRANSIT n'est pas disponible dans l'aperçu.
avoid routeModifiers
copyrights Non disponible dans la version bêta.
departure_time departureTime
distance distanceMeters La distance n'est disponible qu'en mètres.
duration_in_traffic Supprimé dans l'API Routes, utilisez duration. Pour en savoir plus, consultez Modifications des fonctionnalités de la nouvelle API Routes ci-dessus.
language languageCode
mode travelMode

TWO_WHEELER est désormais compatible.

Mode TRANSIT non disponible dans l'aperçu.
region Non disponible dans la version bêta, car les adresses ne sont pas acceptées.
status Non disponible dans la version bêta. Utilisez les codes de réponse HTTP pour les erreurs signalées par l'API. Pour en savoir plus, consultez Gérer les erreurs de requête.
traffic_model Non disponible dans la version bêta.
transit_mode Non disponible, car le mode TRANSIT n'est pas disponible dans l'aperçu.
transit_routing_preference Non disponible, car le mode TRANSIT n'est pas disponible dans l'aperçu.
units Non disponible pour Distance Matrix dans la version preview.
waypoints intermediates Les adresses et les polylignes ne sont pas disponibles dans la version d'aperçu.
optimize=true pour les points de cheminement Non disponible dans la version bêta.