Utiliser annotatePaths pour obtenir des annotations de chemin d'accès

La méthode annotatePaths vous permet d'obtenir des annotations sur les attributs de trafic dynamiques sur les chemins routiers que vous demandez. Ces annotations peuvent être utiles pour les implémentations de systèmes avancés d'aide à la conduite (ADAS).

Pour obtenir des annotations de chemin, envoyez une requête contenant la liste des chemins pour lesquels vous souhaitez obtenir des annotations et les types d'annotations que vous souhaitez sur ces chemins. La réponse contient les chemins d'accès aux données annotées que vous avez demandées précédemment. Les chemins dans la réponse sont annotés comme si le véhicule empruntait chaque chemin au moment de votre requête.

Concepts clés

Les sous-sections suivantes décrivent les concepts nécessaires pour comprendre la méthode annotatePaths.

Chemins et segments

Cette méthode annote les données sur les trajets, qui sont une séquence de segments connectés qu'un véhicule peut parcourir.

Le schéma suivant illustre deux chemins, chacun composé de trois segments.

Schéma illustrant un réseau routier composé de deux tracés constitués de trois segments chacun. Les chemins commencent par les deux mêmes segments, mais vont dans des directions différentes dans le troisième segment.

Figure 1. Schéma du chemin 1, composé des segments A, B et C, et du chemin 2, composé des segments A, B et D.

La longueur d'un tracé est limitée à 15 km. Elle est mesurée du début de la première section au début de la dernière. Une erreur se produit si le début du dernier segment commence à plus de 15 km du début du premier segment.

Le début d'un tracé correspond toujours à la position supposée du véhicule. Un véhicule peut comporter plusieurs tracés se terminant à des emplacements différents, mais ne peut pas commencer à des endroits différents.

Les annotations de segment peuvent varier en fonction du chemin auquel elles appartiennent. Même si deux chemins partagent certains des mêmes segments, les annotations pour ces segments peuvent varier.

Par exemple, sur la figure 1:

  • Le chemin 1 se compose des éléments suivants:

    • Segment A
    • Segment B
    • Segment C

  • Le chemin 2 se compose des éléments suivants:

    • Segment A
    • Segment B
    • Segment D

Dans le chemin 1, le segment B est suivi du segment C, et dans le chemin 2, le même segment B est suivi d'un autre segment, le segment D.

Les attributs dynamiques renvoyés pour le chemin 1 et 2 peuvent différer du segment B, car le virage à droite du chemin 2 peut générer un trafic plus important que celui du chemin droit du chemin 1.

Niveaux de service

Un niveau de service est un terme généralement utilisé pour décrire la catégorisation du flux de trafic prévu en fonction de la vitesse, de la densité, des embouteillages et d'autres paramètres des véhicules. Il est important de noter que les niveaux de service définis dans cette méthode et décrits dans cette documentation sont propriétaires et propres à la méthode.

La liste suivante décrit les niveaux de service utilisés.

Niveau de service Valeur Description
LEVEL_OF_SERVICE_UNSPECIFIED 0 Valeur par défaut. Cette valeur signifie qu'aucune valeur de trafic prévue n'est disponible.
LEVEL_OF_SERVICE_STOPPED 1 Le trafic est à l'arrêt et le véhicule est immobile.
LEVEL_OF_SERVICE_STOP_AND_GO 2 Circulation en s'arrêter et y aller, et le véhicule roule à faible vitesse et s'arrête peu de temps après.
LEVEL_OF_SERVICE_SLOW 3 Un ralentissement de la circulation est prévu et le véhicule roule lentement, mais aucun embouteillage n'est prévu.
LEVEL_OF_SERVICE_NORMAL 4 Le trafic est à vitesse normale, et aucun ralentissement n'est prévu.

Obtenir des annotations de chemin

Pour obtenir des annotations de chemin, envoyez une requête HTTP POST à la méthode annotatePaths (REST) ou appelez la méthode AnnotatePaths (gRPC).

Les sous-sections suivantes décrivent les corps de requête et de réponse utilisés pour demander et recevoir des annotations de chemin et des liens vers la référence REST.

Corps de la requête

Le corps de la requête de la méthode annotatePaths contient les éléments suivants:

  • Paths: route demandée (ensemble de chemins) à annoter avec des données d'attribut dynamique. Tous les tracés de cet itinéraire doivent avoir le même segment de départ, c'est-à-dire le segment sur lequel se trouve le véhicule. Le véhicule est supposé se trouver au début de la première section. Si les chemins d'accès ne commencent pas par le même segment, une erreur est renvoyée.
    • Path: chemin d'accès sur lequel les attributs dynamiques sont demandés.
    • Segments: liste numérotée de segments qui forment le chemin.
  • AnnotationOptions: annotations demandées pour les chemins d'entrée.
    • includeLevelOfService: champ booléen. Lorsque ce paramètre est défini sur "true", les segments de la réponse sont annotés avec des valeurs de trafic prévues. Pour en savoir plus, consultez la section Niveaux de service de ce document.

Exigences concernant les demandes

Le corps de la requête pour la méthode annotatePaths doit respecter les exigences suivantes:

  • Les chemins doivent commencer par le même segment.
  • La longueur du tracé doit être inférieure ou égale à 15 km, et la dernière section du chemin ne doit pas commencer à plus de 15 km du début de sa première section.
  • La requête doit contenir 10 chemins d'accès au maximum.

Exemple de requête

L'exemple suivant montre un corps de requête de la méthode annotatePaths. Dans cet exemple, vous envoyez un chemin composé de trois segments, en spécifiant que vous souhaitez inclure les annotations de niveau de service.

paths {
  segments {
    place_id: "ChIJqZ402gQVkFQRcM9QM5EHX1A"
    polyline {
      encoded_polyline: "ojxaHfkviVuAjA_@l@y@jC"
    }
  }
  segments {
    place_id: "ChIJg_9y5AQVkFQRKL3E7_fPM_o"
    polyline {
      encoded_polyline: "_pxaHlsviVg@bB"
    }
  }
  segments {
    place_id: "ChIJle5mqwUVkFQRuhQhpqFyxRM"
    polyline {
      encoded_polyline: "gqxaHpvviV_EtM"
    }
  }
}
annotation_options {
  include_level_of_service: true
}

Corps de la réponse

Le corps de la réponse de la méthode annotatePaths contient les éléments suivants:

  • annotatedPaths: chemins de l'entrée annotées avec les attributs demandés.
    • AnnotatedPath: copie d'un chemin d'entrée renvoyé avec les attributs prédits.
    • annotatedSegments: liste numérotée de segments constituant le tracé principal, annotée avec les attributs demandés.
      • AnnotatedSegment: segment qui crée un chemin, annoté avec des attributs de données dynamiques.
      • Segment: segment appartenant à un chemin.
        • placeId: ID de lieu pour cette section de route, qui peut être la même valeur que celle du champ placeId de l'objet DirectionalSegment.
      • SegmentSpanAttributes: attributs attribués au segment. Ces attributs peuvent varier en fonction du chemin emprunté par un segment. Un segment peut couvrir l'intégralité du segment. Les segments d'attributs sont dans l'ordre suivant, de l'emplacement du véhicule à la fin du trajet.
        • SegmentSpan: décrit l'emplacement des annotations sur le segment.
        • LevelOfService: niveau de trafic prévu pour l'ensemble du segment, défini par les vitesses de trafic attendues sur ce segment lorsque le véhicule arrive au début du segment. Pour en savoir plus, consultez la section Niveaux de service de ce document.

Exemple de réponse

L'exemple suivant montre un corps de requête de la méthode annotatePaths. Dans cet exemple, vous recevez les annotations de niveau de service sur le chemin d'accès demandé dans Exemple de requête.

annotated_paths {
  annotated_segments {
    segment {
      place_id: "ChIJqZ402gQVkFQRcM9QM5EHX1A"
    }
    segment_span_attributes {
      segment_span {
        start_meters: 0
        end_meters: 142
      }
      level_of_service: LEVEL_OF_SERVICE_NORMAL
    }
  }
  annotated_segments {
    segment {
      place_id: "ChIJg_9y5AQVkFQRKL3E7_fPM_o"
    }
    segment_span_attributes {
      segment_span {
        start_meters: 0
        end_meters: 44
      }
      level_of_service: LEVEL_OF_SERVICE_NORMAL
    }
  }
  annotated_segments {
    segment {
      place_id: "ChIJle5mqwUVkFQRuhQhpqFyxRM"
    }
    segment_span_attributes {
      segment_span {
        start_meters: 0
        end_meters: 206
      }
      level_of_service: LEVEL_OF_SERVICE_NORMAL
    }
  }
}