Guide de migration de l'API Routes

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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

  • 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:

  • Itinéraires en deux-roues
  • 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é
  • Itinéraires écoresponsables
  • 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 présentation du produit.

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

Modifications apportées aux fonctionnalités de l'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 l'API Routes, vous transmettez des paramètres dans le corps de la requête ou dans des 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 l'API Routes pour calculer une route ou calculer 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

    L'API Routes accepte trois préférences de routage que vous pouvez utiliser pour configurer explicitement la qualité de routage et la latence de réponse:

    • 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 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 propriété de réponse duration et modifie les propriétés renvoyées dans la réponse actuelle de l'API Directions et de l'API Distance Matrix, 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 utiliser le nouveau point de terminaison 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 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 des points de cheminement représentés en tant que polylignes encodées en points de cheminement intermédiaires

La spécification de points de cheminement en tant que polylignes encodées est disponible dans l'API Directions pour contenir un grand nombre de points de cheminement dans la limite d'URL de 8 192 caractères. Cette fonctionnalité n'est pas nécessaire dans l'API Routes, car les points de cheminement peuvent être transmis dans le corps des requêtes REST ou gRPC en tant que points de cheminement intermédiaires.

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

Le tableau suivant répertorie les paramètres renommés ou modifiés de l'API Directions actuelle et de l'API Distance Matrix, ou les paramètres qui ne sont pas compatibles avec la version en disponibilité générale. Mettez à jour votre code si vous utilisez l'un de ces paramètres.

Paramètre actuel Paramètre d'API Routes Remarques
alternatives computeAlternativeRoutes
arrival_time Non disponible, car le mode TRANSIT n'est pas disponible.
avoid routeModifiers
copyrights

Non inclus dans la réponse. Vous devez inclure l'instruction suivante lorsque vous présentez les résultats à vos utilisateurs:

Powered by Google, ©YEAR Google

Exemple :

Powered by Google, ©2022 Google
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 Compatible uniquement avec les routes de calcul.
mode travelMode

TWO_WHEELER est désormais compatible.

Mode TRANSIT non disponible.
region regionCode

status Non disponible. 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.
transit_mode Non disponible, car le mode TRANSIT n'est pas disponible.
transit_routing_preference Non disponible, car le mode TRANSIT n'est pas disponible.
units Non disponible pour la matrice de routage.
waypoints intermediates Suppression de la compatibilité avec les polylignes encodées.
optimize=true pour les points de cheminement Non disponible.

Migrer à partir de la version d'aperçu

L'API Routes est disponible en version preview (avant disponibilité générale) en septembre 2022. Les Offres de pré-DG sont couvertes par les Conditions spécifiques du service Google Maps Platform. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Cette section explique comment migrer une application de la version bêta vers la version en disponibilité générale.

Nouvelles fonctionnalités ajoutées à la version en disponibilité générale

La version en disponibilité générale ajoute les nouvelles fonctionnalités suivantes qui n'étaient pas incluses dans l'aperçu:

  • En plus des ID de lieu et des coordonnées de latitude/longitude, vous pouvez désormais spécifier un emplacement dans la version en disponibilité générale:

    • Chaînes d'adresse ("Chicago, Illinois" ou "Darwin, Territoire du Nord, Australie")

      Les chaînes d'adresse correspondent souvent à la manière dont un utilisateur saisit une adresse. Toutefois, {product_name} doit d'abord géocoder la chaîne d'adresse en interne pour la convertir en coordonnées de latitude/longitude avant de pouvoir calculer un itinéraire.

      En outre, la compatibilité avec le paramètre de requête regionCode a été ajoutée, ce qui vous permet de spécifier le renvoi des résultats géocodés pour une région géographique spécifique.

    • Plus Codes

      Les Plus Codes fonctionnent comme des adresses postales pour les personnes ou les lieux qui n'ont pas d'adresse réelle. Au lieu d'adresses comportant des noms de rue et des numéros, les Plus Codes sont basés sur la latitude et la longitude, et sont affichés sous forme de chiffres et de lettres.

  • La réponse de calcul des routes contient désormais le tableau geocodingResults. Pour chaque emplacement de la requête (point de départ, destination ou point de cheminement intermédiaire) spécifié en tant que chaîne d'adresse ou en tant que code Plus, l'API effectue une recherche d'ID de lieu. Chaque élément de ce tableau contient l'ID de lieu correspondant à un établissement ainsi que des métadonnées supplémentaires sur celui-ci. Les emplacements dans la requête spécifiés sous forme d'ID de lieu ou de coordonnées de latitude/longitude sont ignorés.

Modifications apportées aux fonctionnalités d'aperçu existantes

Vous devez maintenant activer explicitement les fonctionnalités suivantes dans Google Analytics en ajoutant le nouveau champ extraComputations à la requête:

Dans la version d'aperçu, vous avez utilisé un masque de champ pour spécifier des réponses dans la réponse. Vous devez maintenant:

  • Définissez le nouveau paramètre de requête de tableau extraComputations pour activer ces fonctionnalités.
  • Définissez un masque de champ à spécifier pour renvoyer les informations dans la réponse.

Que dois-je savoir ?

Les champs suivants ne seront plus inclus dans les réponses computeRouteMatrix, sauf s'ils sont explicitement activés en définissant extraComputations:

  • travelAdvisory.tollInfo (péage)

Les champs suivants ne seront plus inclus dans les réponses computeRoutes, sauf s'ils sont explicitement activés en définissant extraComputations:

  • routes.legs.travelAdvisory.tollInfo(péage)
  • routes.travelAdvisory.tollInfo(péage)
  • routes.travelAdvisory.fuelConsumptionMicroliters(Consommation de carburant)
  • routes.travelAdvisory.speedReadingIntervals(Trafic sur une polyligne)
  • routes.legs.travelAdvisory.speedReadingIntervals(Trafic sur une polyligne)

Que dois-je faire ?

Pour recevoir les champs de réponse pour les frais de péage, la consommation de carburant ou le trafic sur une polyligne, vous devez définir le nouveau champ de tableau de requêtes, extraComputations, afin d'inclure une ou plusieurs des valeurs suivantes: