Cette page a été traduite par l'API Cloud Translation.

Demander des polylignes d'itinéraire

L'encodage des polylignes est un algorithme de compression avec pertes qui vous permet de stocker une série de coordonnées, comme un itinéraire, sous la forme d'une chaîne unique. Le processus d'encodage convertit une valeur binaire en une série de codes de caractères ASCII en utilisant le schéma d'encodage base64. Pour obtenir une description complète du processus d'encodage, consultez la section Format d'algorithme des polylignes encodées.

Les méthodes computeRoutes (REST) et ComputeRoutes (gRPC) renvoient toutes les deux la route représentée par une polyligne dans la réponse. Ces API renvoient deux types de polylignes:

Polyligne de base (par défaut) : représente un itinéraire, mais sans les informations sur le trafic qui sont intégrées dans 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
La polyligne adaptée au trafic contient des informations sur les conditions de circulation sur l'itinéraire. Les conditions de trafic sont exprimées en termes de catégories de vitesse (NORMAL, SLOW, TRAFFIC_JAM) applicables sur un intervalle donné de la polyligne. Les requêtes pour les polylignes tenant compte du trafic sont facturées au tarif préférentiel de Routes. En savoir plus sur la facturation de l'API Routes

Pour en savoir plus sur les polylignes, consultez:

Configurer la qualité et la latence pour en savoir plus sur la configuration de la qualité de la polyligne
La section Format d'algorithme des polylignes encodées décrit l'algorithme permettant d'encoder une polyligne.
L'utilitaire Polyline Encoder interactif 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 avec le code ci-dessous.

Remarque :Les caractères spéciaux contenus dans les polylignes renvoyées par l'API REST sont au format JSON. Pour afficher ces polylignes dans l'utilitaire d'encodeur de polylignes interactives, vous devez d'abord les annuler de l'échappement. De nombreux utilitaires tels que Freeformatter sont disponibles pour effectuer une échappement JSON.

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

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

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 du champ de réponse.
Au niveau des sections, 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 que le point de cheminement indique un arrêt sur l'itinéraire. Par exemple, un itinéraire sans point de cheminement intermédiaire ne comporte qu'une section. Un itinéraire qui comprend 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" a une 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'intégralité de l'itinéraire, pour chaque étape et pour chaque étape de chaque étape, procédez comme suit:

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 pour l'itinéraire, pour chaque étape de l'itinéraire et pour chaque étape de l'étape:

{
  "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 section. Par conséquent, la polyligne pour la section et pour 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 comportant une polyligne unique, et une polyligne pour l'intégralité 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"
      }
    }
  ]
}

Configurer le type d'encodage de la polyligne

Utilisez l'option de requête polylineEncoding pour contrôler le type de polyligne. La propriété polylineEncoding spécifie comment encoder la polyligne en tant que ENCODED_POLYLINE (par défaut), ce qui signifie que vous utilisez l'algorithme d'encodage de polyligne, ou GEO_JSON_LINESTRING, en utilisant le format LineString GeoJSON.

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'

Demander une polyligne tenant compte du trafic

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

Les polylignes tenant compte du trafic contiennent des informations sur les conditions de circulation sur l'itinéraire. Les conditions de trafic 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 indices de leurs points de polyligne de début (inclusifs) et de fin (exclusifs).

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

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

Pour effectuer une requête de calcul d'une polyligne compatible avec 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 la section Configurer la qualité et la latence.
Définissez un masque de champ de réponse qui spécifie l'affichage des propriétés de la 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 du champ de réponse. Pour ne renvoyer que des informations sur le trafic, spécifiez routes.travelAdvisory.speedReadingIntervals.
- Au niveau des sections, renvoyez toutes les informations de trajet dans la réponse pour chaque section de l'itinéraire en incluant routes.legs.travelAdvisory. Pour ne renvoyer que des 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 tenant compte du trafic

Dans la réponse, les données de trafic sont encodées dans la polyligne et sont contenues dans le champ travelAdvisory, de type RouteLegTravelAdvisory (chaque section) et de l'objet 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 le débit du trafic. Chaque objet du tableau est représenté par un objet 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 identique au point d'arrivée 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épart 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 trafic de l'index 2 à l'index 4 étaient identiques.

Afficher des polylignes tenant compte du trafic avec le SDK Maps

Nous vous recommandons d'afficher des polylignes compatibles avec la circulation sur la carte en utilisant les différentes fonctionnalités proposées par les SDK Google Maps, y compris les couleurs, les traits et les motifs personnalisés le long des polylignes. Pour en savoir plus sur l'utilisation de polylignes, consultez les caractéristiques des polylignes pour Android et les caractéristiques des polylignes pour iOS.

Exemple de rendu de polylignes

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 choisir d'afficher la vitesse "NORMAL" sous la forme d'une ligne bleue épaisse sur la carte, tandis que la vitesse "Lente" peut s'afficher sous la forme d'une ligne orange épaisse, et ainsi de suite.

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