Method: annotatePaths (Automotive)

Returns the input segment-based paths back with annotations for dynamic attributes along the paths.

HTTP request

POST https://routes.googleapis.com/annotations/v2:annotatePaths

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "paths": [
    {
      object (Path)
    }
  ],
  "annotationOptions": {
    object (AnnotationOptions)
  }
}
Fields
paths[]

object (Path)

Required. The requested routes to be filled with dynamic attribute data. All paths should have the same starting segment, being the segment that the vehicle is currently on. The vehicle is assumed to be at the start of the first segment. If paths do not start at the same segment, an error will be returned.
annotationOptions

object (AnnotationOptions)

Required. The requested dynamic data attributes that should be added on the input paths. If empty, the request will not be annotated.

Response body

The AnnotatePathsResponse contains the input paths with additional data added for all requested annotations.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "annotatedPaths": [
    {
      object (AnnotatedPath)
    }
  ]
}
Fields
annotatedPaths[]

object (AnnotatedPath)

Paths from the input annotated with requested attributes.

Path

A path that dynamic attributes are being requested on.

A path should have segments that are connected and drivable. A path's segments are assumed to follow a logical route, and if a route cannot be found on the input segments then an error will be returned. For example, if segments in a path do not have connecting endpoints, or a path is empty, this produces an error.

A path is currently limited to 15km long. The path is measured from the beginning of the first segment, the assumed vehicle location. An error will be returned if a segment in a path starts farther than 15km from the beginning of the first segment. It is acceptable for the last segment to start prior to 15km and end past 15km. No partial responses will be returned.

A path can contain the same segments as another path, but it is possible for the segment annotations to contain different responses based on differences in other parts of the path.

JSON representation 
{
  "segments": [
    {
      object (Segment)
    }
  ]
}
Fields
segments[]

object (Segment)

Required. An ordered list of segments that forms the path.

Segment

A segment that belongs to a path.

JSON representation 
{
  "polyline": {
    object (Polyline)
  },

  // Union field id can be only one of the following:
  "placeId": string
  // End of list of possible types for union field id.
}
Fields
polyline

object (Polyline)

Required. The segment's polyline, that can be used to identify the segment if the ID cannot be found, and also to differentiate between two segments if they have the same ID. The polyline is encoded using the standard Google Maps Platform Encoded Polyline Algorithm Format.
Union field id. Used for identifying this segment within an ID space. Required. id can be only one of the following:
placeId

string

The Place ID for this road segment. Used across APIs.

AnnotationOptions

Requested annotations for the input paths.

JSON representation 
{
  "includeLevelOfService": boolean
}
Fields
includeLevelOfService

boolean

Optional. When set to true, the segments in the response will be annotated with predicted traffic values. "Level of Service" is a generally used term to describe categorization of traffic flow, but the level of service definitions in this API belong to this API alone.

AnnotatedPath

A copy of an input path returned with predicted attributes.

JSON representation 
{
  "annotatedSegments": [
    {
      object (AnnotatedSegment)
    }
  ]
}
Fields
annotatedSegments[]

object (AnnotatedSegment)

An ordered list of segments that forms the main path, annotated with requested attributes.

AnnotatedSegment

A segment that builds up a path, annotated with dynamic data attributes.

JSON representation 
{
  "segment": {
    object (Segment)
  },
  "segmentSpanAttributes": [
    {
      object (SegmentSpanAttribute)
    }
  ]
}
Fields
segment

object (Segment)

Segment details used to distinguish it from other segments.
segmentSpanAttributes[]

object (SegmentSpanAttribute)

Attributes assigned to the segment. These attributes may differ based on the path a segment is in. A span may cover the entire segment. Attribute spans will be in forward order from the vehicle location to the end of the path.

SegmentSpanAttribute

A SegmentSpanAttribute contains the annotations returned from the API.

JSON representation 
{
  "segmentSpan": {
    object (SegmentSpan)
  },
  "levelOfService": enum (LevelOfService)
}
Fields
segmentSpan

object (SegmentSpan)

Describes where on the segment the annotations apply.
levelOfService

enum (LevelOfService)

The predicted traffic level for the segment span, defined by traffic speeds expected on this segment when the vehicle arrives at the beginning of the segment.

SegmentSpan

Used to delimit a subsection of a segment. If a span covers the entire segment, startMeters would be 0 and endMeters would be the segment length.

JSON representation 
{
  "startMeters": integer,
  "endMeters": integer
}
Fields
startMeters

integer

Where the beginning of the span is from the starting point of the segment's polyline.
endMeters

integer

Where the end of the span is from the starting point of the segment's polyline.

LevelOfService

Predicted traffic bucket values, to be used for ADAS functionality, that map to general levels of traffic. The values returned by this API are independent and should not be relied on to correspond to other APIs.

Enums
LEVEL_OF_SERVICE_UNSPECIFIED Default value. This value means that there is no predicted traffic value available.
LEVEL_OF_SERVICE_STOPPED Traffic is stopped.
LEVEL_OF_SERVICE_STOP_AND_GO Traffic is stop and go.
LEVEL_OF_SERVICE_SLOW A slowdown is predicted, but no traffic jams are predicted.
LEVEL_OF_SERVICE_NORMAL Normal speed, no slowdown is predicted.