- HTTP 要求
- 要求主體
- 回應主體
- PolylineQuality
- PolylineEncoding
- ReferenceRoute
- ExtraComputation
- 路徑
- RouteLabel
- RouteLeg
- 折線
- RouteLegStep
- NavigationInstruction
- 曼努佛
- RouteLegStepTravelAdvisory
- RouteLegStepLocalizedValues
- RouteLegStepTransitDetails
- TransitStopDetails
- TransitStop
- TransitDetailsLocalizedValues
- LocalizedTime
- TransitLine
- TransitAgency
- TransitVehicle
- TransitVehicleType
- RouteLegTravelAdvisory
- RouteLegLocalizedValues
- StepsOverview
- MultiModalSegment
- 可視區域
- RouteLocalizedValues
- GeocodingResults
- GeocodedWaypoint
指定一組航點和中繼路線控點,然後傳回主要路線以及選用替代路線。
注意:這種方法需要在輸入中指定回應欄位遮罩。如要提供回應欄位遮罩,您可以使用網址參數 $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 ( |
欄位 | |
---|---|
origin |
必要欄位。原始路線控點。 |
destination |
必要欄位。目的地路線控點。 |
intermediates[] |
選用設定。路線沿途的一組路線控點 (不含終點),用於在起點或經過時。最多可支援 25 個中繼路線控點。 |
travelMode |
選用設定。指定交通方式。 |
routingPreference |
選用設定。指定路線的計算方式。伺服器會嘗試使用所選的轉送偏好設定計算路徑。如果轉送偏好設定導致錯誤或多餘的延遲時間過長,系統會傳回錯誤。只有在 |
polylineQuality |
選用設定。指定折線品質的偏好設定。 |
polylineEncoding |
選用設定。指定折線的偏好編碼。 |
departureTime |
選用設定。出發時間。如果不設定這個值,這個值就會預設為您提出要求的時間。注意:當 採用 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度和最多九個小數位數。範例: |
arrivalTime |
選用設定。抵達時間。注意:只有在 採用 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度和最多九個小數位數。範例: |
computeAlternativeRoutes |
選用設定。指定是否要同時計算和路線以外的替代路線。要求如果具有中繼路線控點,就不會傳回替代路線。 |
routeModifiers |
選用設定。一組影響路線計算方式的條件。 |
languageCode |
選用設定。BCP-47 語言代碼,例如「en-US」或「sr-Latn」。詳情請參閱「萬國碼 (Unicode) 語言代碼 ID」。如需支援的語言清單,請參閱「語言支援」一文。如未提供這個值,系統就會從路線要求的位置推斷顯示語言。 |
regionCode |
選用設定。區碼,指定為 ccTLD (「頂層網域」) 的兩位字元值詳情請參閱國家/地區代碼頂層網域。 |
units |
選用設定。為顯示欄位指定測量單位。這些欄位包含 |
optimizeWaypointOrder |
選用設定。設為 true 時,服務會重新排序指定的中間路線控點,藉此將路線的整體成本降到最低。如果有任何中繼路線控點是 |
requestedReferenceRoutes[] |
選用設定。指定除了預設路徑之外,系統要計算哪些參照路徑做為要求的一部分。「參照路徑」是路線計算目標與預設路徑不同。舉例來說, |
extraComputations[] |
選用設定。可用來完成要求的額外運算清單。注意:這些額外運算可能會在回應中傳回額外欄位。您也必須在欄位遮罩中指定這些額外欄位,才能在回應中傳回。 |
trafficModel |
選用設定。指定計算交通時間時要採用的假設。這項設定會影響 |
transitPreferences |
選用設定。指定會影響 |
回應主體
v2.computeRoutes 回應訊息。
如果成功,回應主體即會包含具有以下結構的資料:
JSON 表示法 |
---|
{ "routes": [ { object ( |
欄位 | |
---|---|
routes[] |
指定 |
fallbackInfo |
在某些情況下,如果伺服器無法透過所有輸入偏好設定計算路徑結果,可以選擇改用不同計算方式。使用備用模式時,這個欄位會包含備用回應的詳細資訊。否則,系統不會設定這個欄位。 |
geocodingResults |
包含指定為地址的路線控點的地理編碼回應資訊。 |
PolylineQuality
一組指定折線品質的值。
列舉 | |
---|---|
POLYLINE_QUALITY_UNSPECIFIED |
未指定折線品質偏好設定。預設值為 OVERVIEW 。 |
HIGH_QUALITY |
指定高品質折線;該折線是使用超過 OVERVIEW 點組成的,但回應大小會增加。如需更精確的,請使用這個值。 |
OVERVIEW |
指定總覽折線 - 由少量點組成。顯示路線總覽時,請使用這個值。使用這個選項時,要求延遲時間比使用 HIGH_QUALITY 選項更短。 |
PolylineEncoding
指定要傳回的折線類型。
列舉 | |
---|---|
POLYLINE_ENCODING_UNSPECIFIED |
未指定折線類型偏好設定。預設值為 ENCODED_POLYLINE 。 |
ENCODED_POLYLINE |
指定使用折線編碼演算法編碼的折線。 |
GEO_JSON_LINESTRING |
使用 GeoJSON LineString 格式指定折線 |
ReferenceRoute
ComputeRoutesRequest 支援的參考路徑。
列舉 | |
---|---|
REFERENCE_ROUTE_UNSPECIFIED |
未使用。包含這個值的要求失敗。 |
FUEL_EFFICIENT |
省油路線。標有這個值的路徑會決定要針對燃料消耗等參數進行最佳化。 |
ExtraComputation
完成要求時要執行的額外運算作業。
列舉 | |
---|---|
EXTRA_COMPUTATION_UNSPECIFIED |
未使用。含有這個值的要求會失敗。 |
TOLLS |
路線的收費資訊。 |
FUEL_CONSUMPTION |
路線的預估燃油消耗量。 |
TRAFFIC_ON_POLYLINE |
路線的車流量感知折線。 |
HTML_FORMATTED_NAVIGATION_INSTRUCTIONS |
以格式化的 HTML 文字字串顯示 NavigationInstructions 。本內容僅供參考。此內容僅供顯示。請勿以程式輔助方式進行剖析。 |
路徑
含有路線,由一系列連接的路段所組成,連接起點、終點和中繼路線控點。
JSON 表示法 |
---|
{ "routeLabels": [ enum ( |
欄位 | |
---|---|
routeLabels[] |
|
legs[] |
構成路線的航段 (路線控點之間的路徑區段) 集合。每個路段都會對應兩個非 |
distanceMeters |
路線的移動距離 (以公尺為單位)。 |
duration |
導航路線所需的時間。如果將 時間長度以秒為單位,最多可有 9 個小數位數,並結尾為「 |
staticDuration |
行經路線所需時間 (不考慮路況)。 時間長度以秒為單位,最多可有 9 個小數位數,並結尾為「 |
polyline |
整體路線折線。這條折線是所有 |
description |
路線的說明。 |
warnings[] |
顯示路線時要顯示的警告陣列。 |
viewport |
折線的可視區域定界框。 |
travelAdvisory |
路線的其他資訊。 |
optimizedIntermediateWaypointIndex[] |
如果將 |
localizedValues |
|
routeToken |
具備 Base64 編碼的網路安全路徑符記,可傳遞至 Navigation SDK,讓 Navigation SDK 在導航期間能重建路線;如果重新規劃路線,則會在您透過呼叫 v2.computeRoutes 建立路徑時遵循原始意圖。客戶應將這個權杖視為不透明 blob。請勿用於讀取或變異。注意: |
RouteLabel
的標籤,可用於識別路徑的特定屬性,以便與其他屬性進行比較。Route
列舉 | |
---|---|
ROUTE_LABEL_UNSPECIFIED |
預設 - 不使用。 |
DEFAULT_ROUTE |
用於路線計算的預設「最佳」路線。 |
DEFAULT_ROUTE_ALTERNATE |
預設「最佳」路徑的替代方法。指定 時,系統就會傳回這類路徑。 |
FUEL_EFFICIENT |
省油路線。標有這個值的路線會確定採用節能參數,例如燃料消耗。 |
RouteLeg
包含非 via
路線控點之間的路段。
JSON 表示法 |
---|
{ "distanceMeters": integer, "duration": string, "staticDuration": string, "polyline": { object ( |
欄位 | |
---|---|
distanceMeters |
路線航段的移動距離 (以公尺為單位)。 |
duration |
瀏覽腿部所需的時間。如果將 時間長度以秒為單位,最多可有 9 個小數位數,並結尾為「 |
staticDuration |
行經航程的所需時間 (不考慮路況)。 時間長度以秒為單位,最多可有 9 個小數位數,並結尾為「 |
polyline |
這個路段的整體折線,包含每個 |
startLocation |
這個路段的起點位置。這個地點可能與提供的 |
endLocation |
這個路段的終點。這個地點可能與提供的 |
steps[] |
代表這個路段中路段的步驟陣列。每個步驟都代表一個導覽指示。 |
travelAdvisory |
包含應通知使用者有關路線的其他資訊,例如可能的交通區域限制。 |
localizedValues |
|
stepsOverview |
這個 |
Polyline
封裝編碼的折線。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位 polyline_type 。封裝折線的類型。預設為 encoded_polyline。polyline_type 只能是下列其中一項: |
|
encodedPolyline |
使用折線編碼演算法進行折線的字串編碼 |
geoJsonLinestring |
使用 GeoJSON LineString 格式指定折線。 |
RouteLegStep
包含
的區段。每個步驟對應一個導覽指示。路線路段由步數組成。RouteLeg
JSON 表示法 |
---|
{ "distanceMeters": integer, "staticDuration": string, "polyline": { object ( |
欄位 | |
---|---|
distanceMeters |
這個步驟的移動距離 (以公尺為單位)。在某些情況下,這個欄位可能會沒有值。 |
staticDuration |
在不考量路況的情況下,行經此步驟所需的時間。在某些情況下,這個欄位可能會沒有值。 時間長度以秒為單位,最多可有 9 個小數位數,並結尾為「 |
polyline |
與這個步驟相關聯的折線。 |
startLocation |
這個步驟的起點位置。 |
endLocation |
這個步驟的終點。 |
navigationInstruction |
導航指示。 |
travelAdvisory |
包含應通知使用者有關的其他資訊,例如腿部步驟可能的交通區域限制。 |
localizedValues |
|
transitDetails |
交通方式為 |
travelMode |
這個步驟使用的交通方式。 |
芒果
一組值,用於指定目前步驟要執行的導覽動作 (例如向左轉、合併或直線)。
列舉 | |
---|---|
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 |
在圓環處向 右 轉。 |
DEPART |
初始動線。 |
NAME_CHANGE |
用於表示街道名稱變更。 |
RouteLegStepTravelAdvisory
包含應告知使用者的其他資訊,例如腿部步驟可能的流量區域限制。
JSON 表示法 |
---|
{
"speedReadingIntervals": [
{
object ( |
欄位 | |
---|---|
speedReadingIntervals[] |
注意:目前未填入這個欄位。 |
RouteLegStepLocalizedValues
特定屬性的文字表示法。
JSON 表示法 |
---|
{ "distance": { object ( |
欄位 | |
---|---|
distance |
行走距離,以文字格式表示。 |
staticDuration |
在不考慮路況的情況下,以文字形式呈現的期間。 |
RouteLegStepTransitDetails
TRANSIT
路徑相關 RouteLegStep
的其他資訊。
JSON 表示法 |
---|
{ "stopDetails": { object ( |
欄位 | |
---|---|
stopDetails |
步驟抵達和出發站的相關資訊。 |
localizedValues |
|
headsign |
指定這條路線上標示在車輛或出發停靠站的行駛方向。方向通常是終點站。 |
headway |
指定從目前同一站點出發的預計時間。例如,假設班距秒數為 600,如果錯過上一班公車,下一班預計要等 10 分鐘。 時間長度以秒為單位,最多可有 9 個小數位數,並結尾為「 |
transitLine |
這個步驟中使用的大眾運輸路線相關資訊。 |
stopCount |
從出發車站到抵達停靠站的停靠站數量。這項計數包含抵達站,但不包含出發站。例如,假設您的路線是從 A 站出發,途經 B、C 兩站,最後抵達 D 站, stopCount 將傳回 3。 |
tripShortText |
時刻表和看板中顯示的文字,用於識別提供給乘客的大眾運輸行程。這段文字應明確指出服務日內的行程。例如,「538」是指 Amtrak 列車的 |
TransitStopDetails
RouteLegStep
大眾運輸停靠站的詳細資料。
JSON 表示法 |
---|
{ "arrivalStop": { object ( |
欄位 | |
---|---|
arrivalStop |
步驟抵達停靠站的相關資訊。 |
arrivalTime |
步驟的預計到達時間。 採用 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度和最多九個小數位數。範例: |
departureStop |
步驟出發站的相關資訊。 |
departureTime |
步驟的預估出發時間。 採用 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度和最多九個小數位數。範例: |
TransitStop
大眾運輸停靠站的相關資訊。
JSON 表示法 |
---|
{
"name": string,
"location": {
object ( |
欄位 | |
---|---|
name |
大眾運輸停靠站的名稱。 |
location |
停靠站的位置,以經緯度座標表示。 |
TransitDetailsLocalizedValues
RouteTransitDetails
值的本地化說明。
JSON 表示法 |
---|
{ "arrivalTime": { object ( |
欄位 | |
---|---|
arrivalTime |
時間格式 (文字表示法與對應時區)。 |
departureTime |
時間格式 (文字表示法與對應時區)。 |
LocalizedTime
本地化的時間說明。
JSON 表示法 |
---|
{
"time": {
object ( |
欄位 | |
---|---|
time |
在指定時區中以字串形式指定的時間。 |
timeZone |
包含時區。這個值是時區名稱 (如 IANA 時區資料庫中所定義),例如「America/New_York」。 |
TransitLine
包含這個步驟中使用的大眾運輸路線資訊。
JSON 表示法 |
---|
{ "agencies": [ { object ( |
欄位 | |
---|---|
agencies[] |
執行這條大眾運輸路線的運輸公司 (或運輸公司)。 |
name |
這條大眾運輸路線的全名,例如「8 Avenue 當地」。 |
uri |
這條大眾運輸路線的 URI (由運輸公司提供)。 |
color |
這條路線常用的顏色,以十六進製表示。 |
iconUri |
這條路線相關圖示的 URI。 |
nameShort |
這條大眾運輸路線的簡稱。這個名稱通常會是行號,例如「M7」或「355」。 |
textColor |
這條路線通常用於標示文字的顏色。以十六進製表示。 |
vehicle |
這條大眾運輸路線的交通工具類型, |
TransitAgency
經營大眾運輸路線的運輸公司。
JSON 表示法 |
---|
{ "name": string, "phoneNumber": string, "uri": string } |
欄位 | |
---|---|
name |
這家運輸公司的名稱。 |
phoneNumber |
運輸公司在某些地區專用的電話號碼格式。 |
uri |
運輸公司的 URI。 |
TransitVehicle
大眾運輸路線使用的車輛相關資訊。
JSON 表示法 |
---|
{ "name": { object ( |
欄位 | |
---|---|
name |
車輛的名稱 (大寫)。 |
type |
使用的交通工具類型。 |
iconUri |
此交通工具類型相關圖示的 URI。 |
localIconUri |
此交通工具類型相關圖示的 URI (根據本地交通標誌)。 |
TransitVehicleType
大眾運輸路線的車輛類型。
列舉 | |
---|---|
TRANSIT_VEHICLE_TYPE_UNSPECIFIED |
未使用。 |
BUS |
公車。 |
CABLE_CAR |
靠電纜運作的交通工具,通常在地面上行駛。空中纜車可視為 GONDOLA_LIFT 類型。 |
COMMUTER_TRAIN |
通勤鐵路。 |
FERRY |
渡輪。 |
FUNICULAR |
靠電纜從陡坡往上拉升的交通工具。纜車通常由兩個車廂組成,其中每個車廂都為另一個車廂保持平衡。 |
GONDOLA_LIFT |
空中纜車。 |
HEAVY_RAIL |
重軌電車。 |
HIGH_SPEED_TRAIN |
高速火車。 |
INTERCITY_BUS |
城際巴士。 |
LONG_DISTANCE_TRAIN |
長途火車。 |
METRO_RAIL |
輕軌電車運輸。 |
MONORAIL |
單軌電車。 |
OTHER |
所有其他車輛。 |
RAIL |
火車。 |
SHARE_TAXI |
共乘的計程車可視為一種沿路上下客的公車。 |
SUBWAY |
地下輕軌電車。 |
TRAM |
地上輕軌電車。 |
TROLLEYBUS |
無軌電車。 |
RouteLegTravelAdvisory
包含應通知使用者有關腿部步驟的額外資訊,例如可能的交通區域限制。
JSON 表示法 |
---|
{ "tollInfo": { object ( |
欄位 | |
---|---|
tollInfo |
包含特定 |
speedReadingIntervals[] |
詳細說明交通密度的速度讀取間隔。適用於 示例:
|
RouteLegLocalizedValues
特定屬性的文字表示法。
JSON 表示法 |
---|
{ "distance": { object ( |
欄位 | |
---|---|
distance |
行走距離,以文字格式表示。 |
duration |
以文字形式顯示根據路況考量的時間長度。注意:如果您未要求流量資訊,這個值會與 staticDuration 相同。 |
staticDuration |
在不考慮路況的情況下,以文字形式呈現的期間。 |
StepsOverview
提供 RouteLegStep
清單的總覽資訊。
JSON 表示法 |
---|
{
"multiModalSegments": [
{
object ( |
欄位 | |
---|---|
multiModalSegments[] |
|
MultiModalSegment
提供 RouteLeg.steps
不同多模組區隔的摘要資訊。多模態區隔定義為一或多個具有相同 RouteTravelMode
的連續 RouteLegStep
。如果 RouteLeg
未包含步驟中的任何多模組區隔,系統就不會填入這個欄位。
JSON 表示法 |
---|
{ "navigationInstruction": { object ( |
欄位 | |
---|---|
navigationInstruction |
多模態區隔的 NavigationInstruction。 |
travelMode |
多模態路段的交通方式。 |
stepStartIndex |
對應的 |
stepEndIndex |
多模態區隔結尾的對應 |
可視區域
經緯度可視區域,以 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": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }
JSON 表示法 |
---|
{ "low": { object ( |
欄位 | |
---|---|
low |
必要欄位。可視區域的低點。 |
high |
必要欄位。可視區域的高點。 |
RouteLocalizedValues
特定屬性的文字表示法。
JSON 表示法 |
---|
{ "distance": { object ( |
欄位 | |
---|---|
distance |
行走距離,以文字格式表示。 |
duration |
將路況列入考量的持續時間,以文字形式表示。注意:如果你未要求路況資訊,這個值會與 |
staticDuration |
在不考慮路況的情況下,以文字形式呈現的期間。 |
transitFare |
大眾運輸票價會以文字形式表示。 |
GeocodingResults
包含起點、目的地和中繼路線控點的
。僅針對地址路線控點填入。GeocodedWaypoints
JSON 表示法 |
---|
{ "origin": { object ( |
欄位 | |
---|---|
origin |
來源地理編碼路線控點。 |
destination |
目的地地理編碼路線控點。 |
intermediates[] |
一組中繼地理編碼路線控點清單,每個包含索引欄位的索引欄位,會依照在要求中指定路線控點的順序 (從零開始為單位) 對應。 |
GeocodedWaypoint
用來當做路線控點的地點詳細資料。僅針對地址路線控點填入。納入地理編碼結果的詳細資訊,以便判斷要進行地理編碼的地址。
JSON 表示法 |
---|
{
"geocoderStatus": {
object ( |
欄位 | |
---|---|
geocoderStatus |
表示地理編碼作業產生的狀態碼。 |
type[] |
結果的類型,會以零或多個類型標記的形式表示。支援的類型:地址類型和地址元件類型。 |
partialMatch |
表示地理編碼器沒有傳回與原始要求完全相符的結果,但可以比對部分要求的地址。建議您比對原始要求,檢查是否有拼寫錯誤和/或不完整的地址。 |
placeId |
此結果的地點 ID。 |
intermediateWaypointRequestIndex |
要求中對應中繼路線控點的索引。只有在對應的路線控點為中繼路線控點時才會填入。 |