使用 annotationPaths 以取得路徑註解

annotatePaths 方法可讓您在要求的道路路徑上取得動態流量屬性註解。這類註解在實作進階驅動程式輔助系統 (ADAS) 時非常實用。

如要取得路徑註解，您可以傳送包含要取得註解的路徑清單，以及要在這些路徑中使用的註解類型。回應會包含路徑，其中包含您先前要求的註解資料。在回應中，系統會將回應的路徑視為車輛在要求時行駛的每個路徑。

核心概念

以下各節說明瞭解 annotatePaths 方法的必要概念。

路徑和區隔

這個方法會對「路徑」資料加上註解，路徑是指車輛可能行駛的一系列已連線片段。

下圖說明兩個路徑，每個路徑都包含三個線段。

圖 1 路徑 1 圖表，包含區隔 A、B 和 C 和路徑 2，並由區隔 A、B 和 D 組成。

路徑的長度限制為 15 公里，系統會從第一個路段的起點到最後一個路段的開頭。如果最後一個片段開始的開始時間離第一個片段開頭的 15 公里，就會發生錯誤。

路徑的起點一律是假設的車輛位置，車輛可以有多條路徑結尾是不同的地點，但路徑不得從不同位置開始。

區隔註解可能因所屬的路徑而有所不同。即使兩個路徑共用部分相同片段，這些區隔的註解也可能不同。

例如，在圖 1 中：

• 路徑 1 包含：

  • 區隔 A
  • 區隔 B
  • 區隔 C

• 路徑 2 包含：

  • 區隔 A
  • 區隔 B
  • 區隔 D

在路徑 1 中，區隔 B 後面接著區隔 C；而在路徑 2 中，相同的區隔 B 後面接有不同的區隔 D。

區隔 B 對路徑 1 和路徑 2 傳回的動態屬性可能各不相同，因為在路徑 2 中正確轉彎，產生的流量可能會比路徑 1 中的直線路徑高。

服務水準

「服務等級」這個詞彙通常用於描述根據車輛速度、密度、壅塞等參數的預測車流量分類。請特別注意，本方法和本說明文件中使用的服務定義層級專屬於此方法。

以下清單說明使用的服務層級。

服務等級	值	說明
LEVEL_OF_SERVICE_UNSPECIFIED	0	預設值。這個值代表沒有可用的預測流量值。
LEVEL_OF_SERVICE_STOPPED	1	交通已停止，且車輛未移動。
LEVEL_OF_SERVICE_STOP_AND_GO	2	交通停靠，車輛行駛速度太慢，稍後車輛就會停擺。
LEVEL_OF_SERVICE_SLOW	3	系統預測車上有車多擁擠情形，且車輛行駛速度緩慢，但預計不會發生交通壅塞情形。
LEVEL_OF_SERVICE_NORMAL	4	路況良好，不會預測任何車速。

取得路徑註解

您可以將 HTTP POST 要求傳送至 annotatePaths 方法 (REST)，或呼叫 AnnotatePaths 方法 (gRPC)，取得路徑註解。

以下各節說明用於要求及接收路徑註解和 REST 參考資料的要求和回應主體。

要求主體

annotatePaths 方法要求主體包含下列內容：

• Paths：要利用動態屬性資料加上註解的路徑 (一組路徑)。這條路線的所有路徑都應具有相同的起始路段，也就是車輛所在的路段。系統會假設車輛處於第一個路段的起點。如果路徑未從相同片段開始，系統會傳回錯誤。
  • Path：要求動態屬性的路徑。
  • Segments：形成路徑的區隔已排序清單。
    • Segment：屬於路徑的區隔。
    • Polyline：如果找不到 ID，可用來識別區段的路段折線。如果兩個區隔具有相同的 ID，這個 ID 也會用於區分。折線是以標準 Google 地圖平台編碼折線演算法格式進行編碼。
    • placeId：此路段的地點 ID，可以是 DirectionalSegment 物件中 placeId 欄位的值。
• AnnotationOptions：輸入路徑的要求註解。
  • includeLevelOfService：布林值欄位。設為 true 時，回應中的區段將會加註預測的流量值。詳情請參閱本文件的「服務等級」一節。

申請規定

annotatePaths 方法的要求主體必須遵守下列後續要求：

• 路徑的開頭必須為相同片段。
• 路徑必須等於或少於 15 公里，也就是路徑的最後一個區段從第一個路段起點距離 15 公里。
• 要求必須包含少於或等於 10 個路徑。

注意： 要求主體中列出的所有欄位均為必填。

要求範例

以下範例顯示 annotatePaths 方法的要求主體。在此範例中，您傳送的路徑包含三個片段，並指定要加入服務註解層級。

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
}

回應主體

annotatePaths 方法回應主體包含下列內容：

• annotatedPaths：輸入中以要求屬性加上註解的路徑。
  • AnnotatedPath：傳回預測屬性的輸入路徑副本。
  • annotatedSegments：形成主要路徑的片段排序清單，並加上要求的屬性註解。
    • AnnotatedSegment：建構路徑的區隔，並使用動態資料屬性加上註解。
    • Segment：屬於路徑的區段。
      • placeId：此路段的地點 ID，可以是 DirectionalSegment 物件中 placeId 欄位的值。
    • SegmentSpanAttributes：指派給區隔的屬性。這些屬性可能會因路段所在的路徑而異。跨距可能會涵蓋整個區段。屬性時距將依序從車輛位置到路徑結尾。
      • SegmentSpan：說明註解在片段中的套用位置。
      • LevelOfService：路段的預測流量等級，由車輛抵達路段開頭時，這個路段的預估車速定義。詳情請參閱本文件的「服務等級」一節。

回應範例

以下範例顯示 annotatePaths 方法的要求主體。在這個範例中，您會在範例要求中要求的路徑上收到服務註解層級。

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