Method: computeRoutes

根據一組終端機和中繼路線控點，傳回主要路徑和選擇性的替代路線。

注意：如要使用這種方法，您必須在輸入內容中指定回應欄位遮罩。您可以使用網址參數 $fields 或 fields，或使用 HTTP/gRPC 標頭 X-Goog-FieldMask (請參閱可用的網址參數和標頭) 來提供回應欄位遮罩。值是以逗號分隔的欄位路徑清單。請參閱如何建立欄位路徑的詳細說明文件。

例如，透過此方法：

  • 所有可用欄位的欄位遮罩 (手動檢查)：X-Goog-FieldMask: *
  • 路徑層級時間長度、距離和折線的欄位遮罩 (實際工作環境設定範例)：X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline

Google 不建議使用萬用字元 (*) 回應欄位遮罩，或是在頂層 (routes) 中指定欄位遮罩，原因如下：

  • 我們的伺服器只可以選取您所需的欄位，藉此協助計算運算週期，並縮短您的延遲時間，並將結果傳回給您。
  • 只選擇在實際工作環境工作中需要的欄位，可確保穩定延遲效能。我們日後可能會新增更多回應欄位，而這些新欄位可能需要額外的運算時間。如果您選取所有欄位，或是在頂層選取所有欄位，成效可能會降低，因為系統新增的所有回應會自動加入回應中。
  • 請僅選取你需要的欄位，這樣可產生較低的回應大小，進而提高網路處理量。

HTTP 要求

POST https://routes.googleapis.com/directions/v2:computeRoutes

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

要求主體

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

JSON 表示法 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  },
  "intermediates": [
    {
      object (Waypoint)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "polylineQuality": enum (PolylineQuality),
  "polylineEncoding": enum (PolylineEncoding),
  "departureTime": string,
  "computeAlternativeRoutes": boolean,
  "routeModifiers": {
    object (RouteModifiers)
  },
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "requestedReferenceRoutes": [
    enum (ReferenceRoute)
  ],
  "extraComputations": [
    enum (ExtraComputation)
  ]
}
欄位
origin

object (Waypoint)

必要欄位。起點路線控點。
destination

object (Waypoint)

必要欄位。目的地路線控點。
intermediates[]

object (Waypoint)

選填欄位，沿途的一組路線控點 (不含終點點)，用於停靠或通過。最多可支援 25 個中繼路線控點。
travelMode

enum (RouteTravelMode)

選填欄位，指定交通方式。
routingPreference

enum (RoutingPreference)

選填欄位，指定如何計算路徑。伺服器會嘗試使用所選的轉送偏好設定來計算路徑。如果轉送偏好設定導致錯誤或較長的延遲時間，則會傳回錯誤。只有在 travelMode 為 DRIVE 或 TWO_WHEELER 時，才可指定這個選項，否則要求將會失敗。
polylineQuality

enum (PolylineQuality)

選填欄位，指定您對折線的偏好設定。
polylineEncoding

enum (PolylineEncoding)

選填欄位，指定折線的編碼方式。
departureTime

string (Timestamp format)

選填欄位，出發時間。如未設定這個值，則預設值為您提出要求的時間。如果您將這個值設為已經發生的時間，請求就會失敗。

RFC3339 UTC 的「Zulu」格式的時間戳記，單位為奈秒解析度，最多可達 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
computeAlternativeRoutes

boolean

選填欄位，指定除了路線之外，是否要計算替代路徑。
routeModifiers

object (RouteModifiers)

選填欄位，一組可滿足路徑計算方式的條件。
languageCode

string

選填欄位，BCP-47 語言代碼，例如「en-US」或「sr-Latn」。詳情請參閱 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。如需支援的語言清單，請參閱語言支援。如未提供這個值，系統則會根據路線要求的位置推測顯示語言。
regionCode

string

選填欄位，以 ccTLD (「頂層網域」) 為兩個字元的值來指定區域代碼。詳情請參閱 https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains#Country_code_top-level_domains
units

enum (Units)

選填欄位，指定顯示欄位的測量單位。這包括 NavigationInstruction 中的 instruction 欄位。路徑、腿部、步距和時間長度的測量單位不受這個值影響。如未提供這個值，系統則會從要求位置推測顯示單元。
requestedReferenceRoutes[]

enum (ReferenceRoute)

選填欄位，除了預設的預設路徑外，也需指定在要求中計算的參考路徑。參考路徑是指與預設路線不同的路線計算目標。舉例來說，FUEL_EFFICIENT 參照路徑計算的計算方式會考量多種參數，以便找出最佳的燃油效率。
extraComputations[]

enum (ExtraComputation)

選填欄位，可用於完成要求的額外運算清單。注意： 這些額外運算可能會在回應中傳回額外的欄位。您必須在欄位遮罩中指定這些額外欄位，以在回應中傳回。

回應主體

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

v2.computeRoutes 回應回應訊息，

JSON 表示法 
{
  "routes": [
    {
      object (Route)
    }
  ],
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "geocodingResults": {
    object (GeocodingResults)
  }
}
欄位
routes[]

object (Route)

在您指定 compute_alternatives_routes 時，包含一組計算路徑 (最多三條)，不指定則只包含一個路徑。當這個陣列包含多個項目時，第一個項目是最建議的路徑。如果陣列是空的，表示找不到任何路線。
fallbackInfo

object (FallbackInfo)

在某些情況下，如果伺服器無法根據所有輸入偏好設定計算路線結果，則會改用不同的運算方式。使用備用模式時，這個欄位會包含備用回應的詳細資訊。否則系統會取消設定這個欄位。
geocodingResults

object (GeocodingResults)

包含指定為地址的路線控點的地理編碼回應資訊。

折線品質

指定折線品質的一組值。

列舉
POLYLINE_QUALITY_UNSPECIFIED 未指定折線品質偏好設定。預設值為 OVERVIEW。
HIGH_QUALITY 指定高品質折線，這類片段是由 OVERVIEW 以外的點所組成，但會增加回應的大小。當您需要更精準的數值時，請使用這個值。
OVERVIEW 指定總覽折線 - 由少量點組成。顯示路徑總覽時，請使用這個值。相較於使用 HIGH_QUALITY 選項，使用這個選項的延遲時間較少。

折線編碼

指定要傳回的折線類型。

列舉
POLYLINE_ENCODING_UNSPECIFIED 未指定折線類型偏好設定。預設值為 ENCODED_POLYLINE。
ENCODED_POLYLINE 指定使用折線編碼演算法編碼的折線。
GEO_JSON_LINESTRING 使用 GeoJSON LineString 格式指定折線

單位

一組值，用於指定顯示器所使用的測量單位。

列舉
UNITS_UNSPECIFIED 未指定度量單位。預設為從要求推估的測量單位。
METRIC 度量單位。
IMPERIAL 英制 (英制) 度量單位。

參考路徑

ComputeRoutesRequest 支援的參考路徑。

列舉
REFERENCE_ROUTE_UNSPECIFIED 未使用。包含此值的要求會失敗。
FUEL_EFFICIENT 省油路線。系統會判斷已加上這個路徑的路徑，以根據油耗等參數進行最佳化。

額外計算

在完成要求時執行的額外運算。

列舉
EXTRA_COMPUTATION_UNSPECIFIED 未使用。包含此值的要求會失敗。
TOLLS 路線收費資訊。
FUEL_CONSUMPTION 路線的預估油耗量。
TRAFFIC_ON_POLYLINE 路線的交通號誌折線。

路線

封裝路徑，由一系列連接的航段組成，可分為起點、終點和中間點。

JSON 表示法 
{
  "routeLabels": [
    enum (RouteLabel)
  ],
  "legs": [
    {
      object (RouteLeg)
    }
  ],
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "description": string,
  "warnings": [
    string
  ],
  "viewport": {
    object (Viewport)
  },
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "routeToken": string
}
欄位
routeLabels[]

enum (RouteLabel)

Route 的標籤，可用於識別路線的特定屬性，以與其他屬性進行比較。
legs[]

object (RouteLeg)

構成路線的一組腿 (路線點之間的路徑區隔)。每條腿都對應至兩個非 via 路線控點之間的行程。例如，沒有中間路線的航線只有一個路段。包含一個非 via 中繼路線控點的路徑有兩條腿。包含一個 via 中繼路線控點的航路只有一個路段。路段的順序會依照 Waypoint 的順序，從 origin 到 intermediates 到 destination。
distanceMeters

integer

路線的移動距離，單位為公尺。
duration

string (Duration format)

導航所需的所需時間。如果將 routingPreference 設為 TRAFFIC_UNAWARE，則此值會與 staticDuration 相同。如果將 routingPreference 設為 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，則系統會考量流量條件來計算這個值。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
staticDuration

string (Duration format)

沿著路線進行行駛的時間長度，但不考慮路況。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
polyline

object (Polyline)

整體路線折線。這個折線將是所有 legs 的綜合折線。
description

string

路線說明。
warnings[]

string

顯示路徑時顯示的警告陣列。
viewport

object (Viewport)

折線的可視區域定界框。
travelAdvisory

object (RouteTravelAdvisory)

有關路線的其他資訊。
routeToken

string

可傳遞至 NavigationSDK 的 Web 安全 base64 編碼路徑權杖，讓 Navigation SDK 可在導航期間重建路徑，且會在呼叫 v2.computeRoutes 時重新轉送原始意圖。客戶應將這個權杖視為不透明的 blob。注意：Route.route_token 僅適用於將 ComputeRoutesRequest.routing_preference 設為 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL 的要求。Route.route_token 也不支援包含 Via 路線控點的要求。

路徑標籤

Route 的標籤，可用於識別路線的特定屬性，以與其他屬性進行比較。

列舉
ROUTE_LABEL_UNSPECIFIED 預設 - 未使用。
DEFAULT_ROUTE 路徑計算傳回的預設「最佳」路線。
DEFAULT_ROUTE_ALTERNATE 這是預設「最佳」路線的替代方案。如果指定了 ComputeRoutesRequest.compute_alternative_routes，系統將傳回這類路徑。
FUEL_EFFICIENT 省油路線。包含此值的路徑已確定根據 Eco 參數 (如油耗) 最佳化。

路線

封裝非 via 路線控點之間的區隔。

JSON 表示法 
{
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "steps": [
    {
      object (RouteLegStep)
    }
  ],
  "travelAdvisory": {
    object (RouteLegTravelAdvisory)
  }
}
欄位
distanceMeters

integer

路線腿的移動距離，單位為公尺。
duration

string (Duration format)

導航腿所需的時間長度。如果 route_preference 設為 TRAFFIC_UNAWARE，則這個值會與 staticDuration 相同。如果 route_preference 為 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，則計算這個值時會考量路況。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
staticDuration

string (Duration format)

穿越腿部的所需時間，計算時不會考量路況。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
polyline

object (Polyline)

這條腿的整體折線。這包括每個 step 的折線。
startLocation

object (Location)

這條腿的起點。這可能與提供的 origin 不同。舉例來說，如果提供的 origin 不在道路上，這便是道路上的一個點。
endLocation

object (Location)

這個腿的終點位置。這可能與提供的 destination 不同。舉例來說，如果提供的 destination 不在道路上，這便是道路上的一個點。
steps[]

object (RouteLegStep)

表示這個腿中段的一系列步驟。每個步驟都代表一個瀏覽操作說明。
travelAdvisory

object (RouteLegTravelAdvisory)

封裝使用者應瞭解的其他資訊，例如可能的交通路線限制等交通路線限制。

Polyline

封裝編碼折線。

JSON 表示法 
{

  // Union field polyline_type can be only one of the following:
  "encodedPolyline": string,
  "geoJsonLinestring": {
    object
  }
  // End of list of possible types for union field polyline_type.
}
欄位
聯集欄位 polyline_type。封裝折線的類型。預設值為 encoded_polyline。polyline_type 只能是下列其中一項：
encodedPolyline

string

使用折線編碼演算法為折線的字串編碼
geoJsonLinestring

object (Struct format)

使用 GeoJSON LineString 格式指定折線

路線圖例

封裝 RouteLeg 的區隔。步驟對應單一導覽指示。路線腿由多個步驟組成。

JSON 表示法 
{
  "distanceMeters": integer,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "navigationInstruction": {
    object (NavigationInstruction)
  },
  "travelAdvisory": {
    object (RouteLegStepTravelAdvisory)
  }
}
欄位
distanceMeters

integer

這個步驟的移動距離，單位為公尺。在某些情況下，這個欄位可能沒有值。
staticDuration

string (Duration format)

完成這個步驟後，系統不會將流量狀況納入考量。在某些情況下，這個欄位可能沒有值。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
polyline

object (Polyline)

與這個步驟相關聯的折線。
startLocation

object (Location)

這個步驟的起點。
endLocation

object (Location)

這個步驟的終點位置。
navigationInstruction

object (NavigationInstruction)

導航操作說明。
travelAdvisory

object (RouteLegStepTravelAdvisory)

封裝使用者應瞭解的額外資訊，例如腿部可能的交通區域限制。

駕駛人

一組值，用來指定目前步驟要完成的導覽動作 (例如向左、合併、直接等等)。

列舉
MANEUVER_UNSPECIFIED 未使用。
TURN_SLIGHT_LEFT 稍微向左轉。
TURN_SHARP_LEFT 向左大幅轉彎。
UTURN_LEFT 請左轉。
TURN_LEFT 向左轉。
TURN_SLIGHT_RIGHT 稍微向右轉。
TURN_SHARP_RIGHT 向右向右轉。
UTURN_RIGHT 右轉。
TURN_RIGHT 請向右轉。
STRAIGHT 直走。
RAMP_LEFT 靠左坡道行駛。
RAMP_RIGHT 靠右坡道。
MERGE 合併為流量。
FORK_LEFT 使用左分支。
FORK_RIGHT 使用叉子。
FERRY 搭渡輪。
FERRY_TRAIN 搭火車搭渡輪。
ROUNDABOUT_LEFT 在圓環處左轉。
ROUNDABOUT_RIGHT 在圓環處向右轉。

航行步行旅程顧問

封裝使用者應瞭解的額外資訊，例如腿部可能的交通區域限制。

JSON 表示法 
{
  "speedReadingIntervals": [
    {
      object (SpeedReadingInterval)
    }
  ]
}
欄位
speedReadingIntervals[]

object (SpeedReadingInterval)

注意：這個欄位目前未填入資料。

航線旅遊顧問

封裝使用者應瞭解的其他資訊，例如可能的交通路線限制等交通路線限制。

JSON 表示法 
{
  "tollInfo": {
    object (TollInfo)
  },
  "speedReadingIntervals": [
    {
      object (SpeedReadingInterval)
    }
  ]
}
欄位
tollInfo

object (TollInfo)

封裝特定 RouteLeg 上的收費路段相關資訊。只有在我們預期 RouteLeg 上有收費路段時，才會填入這個欄位。如果設定這個欄位，但系統卻未填寫推測價格子欄位，我們預期道路會包含收費路段，但不知道預估價格。如果這個欄位不存在，則 RouteLeg 不會支付任何費用。
speedReadingIntervals[]

object (SpeedReadingInterval)

讀取流量密度的讀取間隔。適用於 TRAFFIC_AWARE 和 TRAFFIC_AWARE_OPTIMAL 轉送偏好設定。間隔涵蓋 RouteLg 的整個折線，且沒有重疊。指定間隔的起點與前一個間隔的終點相同。

例子：

polyline: A ---- B ---- C ---- D ---- E ---- F ---- G
speedReadingIntervals: [A,C), [C,D), [D,G).

可視區域

經緯度可視區域，以 low 和 high 點的對角線對面表示。可視區域是指封閉區域，也就是其界線。緯度範圍必須介於 -90 到 90 度之間 (含首尾)，經度範圍則必須介於 -180 到 180 之間 (含首尾)。各種情況包括：

  • 如果 low = high，可視區域由該單一點組成。

  • 如果 low.longitude > high.longitude，則將經度範圍反轉 (可視區域橫跨 180 度經度線)。

  • 如果 low.longitude = -180 度且 high.longitude = 180 度，可視區域會包含所有經度。

  • 如果 low.longitude = 180 度且 high.longitude = -180 度，經度範圍會留空。

  • 如果 low.latitude > high.latitude，則緯度範圍為空白。

您必須填入 low 和 high，且呈現的方塊不可空白 (如上述定義所指定)。空白的可視區域會導致錯誤發生。

舉例來說，這個可視區域完全涵蓋了紐約市：

{ "low": { "緯度": 40.477398, "經度": -74.259087 }, "high": { "緯度": 40.91618, "經度": -73.70018 } }

JSON 表示法 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
欄位
low

object (LatLng)

必要欄位。可視區域的低點。
high

object (LatLng)

必要欄位。可視區域的高點。

地理編碼結果

包含起點、目的地和中繼路線控點的 GeocodedWaypoint。僅填入地址路線控點。

JSON 表示法 
{
  "origin": {
    object (GeocodedWaypoint)
  },
  "destination": {
    object (GeocodedWaypoint)
  },
  "intermediates": [
    {
      object (GeocodedWaypoint)
    }
  ]
}
欄位
origin

object (GeocodedWaypoint)

來源地理編碼路線控點。
destination

object (GeocodedWaypoint)

目的地地理編碼路線點。
intermediates[]

object (GeocodedWaypoint)

中間點地理編碼路線清單，每個索引點都有一個索引欄位，且該欄位會對應至路線點的 0 定位點 (依要求中指定的順序)。

GPS 編碼方式

用來當做路線控點的位置詳細資料。僅填入地址路線控點。包含地理編碼結果的詳細資料，可用於判斷地址的地理編碼。

JSON 表示法 
{
  "geocoderStatus": {
    object (Status)
  },
  "type": [
    string
  ],
  "partialMatch": boolean,
  "placeId": string,
  "intermediateWaypointRequestIndex": integer
}
欄位
geocoderStatus

object (Status)

指出地理編碼作業產生的狀態碼。
type[]

string

結果的類型，以零或多個類型標記的形式表示。支援的類型：https://developers.google.com/maps/documentation/syndication/requests-Composite#Types
partialMatch

boolean

表示地理編碼器能傳回要求部分部分，但原始要求卻無法傳回原始要求。建議您比對原始要求，檢查是否有拼寫錯誤和/或不完整的地址。
placeId

string

這個結果的地點 ID。
intermediateWaypointRequestIndex

integer

要求中對應的中繼路線索引。只有在對應的路線控點為中繼路線控點時，才會填入資料。