Lorsque l'API Routes calcule un itinéraire, elle utilise les points de cheminement et les paramètres de configuration que vous fournissez en entrée. L'API renvoie ensuite une réponse contenant le parcours par défaut et un ou plusieurs itinéraires alternatifs.
Votre réponse peut inclure différents types de parcours et d'autres données, en fonction des champs que vous demandez:
| Pour inclure cette information dans la réponse | Consultez cette documentation. |
|---|---|
| L'itinéraire le plus économe en carburant ou en énergie en fonction du type de moteur du véhicule. | Configurer les itinéraires économes en carburant |
| Jusqu'à trois itinéraires bis | Demander des itinéraires bis |
| Polyligne d'un itinéraire complet, de chaque étape d'un itinéraire et de chaque étape d'une étape. | Demander des polylignes d'itinéraire |
| Les péages estimés, en tenant compte de toutes les remises sur les péages ou des cartes disponibles pour le conducteur ou le véhicule. | Calculer les frais de péage |
| Réponses localisées par code de langue et unité de mesure (impériale ou métrique). | Demander des valeurs localisées |
Pour mettre en forme les instructions de navigation en tant que chaîne de texte HTML, ajoutez HTML_FORMATTED_NAVIGATION_INSTRUCTIONS à extraComputations. |
Calculs supplémentaires |
Pour obtenir la liste complète des options d'entrée, consultez les sections Options de routage disponibles et Corps de la requête.
Grâce à la réponse, vous pouvez fournir à vos clients les informations nécessaires pour sélectionner le parcours adapté à leurs besoins.
À propos des masques de champ
Lorsque vous appelez une méthode pour calculer un itinéraire, vous devez spécifier un masque de champ qui définit les champs que vous souhaitez renvoyer dans la réponse. Il n'existe pas de liste par défaut des champs renvoyés. Si vous omettez cette liste, les méthodes renvoient une erreur.
Les exemples de ce document montrent l'objet de réponse complet sans tenir compte des masques de champ. Dans un environnement de production, votre réponse n'inclura que les champs que vous spécifiez explicitement dans le masque de champ.
Pour en savoir plus, consultez Choisir les informations à renvoyer.
À propos de l'affichage des droits d'auteur
Vous devez inclure la déclaration de droits d'auteur suivante lorsque vous affichez les résultats à vos utilisateurs:
Powered by Google, ©YEAR Google
Exemple :
Powered by Google, ©2023 Google
À propos des itinéraires, des étapes et des instructions
Avant d'examiner la réponse renvoyée par l'API Routes, vous devez comprendre les composants qui constituent un itinéraire:
Votre réponse peut contenir des informations sur chacun de ces composants de l'itinéraire:
Itinéraire: trajet complet du point de cheminement de départ, via les points de cheminement intermédiaires, jusqu'au point de cheminement de destination. Un itinéraire se compose d'une ou de plusieurs sections.
Trajet: chemin entre un point de cheminement d'un itinéraire et le point de cheminement suivant. Chaque étape comprend une ou plusieurs étapes distinctes.
Un itinéraire contient une section distincte pour le chemin entre chaque point de cheminement et le suivant. Par exemple, si le parcours ne comporte qu'un seul point de cheminement de départ et un seul point de cheminement de destination, il ne comporte qu'une seule étape. Pour chaque point de cheminement supplémentaire que vous ajoutez à l'itinéraire après l'origine et la destination, appelé point de cheminement intermédiaire, l'API ajoute un tronçon distinct.
L'API n'ajoute pas d'étape pour un point de cheminement intermédiaire de transit. Par exemple, un itinéraire contenant un point de cheminement de départ, un point de cheminement intermédiaire de passage et un point de cheminement de destination ne contient qu'une seule section entre le point de départ et la destination, en passant par le point de cheminement. Pour en savoir plus sur les points de cheminement de passage, consultez la section Définir un point de cheminement de passage.
Étape: instruction unique sur un tronçon d'un itinéraire. Une étape est l'unité la plus petite d'un itinéraire. Par exemple, une étape peut indiquer "Tourner à gauche sur la rue principale".
Contenu de la réponse
L'objet JSON représentant la réponse de l'API contient les propriétés de niveau supérieur suivantes:
routes, tableau d'éléments de type Route. Le tableauroutescontient un élément pour chaque itinéraire renvoyé par l'API. Le tableau peut contenir au maximum cinq éléments: la route par défaut, la route écologique et jusqu'à trois autres routes.geocodingResults, tableau d'éléments de type GeocodingResults. Pour chaque lieu de la requête (point de départ, destination ou point intermédiaire) que vous avez spécifié en tant que chaîne d'adresse ou en tant que plus code, l'API effectue une recherche d'ID de lieu. Chaque élément de ce tableau contient l'ID de lieu correspondant à un emplacement. Les emplacements de la requête spécifiés en tant qu'identifiant de lieu ou en tant que coordonnées de latitude/longitude ne sont pas inclus. Si vous avez spécifié tous les emplacements à l'aide d'ID de lieu ou de coordonnées de latitude et de longitude, ce tableau n'est pas fourni.fallbackInfo, de type FallbackInfo. Si l'API ne parvient pas à calculer un itinéraire à partir de toutes les propriétés d'entrée, elle peut utiliser une autre méthode de calcul. Lorsque le mode de remplacement est utilisé, ce champ contient des informations détaillées sur la réponse de remplacement. Sinon, ce champ n'est pas défini.
La réponse a le format suivant:
{
// The routes array.
"routes": [
{
object (Route)
}
],
// The place ID lookup results.
"geocodingResults": [
{
object (GeocodedWaypoint)
}
],
// The fallback property.
"fallbackInfo": {
object (FallbackInfo)
}
}
Déchiffrer le tableau des routes
La réponse contient le tableau routes, où chaque élément du tableau est de type Route.
Chaque élément du tableau représente un itinéraire complet entre le point de départ et la destination. L'API renvoie toujours au moins un itinéraire, appelé itinéraire par défaut.
Vous pouvez demander des itinéraires supplémentaires. Si vous demandez un itinéraire économe en carburant, le tableau peut contenir deux éléments: l'itinéraire par défaut et l'itinéraire économe en carburant. Vous pouvez également définir computeAlternativeRoutes sur true dans la requête pour ajouter jusqu'à trois itinéraires alternatifs à la réponse.
Chaque itinéraire du tableau est identifié par la propriété de tableau routeLabels:
| Valeur | Description |
|---|---|
DEFAULT_ROUTE |
Identifie l'itinéraire par défaut. |
FUEL_EFFICIENT |
Indique l'itinéraire économe en carburant. |
DEFAULT_ROUTE_ALTERNATE |
I : indique un autre itinéraire. |
Le tableau legs contient la définition de chaque section de l'itinéraire. Les autres propriétés, telles que distanceMeters, duration et polyline,, contiennent des informations sur l'itinéraire dans son ensemble:
{
"routeLabels": [
enum (RouteLabel)
],
"legs": [
{
object (RouteLeg)
}
],
"distanceMeters": integer,
"duration": string,
"routeLabels": [string],
"staticDuration": string,
"polyline": {
object (Polyline)
},
"description": string,
"warnings": [
string
],
"viewport": {
object (Viewport)
},
"travelAdvisory": {
object (RouteTravelAdvisory)
}
"routeToken": string
}
En raison des conditions de circulation actuelles et d'autres facteurs, l'itinéraire par défaut et l'itinéraire économe en carburant peuvent être identiques. Dans ce cas, le tableau routeLabels contient les deux libellés: DEFAULT_ROUTE et FUEL_EFFICIENT.
{
"routes": [
{
"routeLabels": [
"DEFAULT_ROUTE",
"FUEL_EFFICIENT"
],
…
}
]
}
Comprendre le tableau des segments
Chaque route de la réponse contient un tableau legs, où chaque élément du tableau legs est de type RouteLeg.
Chaque segment du tableau définit le chemin d'un point de cheminement au suivant le long de l'itinéraire. Un itinéraire contient toujours au moins une étape.
La propriété legs contient la définition de chaque étape de la section dans le tableau steps. Les autres propriétés, telles que distanceMeters, duration et polyline, contiennent des informations sur la section.
{
"distanceMeters": integer,
"duration": string,
"staticDuration": string,
"polyline": {
object (Polyline)
},
"startLocation": {
object (Location)
},
"endLocation": {
object (Location)
},
"steps": [
{
object (RouteLegStep)
}
],
"travelAdvisory": {
object (RouteLegTravelAdvisory)
}
}
Comprendre le tableau d'étapes
Chaque étape de la réponse contient un tableau steps, où chaque élément du tableau steps est de type RouteLegStep.
Une étape correspond à une seule instruction le long de la branche. Une étape contient toujours au moins une étape.
Chaque élément du tableau steps inclut la propriété navigationInstruction, de type NavigationInstruction, qui contient l'instruction d'étape. Exemple :
"navigationInstruction": {
"maneuver": "TURN_LEFT",
"instructions": "Turn left toward Frontage Rd"
}
instructions peut contenir des informations supplémentaires sur l'étape. Exemple :
"navigationInstruction": {
"maneuver": "TURN_SLIGHT_LEFT",
"instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days"
}
Les autres propriétés de l'étape décrivent des informations sur l'étape, telles que distanceMeters, duration et polyline:
{
"distanceMeters": integer,
"staticDuration": string,
"polyline": {
object (Polyline)
},
"startLocation": {
object (Location)
},
"endLocation": {
object (Location)
},
"navigationInstruction": {
object (NavigationInstruction)
}
}
Spécifier la langue des instructions par étape
L'API renvoie des informations sur l'itinéraire dans la langue locale, translitérées dans un script lisible par l'utilisateur, si nécessaire, tout en respectant la langue préférée. Les composants de l'adresse sont tous renvoyés dans la même langue.
Utilisez le paramètre
languageCoded'une requête pour définir explicitement la langue de l'itinéraire à partir de la liste des langues acceptées. Google met souvent à jour les langues acceptées. Cette liste n'est donc pas exhaustive.Si un nom n'est pas disponible dans la langue spécifiée, l'API utilise la correspondance la plus proche.
La langue spécifiée peut influencer l'ensemble de résultats que l'API choisit de renvoyer et l'ordre dans lequel ils sont renvoyés. Le géocodeur interprète les abréviations différemment selon la langue, par exemple les abréviations des types de rues ou les synonymes pouvant être valides dans une langue, mais pas dans une autre. Par exemple, utca et tér sont des synonymes de "rue" en hongrois.
Comprendre le tableau geocodingResults
Pour chaque lieu de la requête (origine, destination ou point de cheminement intermédiaire) spécifié en tant que chaîne d'adresse ou en tant que plus code, l'API tente de trouver le lieu le plus pertinent associé à un ID de lieu correspondant. Chaque élément du tableau geocodingResults contient le champ placeID contenant l'emplacement sous la forme d'un ID de lieu et un champ type spécifiant le type d'emplacement, tel que street_address, premise ou airport.
Le tableau geocodingResults contient trois champs:
origin: si l'adresse a été spécifiée sous forme de chaîne d'adresse ou de code Plus, l'ID de lieu de l'origine. Sinon, ce champ est omis de la réponse.destination: si l'adresse a été spécifiée sous forme de chaîne d'adresse ou de Plus Code, ID de lieu de la destination. Sinon, ce champ est omis de la réponse.intermediates: tableau contenant l'ID de lieu de tous les points de cheminement intermédiaires spécifiés sous forme de chaîne d'adresse ou de code Plus. Si vous spécifiez un point de cheminement intermédiaire à l'aide d'un ID de lieu ou de coordonnées de latitude et de longitude, il est omis de la réponse. Utilisez la propriétéintermediateWaypointRequestIndexdans la réponse pour déterminer quel point de cheminement intermédiaire de la requête correspond à l'ID de lieu dans la réponse.
"geocodingResults": {
"origin": {
"geocoderStatus": {},
"type": [
enum (Type)
],
"placeId": string
},
"destination": {
"geocoderStatus": {},
"type": [
enum (Type)
],
"placeId": string
},
"intermediates": [
{
"geocoderStatus": {},
"intermediateWaypointRequestIndex": integer,
"type": [
enum (Type)
],
"placeId": string
},
{
"geocoderStatus": {},
"intermediateWaypointRequestIndex": integer,
"type": [
enum (Type)
],
"placeId": string
}
]
}
Comprendre les valeurs de réponse localisées
Les valeurs de réponse localisées sont un champ de réponse supplémentaire qui fournit du texte localisé pour les valeurs de paramètre renvoyées. Le texte localisé est fourni pour la durée du trajet, la distance et le système d'unités (métrique ou impérial). Vous demandez des valeurs localisées à l'aide d'un masque de champ. Vous pouvez spécifier la langue et le système d'unités, ou utiliser les valeurs inférées par l'API. Pour en savoir plus, consultez LocalizedValues.
Par exemple, si vous spécifiez un code de langue pour l'allemand (de) et les unités impériales, vous obtenez une valeur de distanceMeters de 49889,7, mais également un texte localisé fournissant cette mesure de distance en allemand et en unités impériales, soit "31 Meile".
Voici un exemple de ce que vous verrez pour les valeurs localisées:
{ "localized_values":
{
"distance": { "text": "31,0 Meile/n" },
"duration": { "text": 38 Minuten}.
"static_duration": { "text": 36 Minuten}.
}
}
Si vous ne spécifiez pas la langue ni le système d'unités, l'API infère la langue et les unités comme suit:
- La méthode
ComputeRoutesdéduit l'emplacement et les unités de distance à partir du point d'itinéraire d'origine. Par conséquent, pour une requête de calcul d'itinéraire aux États-Unis, l'API déduit la langueen-USet les unitésIMPERIAL. - La méthode
ComputeRouteMatrixutilise par défaut la langue "en-US" et les unités métriques.