Use annotatePaths to get path annotations

The annotatePaths method lets you get annotations on dynamic traffic attributes on road paths you request. These annotations can be useful for implementations of advanced driver assistance systems (ADAS).

You can get path annotations by sending a request with a list of the paths you want to get annotations on, and the types of annotations you want on these paths. The response contains the paths with the annotated data you previously requested. The paths in the response are annotated as if the vehicle was driving each path at the time of your request.

Key concepts

The following subsections describe the necessary concepts to understand the annotatePaths method.

Paths and segments

This method annotates data on paths, which are a sequence of connected segments that a vehicle might travel.

The following diagram illustrates two paths, each consisting of three segments.

Diagram illustrating a road grid, where there are two paths consisting of three segments each. The paths start with the same two segments but go in different directions in the third segment.

Figure 1. A diagram of Path 1, consisting of segments A, B, and C, and Path 2, consisting of segments A, B, and D.

A path is limited to 15 km long, and is measured from the beginning of the first segment to the beginning of the last segment. An error occurs if the beginning of the last segment starts farther than 15 km from the beginning of the first segment.

The start of a path is always the assumed vehicle location, and a vehicle can have several paths that end in different locations, but the paths can't start in different locations.

Segment annotations can differ depending on the path they are part of. Even if two paths share some of the same segments, the annotations for those segments might vary.

For example, in Figure 1:

  • Path 1 is consisted of:

    • Segment A
    • Segment B
    • Segment C

  • Path 2 is consisted of:

    • Segment A
    • Segment B
    • Segment D

In Path 1, Segment B is followed by Segment C, and in Path 2, the same Segment B is followed by a different segment, Segment D.

Segment B may have different dynamic attributes returned for Path 1 and Path 2 since the right turn in Path 2 may yield higher traffic than the straight path in Path 1.

Levels of service

A Level of Service is a generally-used term to describe categorization of predicted traffic flow based on vehicle speed, density, congestion, and other parameters. It's important to note that the levels of service definitions used in this method and described in this documentation are proprietary and unique to the method.

The following list describes the levels of service used.

Level of service Value Description
LEVEL_OF_SERVICE_UNSPECIFIED 0 Default value. This value means that there is no predicted traffic value available.
LEVEL_OF_SERVICE_STOPPED 1 Traffic is stopped and the vehicle is not moving.
LEVEL_OF_SERVICE_STOP_AND_GO 2 Traffic is stop and go and the vehicle is moving at low speed and stopping soon after.
LEVEL_OF_SERVICE_SLOW 3 A traffic slowdown is predicted and the vehicle is moving slowly but no traffic jams are predicted.
LEVEL_OF_SERVICE_NORMAL 4 Traffic is at normal speed and no slowdown is predicted.

Get path annotations

You can get a path annotations by sending an HTTP POST request to the annotatePaths method (REST) or by calling the AnnotatePaths method (gRPC).

The following subsections describe the request and response bodies used to request and receive path annotations and links to the REST reference.

Request body

The annotatePaths method request body contains the following:

  • Paths: The requested route (set of paths) to be annotated with dynamic attribute data. All paths on this route should have the same starting segment, being the segment that the vehicle is on. The vehicle is assumed to be at the start of the first segment. If paths don't start at the same segment, an error is returned.
    • Path: A path that dynamic attributes are being requested on.
    • Segments: An ordered list of segments that forms the path.
      • Segment: A segment that belongs to a path.
      • Polyline: The segment's polyline that can be used to identify the segment if the ID cannot be found. It also serves 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.
      • placeId: The place ID for this road segment that can be the same value of the placeId field from the DirectionalSegment object.
  • AnnotationOptions: The requested annotations for the input paths.
    • includeLevelOfService: A boolean field. When set to true, the segments in the response are annotated with predicted traffic values. See the Levels of service section of this document for more information.

Request requirements

The request body for the annotatePaths method must follow the next requirements:

  • Paths must start with the same segment.
  • Paths must be equal to or shorter than 15 km, where the last segment of the path starts no further than 15 km from the beginning of its first segment.
  • The request must contain less or equal to 10 paths.

Sample request

The following example shows a request body of the annotatePaths method. In this example you are sending one path consisting of three segments, specifying that you want to include the level of service annotations.

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
}

Response body

The annotatePaths method response body contains the following:

  • annotatedPaths: Paths from the input annotated with requested attributes.
    • AnnotatedPath: A copy of an input path returned with predicted attributes.
    • annotatedSegments: 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.
      • Segment: A segment that belongs to a path.
        • placeId: The place ID for this road segment that can be the same value of the placeId field from the DirectionalSegment object.
      • SegmentSpanAttributes: 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.
        • SegmentSpan: Describes where on the segment the annotations apply.
        • 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. See the Levels of service section of this document for more information.

Sample response

The following example shows a request body of the annotatePaths method. In this example you receive the level of service annotations on the one path requested in the Sample request.

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