Demander des polylignes d'itinéraire

Développeurs de l'Espace économique européen (EEE)

Les méthodes computeRoutes (REST) et la ComputeRoutes méthode (gRPC) renvoient toutes deux l'itinéraire représenté par une polyligne dans le cadre de la réponse. Ces API renvoient deux types de polylignes :

Polyligne de base (par défaut) : représente un itinéraire, mais sans informations sur le trafic intégrées à la polyligne. Les requêtes qui renvoient une polyligne de base sont facturées au tarif Routes Basic. En savoir plus sur la facturation de l'API Routes
Polyligne avec informations sur le trafic : contient des informations sur les conditions de circulation le long de l'itinéraire. Les conditions de circulation sont exprimées en termes de catégories de vitesse (NORMAL, SLOW, TRAFFIC_JAM) applicables à un intervalle donné de la polyligne. Les requêtes de polylignes avec informations sur le trafic sont facturées au tarif Routes Preferred. En savoir plus sur la facturation de l'API Routes Pour en savoir plus, consultez Configurer la qualité des polylignes.

Pour en savoir plus sur les polylignes, consultez les ressources suivantes :

Informations conceptuelles sur les polylignes
L'utilitaire d'encodage interactif des polylignes vous permet de créer des polylignes encodées dans une interface utilisateur ou de décoder des polylignes à afficher sur une carte. Par exemple, utilisez cet utilitaire pour décoder une polyligne créée par le code ci-dessous.

Remarque : Les caractères spéciaux des polylignes renvoyées par l'API REST sont échappés au format JSON. Pour afficher ces polylignes dans l'utilitaire d'encodage interactif des polylignes, vous devez d'abord les déséchapper. De nombreux utilitaires sont disponibles pour effectuer un déséchappement JSON, comme Freeformatter

Demander une polyligne de base pour un itinéraire, une section ou une étape

Une polyligne est représentée par un Polyline (REST) ou Polyline (gRPC) object. Vous pouvez renvoyer une polyligne dans la réponse au niveau de l'itinéraire, de la section et de l'étape.

Spécifiez la polyligne à renvoyer à l'aide du masque de champ de réponse :

Au niveau de l'itinéraire, renvoyez une polyligne dans la réponse en incluant routes.polyline dans le masque de champ de réponse.
Au niveau de la section, renvoyez une polyligne dans la réponse pour chaque section de l' itinéraire en incluant routes.legs.polyline.

Remarque : Chaque section correspond au trajet entre deux points de cheminement lorsque via est défini sur "false" pour le point de cheminement afin d'indiquer un arrêt sur l'itinéraire. Par exemple, un itinéraire sans point de cheminement intermédiaire ne comporte qu'une seule section. Un itinéraire qui inclut un point de cheminement intermédiaire avec un arrêt comporte deux sections. Un itinéraire qui inclut un point de cheminement intermédiaire avec via défini sur "true" ne comporte qu'une seule section.
Au niveau de l'étape, renvoyez une polyligne dans la réponse pour chaque étape de la section en incluant routes.legs.steps.polyline.

Par exemple, pour renvoyer une polyligne pour l'ensemble de l'itinéraire, pour chaque section et pour chaque étape de chaque section :

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Cette requête renvoie la réponse suivante, qui inclut la polyligne de l'itinéraire, pour chaque section de l'itinéraire et pour chaque étape de la section :

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
              "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
          }
        },
          "steps": [
              {
                  "polyline": {
                      "encodedPolyline": "kclcF...@sC@YIOKI"
                  }
              },
              {
                  "polyline": {
                      "encodedPolyline": "wblcF~...SZSF_@?"
                  }
              },
              ...
      ],
      "distanceMeters": 56901,
      "duration": "2420s",
      "polyline": {
        "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
      }
    }
  ]
}

Étant donné que cette requête ne contient qu'un point de départ et une destination, l'itinéraire renvoyé ne contient qu'une seule section. Par conséquent, la polyligne de la section et celle de l'itinéraire sont identiques.

Si vous ajoutez un point de cheminement intermédiaire à la requête, l'itinéraire renvoyé contient deux sections :

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "intermediates": [
    { "address": "450 Serra Mall, Stanford, CA 94305, USA"},
  ],
  "travelMode": "DRIVE",
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Cette requête renvoie deux sections, chacune avec une polyligne unique, et une polyligne pour l'ensemble de l'itinéraire :

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
            "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "kclcFfqch...YIOKI"
                }
            },
        ...
        },
        {
          "polyline": {
            "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "uypeFbo`jVgJq...PoBiC"
                }
            },
        ...
        }
      ],
      "distanceMeters": 68403,
      "duration": "3759s",
      "polyline": {
          "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE"
      }
    }
  ]
}

Qualité des polylignes

La qualité d'une polyligne peut être décrite comme suit :

Précision à virgule flottante des points

Les points sont spécifiés en tant que valeurs de latitude et de longitude, qui sont représentées au format à virgule flottante à simple précision. Cela fonctionne bien pour les petites valeurs (qui peuvent être représentées avec précision), mais la précision diminue à mesure que les valeurs augmentent en raison des erreurs d'arrondi à virgule flottante.

Dans computeRoutes méthode (REST) et ComputeRoutes, cela est contrôlé par polylineEncoding.
Nombre de points qui composent la polyligne

Plus il y a de points, plus la polyligne est lisse (en particulier dans les courbes).

Dans computeRoutes (REST) et ComputeRoutes, cela est contrôlé par polylineQuality.

Configurer le type d'encodage des polylignes

Utilisez l'option de requête polylineEncoding pour contrôler le type de polyligne. La propriété polylineEncoding détermine si la polyligne sera encodée en tant que ENCODED_POLYLINE (par défaut), ce qui signifie que le format d'algorithme des polylignes encodées sera utilisé, ou GEO_JSON_LINESTRING, ce qui signifie que le format GeoJSON LineString sera utilisé.

Par exemple, dans le corps de la requête :

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "polylineEncoding": "ENCODED_POLYLINE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Configurer la qualité des polylignes

polylineQuality spécifie la qualité de la polyligne en tant que HIGH_QUALITY ou OVERVIEW (par défaut). Avec OVERVIEW, la polyligne est composée d'un petit nombre de points et présente une latence de requête inférieure à celle de HIGH_QUALITY.

Par exemple, dans le corps de la requête :

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "polylineQuality": "HIGH_QUALITY",
  "polylineEncoding": "ENCODED_POLYLINE",
  "departureTime": "2023-10-15T15:01:23.045123456Z",
  ...
}

Demander une polyligne avec informations sur le trafic

Les exemples présentés ci-dessus renvoient tous des polylignes de base, c'est-à-dire des polylignes sans informations sur le trafic. Vous pouvez également demander que la polyligne contienne des informations sur le trafic pour l'itinéraire et pour chaque section de l'itinéraire.

Les polylignes avec informations sur le trafic contiennent des informations sur les conditions de circulation le long de l'itinéraire. Les conditions de circulation sont exprimées en termes de catégories de vitesse (NORMAL, SLOW, TRAFFIC_JAM) pour un intervalle donné de la polyligne de réponse. Les intervalles sont définis par les index de leurs points de polyligne de début (inclus) et de fin (exclus).

Par exemple, la réponse suivante indique un trafic NORMAL entre les points de polyligne 2 et 4 :

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

Pour envoyer une requête afin de calculer une polyligne avec informations sur le trafic, définissez les propriétés suivantes dans la requête :

Définissez le champ de tableau extraComputations sur TRAFFIC_ON_POLYLINE pour activer le calcul du trafic.
Définissez travelMode sur DRIVE ou TWO_WHEELER. Les requêtes pour tout autre mode de transport renvoient une erreur.
Spécifiez la préférence de routage TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL dans la requête. Pour en savoir plus, consultez Configurer la qualité par rapport à la latence.
Définissez un masque de champ de réponse qui spécifie de renvoyer les propriétés de réponse :
- Au niveau de l'itinéraire, renvoyez toutes les informations de voyage dans la réponse en incluant routes.travelAdvisory dans le masque de champ de réponse. Pour ne renvoyer que les informations sur le trafic, spécifiez routes.travelAdvisory.speedReadingIntervals.
- Au niveau de la section, renvoyez toutes les informations de voyage dans la réponse pour chaque section de l'itinéraire en incluant routes.legs.travelAdvisory. Pour ne renvoyer que les informations sur le trafic, spécifiez routes.legs.travelAdvisory.speedReadingIntervals.

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "extraComputations": ["TRAFFIC_ON_POLYLINE"],
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Exemple de réponse pour une polyligne avec informations sur le trafic

Dans la réponse, les données de trafic sont encodées dans la polyligne et sont contenues dans le travelAdvisory champ, de type RouteLegTravelAdvisory (chaque section) et RouteTravelAdvisory (itinéraire).

Exemple :

{
  "routes": [
    {
      "legs": {
        "polyline": {
          "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
        },
        // Traffic data for the leg.
        "travelAdvisory": {
          "speedReadingIntervals": [
            {
              "endPolylinePointIndex": 1,
              "speed": "NORMAL"
            },
            {
              "startPolylinePointIndex": 1,
              "endPolylinePointIndex": 2,
              "speed": "SLOW"
            },
            {
              "startPolylinePointIndex": 2,
              "endPolylinePointIndex": 4,
              "speed": "NORMAL"
            }
          ] 
        }
      },
      "polyline": {
        "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
      },
      // Traffic data for the route.
      "travelAdvisory": {
        "speedReadingIntervals": [
          {
            "endPolylinePointIndex": 1,
            "speed": "NORMAL"
          },
          {
            "startPolylinePointIndex": 1,
            "endPolylinePointIndex": 2,
            "speed": "SLOW"
          },
          {
            "startPolylinePointIndex": 2,
            "endPolylinePointIndex": 4,
            "speed": "NORMAL"
          }
        ] 
      }
    }
  ]
}

RouteTravelAdvisory et RouteLegTravelAdvisory incluent un champ de tableau appelé speedReadingIntervals qui contient des informations sur la vitesse du trafic. Chaque objet du tableau est représenté par un SpeedReadingInterval (REST) ou SpeedReadingInterval (gRPC).

Un objet SpeedReadingInterval inclut la lecture de la vitesse pour un intervalle d'itinéraire, tel que NORMAL, SLOW ou TRAFFIC_JAM. L'ensemble du tableau d'objets couvre l'intégralité de la polyligne de l'itinéraire sans chevauchement. Le point de départ d'un intervalle spécifié est le même que le point de terminaison de l'intervalle précédent.

Chaque intervalle est décrit par son startPolylinePointIndex, son endPolylinePointIndex et la catégorie de vitesse correspondante. Notez que l' absence d'index de début dans l'intervalle correspond à l'index 0 conformément aux pratiques proto3.

Les valeurs startPolylinePointIndex et endPolylinePointIndex ne sont pas toujours consécutives. Exemple :

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

Dans ce cas, les conditions de circulation étaient les mêmes de l'index 2 à l'index 4.

Afficher des polylignes avec informations sur le trafic avec le SDK Maps

Nous vous recommandons d'afficher les polylignes avec informations sur le trafic sur la carte à l'aide des différentes fonctionnalités proposées par les SDK Google Maps, y compris la coloration, les traits et les motifs personnalisés le long des tronçons de la polyligne. Pour en savoir plus sur l'utilisation des polylignes, consultez Fonctionnalités des polylignes pour Android et Fonctionnalités des polylignes pour iOS.

Exemple de rendu de polyligne

Les utilisateurs du SDK Maps ont la possibilité de définir une logique de mappage personnalisée entre les catégories de vitesse et les schémas de rendu des polylignes. Par exemple, vous pouvez décider d'afficher la vitesse "NORMAL" sous la forme d'une ligne bleue épaisse sur la carte, tandis que la vitesse "SLOW" peut être affichée sous la forme d'une ligne orange épaisse.

Les extraits suivants ajoutent une polyligne bleue épaisse avec des segments géodésiques de Melbourne à Perth. Pour en savoir plus, consultez Personnaliser l'apparence (pour Android) et Personnaliser la polyligne (pour iOS).

Android

Java

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Kotlin

val line: Polyline = map.addPolyline(
  PolylineOptions()
    .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
    .width(25f)
    .color(Color.BLUE)
    .geodesic(true)
)

iOS

Objective-C

GMSMutablePath *path = [GMSMutablePath path];
[path addLatitude:-37.81319 longitude:144.96298];
[path addLatitude:-31.95285 longitude:115.85734];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.strokeWidth = 10.f;
polyline.strokeColor = .blue;
polyline.geodesic = YES;
polyline.map = mapView;

Swift

let path = GMSMutablePath()
path.addLatitude(-37.81319, longitude: 144.96298)
path.addLatitude(-31.95285, longitude: 115.85734)
let polyline = GMSPolyline(path: path)
polyline.strokeWidth = 10.0
polyline.geodesic = true
polyline.map = mapView

Utiliser des polylignes encodées avec la recherche sur le trajet

Utilisez la recherche Text Search de l'API Places pour effectuer une recherche le long d'un itinéraire calculé. Vous transmettez la polyligne encodée d'un itinéraire précalculé de l'API Routes Compute Routes à la requête Text Search. La réponse contient ensuite les lieux qui correspondent aux critères de recherche et qui se trouvent également à proximité de l'itinéraire spécifié. Pour en savoir plus, consultez la section Rechercher sur un trajet.

Par exemple, pour renvoyer les cafés situés le long de l'itinéraire entre le point de départ et la destination :

Node.js

const API_KEY = 'YOUR_API_KEY';
const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes';
const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';

                       }             } function init(){ const routes_request = { "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }; const textSearch_request = { "textQuery": "cafe", "searchAlongRouteParameters": { "polyline": { "encodedPolyline": "" } } }; fetchResources(routes_service,routes_request).then(routes => { textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline; fetchResources(textSearch_service,textSearch_request).then(places => { console.log(places); }); }); async function fetchResources(resource,reqBody){ const response = await fetch(resource, { method: 'POST', body: JSON.stringify(reqBody), headers: { 'Content-Type': 'application/json', 'X-Goog-Api-Key': API_KEY, 'X-Goog-FieldMask': '*' } }); const responseJSON = await response.json(); return responseJSON; >init();