Method: annotatePaths (Automotive)

傳回以路徑為基礎的輸入路徑，以及路徑沿途中動態屬性的註解。

HTTP 要求

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

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "paths": [
    {
      object (Path)
    }
  ],
  "annotationOptions": {
    object (AnnotationOptions)
  }
}
欄位
paths[]

object (Path)

必要欄位。要填入動態屬性資料的要求路徑。所有路徑的起始路段應具有相同的起點，而且做為車輛目前所在的路段。系統會假設車輛處於第一個路段的起點。如果路徑未從相同片段開始，系統會傳回錯誤。
annotationOptions

object (AnnotationOptions)

必要欄位。您必須在輸入路徑中加入要求的動態資料屬性。如果要求為空白，系統就不會為要求加上註解。

回應主體

AnnotatePathsResponse 包含輸入路徑，其中包含針對所有要求註解新增的額外資料。

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法 
{
  "annotatedPaths": [
    {
      object (AnnotatedPath)
    }
  ]
}
欄位
annotatedPaths[]

object (AnnotatedPath)

輸入中已加註要求屬性的路徑。

路徑

動態屬性要求的路徑。

路徑應包含相關且可行駛的路段。系統會假設路徑的路段遵循邏輯路徑，如果在輸入路段中找不到路徑，系統會傳回錯誤。舉例來說，如果路徑中的路段沒有連線端點，或路徑為空白，就會產生錯誤。

路徑目前最多只能有 15 公里。系統會從第一個路段 (假設的車輛位置) 的開頭開始測量路徑。如果路徑中的路段起點與第一個路段起點的起點相較遠超過 15 公里，系統就會傳回錯誤。最後一段路段的起點都可以在 15 公里之前到 15 公里以後。系統不會傳回部分回應。

路徑可以包含與其他路徑相同的區段，但區段註解也可能包含因路徑其他部分的差異而包含不同的回應。

JSON 表示法 
{
  "segments": [
    {
      object (Segment)
    }
  ]
}
欄位
segments[]

object (Segment)

必要欄位。形成路徑的區隔的已排序清單。

區隔

屬於路徑的區段。

JSON 表示法 
{
  "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.
}
欄位
polyline

object (Polyline)

必要欄位。區隔的折線，可在找不到 ID 時用來識別區隔，也可在兩個區隔具有相同的 ID 時加以區分。折線是採用標準 Google 地圖平台編碼折線演算法格式進行編碼。
聯集欄位 id。用於在 ID 空間內識別這個區段。必要欄位。id 只能是下列其中一項：
placeId

string

這個路段的地點 ID。用於所有 API。

AnnotationOptions

輸入路徑要求的註解。

JSON 表示法 
{
  "includeLevelOfService": boolean
}
欄位
includeLevelOfService

boolean

選用設定。如果設為 True，回應中的區隔就會加上預測的流量值。「服務等級」通常用於描述流量流量的分類，但這個 API 中的服務定義層級只屬於這個 API。

AnnotatedPath

隨預測屬性傳回的輸入路徑副本。

JSON 表示法 
{
  "annotatedSegments": [
    {
      object (AnnotatedSegment)
    }
  ]
}
欄位
annotatedSegments[]

object (AnnotatedSegment)

形成主要路徑的片段已排序清單，並加上註解。

AnnotatedSegment

建立路徑的區隔，並加上動態資料屬性註解。

JSON 表示法 
{
  "segment": {
    object (Segment)
  },
  "segmentSpanAttributes": [
    {
      object (SegmentSpanAttribute)
    }
  ]
}
欄位
segment

object (Segment)

用來與其他區隔做出區隔的區隔詳細資料。
segmentSpanAttributes[]

object (SegmentSpanAttribute)

指派給區隔的屬性。這些屬性可能會因路段所在的路徑而異。跨距可能會涵蓋整個區隔。屬性時距將依序從車輛位置到路徑結尾。

SegmentSpanAttribute

SegmentSpanAttribute 包含從 API 傳回的註解。

JSON 表示法 
{
  "segmentSpan": {
    object (SegmentSpan)
  },
  "levelOfService": enum (LevelOfService)
}
欄位
segmentSpan

object (SegmentSpan)

說明註解在區段上的位置。
levelOfService

enum (LevelOfService)

路段時距的預測流量等級，根據車輛抵達路段起點時的預期流量速度定義。

SegmentSpan

用於分隔區隔的子區段。如果跨距涵蓋整個區段，startMeters 會是 0， endMeter 則是線段長度。

JSON 表示法 
{
  "startMeters": integer,
  "endMeters": integer
}
欄位
startMeters

integer

Span 的起點是從線段折線的起點。
endMeters

integer

跨距的結束位置從線段折線的起點。

LevelOfService

預測流量區間值，用於 ADAS 功能 (對應至一般流量等級)。此 API 傳回的值各自獨立，不應依賴與其他 API 對應。

列舉
LEVEL_OF_SERVICE_UNSPECIFIED 預設值。這個值代表沒有可用的預測流量值。
LEVEL_OF_SERVICE_STOPPED 交通已停止。
LEVEL_OF_SERVICE_STOP_AND_GO 交通順暢，
LEVEL_OF_SERVICE_SLOW 系統預測有車多擁擠情形，但預計不會造成交通壅塞。
LEVEL_OF_SERVICE_NORMAL 為一般速度，不會提供車多擁擠情形。