Mit annotatePaths Pfadanmerkungen abrufen

Mit der Methode annotatePaths können Sie Annotationen zu dynamischen Verkehrsattributen für von Ihnen angeforderte Straßenpfade abrufen. Diese Annotationen können nützlich für die Implementierung von erweiterten Fahrassistenzsystemen (Treiberassistenzsystem) sein.

Sie können Pfadanmerkungen abrufen, indem Sie eine Anfrage mit einer Liste der Pfade, für die Sie Annotationen erhalten möchten, und den gewünschten Annotationstypen für diese Pfade senden. Die Antwort enthält die Pfade mit den annotierten Daten, die Sie zuvor angefordert haben. Die Pfade in der Antwort werden so annotiert, als ob das Fahrzeug zum Zeitpunkt Ihrer Anfrage jeden Pfad befahren würde.

Schlüsselkonzepte

In den folgenden Unterabschnitten werden die grundlegenden Konzepte der annotatePaths-Methode beschrieben.

Pfade und Segmente

Bei dieser Methode werden Daten zu Pfaden annotiert, bei denen es sich um eine Abfolge verbundener Segmente handelt, die ein Fahrzeug zurücklegen kann.

Das folgende Diagramm zeigt zwei Pfade, die jeweils aus drei Segmenten bestehen.

Abbildung 1: Ein Diagramm von Pfad 1, bestehend aus den Segmenten A, B und C, und Pfad 2, bestehend aus den Segmenten A, B und D.

Ein Pfad ist auf 15 km lang und wird vom Beginn des ersten Segments bis zum Anfang des letzten Abschnitts gemessen. Ein Fehler tritt auf, wenn der Beginn des letzten Abschnitts mehr als 15 km vom Anfang des ersten Segments entfernt ist.

Der Start eines Pfads ist immer der angenommene Fahrzeugstandort. Ein Fahrzeug kann mehrere Wege haben, die an verschiedenen Orten enden, die jedoch nicht an verschiedenen Orten beginnen können.

Segmentanmerkungen können sich je nach Pfad unterscheiden, zu dem sie gehören. Auch wenn zwei Pfade zum Teil dieselben Segmente haben, können die Vermerke für diese Segmente variieren.

Zum Beispiel in Abbildung 1:

• Pfad 1 besteht aus:

  • Segment A
  • Segment B
  • Segment C

• Pfad 2 besteht aus:

  • Segment A
  • Segment B
  • Segment D

In Pfad 1 folgt Segment B auf Segment C. In Pfad 2 folgt auf dasselbe Segment B ein anderes Segment – Segment D.

Für Segment B können unterschiedliche dynamische Attribute für Pfad 1 und Pfad 2 zurückgegeben werden, da mit der rechten Abzweigung in Pfad 2 mehr Zugriffe erzielt werden können als für den geraden Pfad in Pfad 1.

Servicelevels

Der Begriff „Dienstebene“ ist ein allgemein verwendeter Begriff, um die Kategorisierung des vorhergesagten Verkehrsflusses anhand von Fahrzeuggeschwindigkeit, -dichte, Überlastung und anderen Parametern zu beschreiben. Beachten Sie, dass die in dieser Methode verwendeten und in dieser Dokumentation beschriebenen Ebenen der Dienstdefinitionen proprietär sind und nur für die Methode gelten.

In der folgenden Liste werden die verwendeten Dienstebenen beschrieben.

Servicelevel	Wert	Beschreibung
LEVEL_OF_SERVICE_UNSPECIFIED	0	Standardwert. Dieser Wert bedeutet, dass kein prognostizierter Traffic-Wert verfügbar ist.
LEVEL_OF_SERVICE_STOPPED	1	Der Verkehr ist angehalten und das Fahrzeug fährt nicht.
LEVEL_OF_SERVICE_STOP_AND_GO	2	Das Fahrzeug fährt mit niedriger Geschwindigkeit und stoppt kurz danach.
LEVEL_OF_SERVICE_SLOW	3	Ein Stau wird vorhergesagt und das Fahrzeug bewegt sich langsam, aber es sind keine Staus vorhergesagt.
LEVEL_OF_SERVICE_NORMAL	4	Der Verkehr fließt normal und es ist kein Stau zu erwarten.

Pfadannotationen abrufen

Sie können Pfadanmerkungen abrufen, indem Sie eine HTTP-POST-Anfrage an die Methode annotatePaths (REST) senden oder die Methode AnnotatePaths (gRPC) aufrufen.

In den folgenden Unterabschnitten werden die Anfrage- und Antworttexte beschrieben, die zum Anfordern und Empfangen von Pfadannotationen und Links zur REST-Referenz verwendet werden.

Anfragetext

Der Anfragetext für die Methode annotatePaths enthält Folgendes:

• Paths: Die angeforderte Route (Satz von Pfaden), die mit dynamischen Attributdaten annotiert werden soll. Alle Pfade auf dieser Route müssen dasselbe Startsegment haben, also das Segment, auf dem sich das Fahrzeug befindet. Es wird davon ausgegangen, dass sich das Fahrzeug am Start des ersten Segments befindet. Wenn die Pfade nicht beim selben Segment beginnen, wird ein Fehler zurückgegeben.
  • Path: Ein Pfad, über den dynamische Attribute angefordert werden.
  • Segments: Eine sortierte Liste von Segmenten, die den Pfad bildet.
    • Segment: Segment, das zu einem Pfad gehört
    • Polyline: Die Polylinie des Segments, mit der das Segment identifiziert werden kann, wenn die ID nicht gefunden wird. Sie dient auch dazu, zwischen zwei Segmenten zu unterscheiden, wenn sie dieselbe ID haben. Die Polylinie wird mit dem standardmäßigen Algorithmusformat für codierte Polylinien der Google Maps Platform codiert.
    • placeId: Die Orts-ID für dieses Straßensegment. Sie kann mit dem Wert im Feld placeId des Objekts DirectionalSegment übereinstimmen.
• AnnotationOptions: Die angeforderten Annotationen für die Eingabepfade.
  • includeLevelOfService: Ein boolesches Feld. Wenn dieser Wert auf „true“ gesetzt ist, werden die Segmente in der Antwort mit vorhergesagten Traffic-Werten versehen. Weitere Informationen finden Sie im Abschnitt Dienststufen dieses Dokuments.

Anfrageanforderungen

Der Anfragetext für die Methode annotatePaths muss die folgenden Anforderungen erfüllen:

• Pfade müssen mit demselben Segment beginnen.
• Pfade müssen gleich oder kürzer als 15 km sein, wobei der letzte Abschnitt des Pfads nicht weiter als 15 km vom Anfang des ersten Abschnitts beginnt.
• Die Anfrage darf maximal 10 Pfade enthalten.

Hinweis :Alle im Anfragetext aufgeführten Felder sind Pflichtfelder.

Beispielanfrage

Das folgende Beispiel zeigt einen Anfragetext der Methode annotatePaths. In diesem Beispiel senden Sie einen aus drei Segmenten bestehenden Pfad und geben an, dass Sie die Dienstanmerkungen einschließen möchten.

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
}

Antworttext

Der Antworttext der Methode annotatePaths enthält Folgendes:

• annotatedPaths: Pfade aus der Eingabe, die mit angeforderten Attributen annotiert sind.
  • AnnotatedPath: Eine Kopie eines Eingabepfads, der mit vorhergesagten Attributen zurückgegeben wird.
  • annotatedSegments: Eine sortierte Liste von Segmenten, die den Hauptpfad bilden, und mit angeforderten Attributen gekennzeichnet.
    • AnnotatedSegment: Ein Segment, das einen Pfad bildet, der mit dynamischen Datenattributen annotiert ist.
    • Segment: Segment, das zu einem Pfad gehört
      • placeId: Die Orts-ID für dieses Straßensegment. Sie kann mit dem Wert im Feld placeId des Objekts DirectionalSegment übereinstimmen.
    • SegmentSpanAttributes: Das sind Attribute, die dem Segment zugewiesen sind. Diese Attribute können sich je nach Pfad unterscheiden, in dem sich ein Segment befindet. Eine Spanne kann das gesamte Segment abdecken. Die Attributbereiche sind vom Fahrzeugstandort bis zum Ende des Pfads in der angegebenen Reihenfolge angeordnet.
      • SegmentSpan: Beschreibt, wo im Segment die Annotationen gelten.
      • LevelOfService: Das voraussichtliche Verkehrsniveau für die Spanne des Segments, definiert durch die auf diesem Segment erwarteten Verkehrsgeschwindigkeiten, wenn das Fahrzeug am Anfang des Segments ankommt. Weitere Informationen finden Sie im Abschnitt Dienststufen dieses Dokuments.

Beispielantwort

Das folgende Beispiel zeigt einen Anfragetext der Methode annotatePaths. In diesem Beispiel erhalten Sie die Dienstanmerkungen zu dem einen Pfad, der in der Beispielanfrage angefordert wurde.

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
    }
  }
}