共用方式為


Route - Post Route Directions Batch

使用 將查詢批次傳送至單一異步要求中的 取得路由指示 API。

Post Route Directions Batch API 是 HTTP POST 要求,會使用單一異步要求,將查詢批次傳送至 取得路由指示 API。 您可以呼叫 Route Directions Batch API,以異步方式執行 (async) 或同步執行 (sync)。 異步 API 可讓呼叫者批處理最多 700 700 個 查詢,並將 API 同步處理至 100 個 查詢 。 若要在同步要求中呼叫 Post Route Directions Batch API,請參閱 後路由指示批次同步處理

提交異步批次要求

異步 API 適用於處理大量相對複雜的路由要求

  • 它允許在不同的呼叫中擷取結果(可能有多個下載專案)。
  • 異步 API 已針對可靠性進行優化,預計不會遇到逾時。
  • 此 API 的批次項目數目限制為 700

當您使用異步要求提出要求時,服務預設會在響應標頭的 [位置] 字段中傳回 202 回應碼以及重新導向 URL。 應該定期檢查此 URL,直到響應資料或錯誤資訊可用為止。 異步回應會儲存 24 小時。 如果到期期間之後使用,重新導向 URL 會傳回 404 回應。

請注意,異步批次要求是長時間執行的作業。 以下是一般作業順序:

  1. 用戶端會將路線指示批次 POST 要求傳送至 Azure 地圖服務。
POST https://atlas.microsoft.com/route/directions/batch/json?api-version=1.0&subscription-key={subscription-key}
  1. 伺服器會以下欄其中一項回應:

    HTTP 202 Accepted - 已接受 Batch 要求。

    HTTP Error - 處理 Batch 要求時發生錯誤。 這可能是 400 Bad Request 或任何其他 Error 狀態代碼。

  2. 如果成功接受批次要求,回應中的 Location 標頭會包含下載批次要求結果的 URL。 此狀態 URI 如下所示:

GET https://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key} 
  1. 用戶端會在步驟 3 中取得 下載 URL 發出 GET 要求,以下載批次結果。

批次要求的 POST 本文

若要在查詢 傳送 路由指示,您將使用 要求,其中要求本文會以 格式包含 陣列,且 標頭會設定為 。 以下是包含 3 個 路由指示 查詢的範例要求本文:

{
    "batchItems": [
        { "query": "?query=47.620659,-122.348934:47.610101,-122.342015&travelMode=bicycle&routeType=eco&traffic=false" },
        { "query": "?query=40.759856,-73.985108:40.771136,-73.973506&travelMode=pedestrian&routeType=shortest" },
        { "query": "?query=48.923159,-122.557362:32.621279,-116.840362" }
    ]
}

批次中 查詢 路由指示只是部分 URL ,而不需要 通訊協定、基底 URL、路徑、api-version 和 subscription-key。 它可以接受任何支援的 路由指示,URI 參數路由方向中的字串值 查詢必須正確逸出(例如,“字元應該使用 \ 逸出),而且也應該正確編碼 URL。

異步 API 可讓呼叫者將最多 700 個 查詢批處理,並將 API 同步處理至最多 100 100 個 查詢,批次至少應包含 1 個 查詢。

下載異步批次結果

若要下載異步批次結果,您將向批次下載端點發出 GET 要求。 此 下載 URL 可以從成功 POST 批次要求的 Location 標頭取得,如下所示:

https://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

以下是下載批次結果的一般作業順序:

  1. 用戶端會使用 下載 URL傳送 GET 要求。

  2. 伺服器會以下欄其中一項回應:

    HTTP 202 Accepted - 已接受 Batch 要求,但仍正在處理中。 請稍後再試一次。

    HTTP 200 OK - 已成功處理批次要求。 回應本文包含所有批次結果。

批次回應模型

傳回的數據內容類似於異步和同步處理要求。 下載異步批次要求的結果時,如果批次已完成處理,響應主體就會包含批次回應。 此批次回應包含 summary 元件,指出屬於原始批次要求一部分的 totalRequests,以及成功執行的查詢 successfulRequests。 批次回應也包含 batchItems 數位列,其中包含批次要求中每個查詢的回應。 batchItems 會以與批次要求中傳送原始查詢完全相同的順序來包含結果。 batchItems 中的每個專案都包含 statusCoderesponse 欄位。 batchItems 中的每個 response 都是下列其中一種類型:

  • RouteDirections - 如果查詢成功完成。

  • Error - 如果查詢失敗。 在此案例中,回應會包含 codemessage

以下是 1 個成功 和 1 失敗 結果的批次回應範例:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}
POST https://atlas.microsoft.com/route/directions/batch/json?api-version=1.0

URI 參數

名稱 位於 必要 類型 Description
format
path True

JsonFormat

回應所需的格式。 僅支援 json 格式。

api-version
query True

string

Azure 地圖服務 API 的版本號碼。

要求標頭

名稱 必要 類型 Description
x-ms-client-id

string

指定要與 Microsoft Entra ID 安全性模型搭配使用的帳戶。 它代表 Azure 地圖服務帳戶的唯一標識碼,而且可以從 Azure 地圖服務管理平面帳戶 API 擷取。 若要在 Azure 地圖服務中使用 Microsoft Entra ID 安全性,請參閱下列 文章 以取得指引。

要求本文

名稱 類型 Description
batchItems

BatchRequestItem[]

要處理的查詢清單。

回應

名稱 類型 Description
200 OK

RouteDirectionsBatchResult

批次要求已成功處理。 回應本文包含所有批次結果。

202 Accepted

僅支援異步要求。 要求已接受:要求已接受進行處理。 請使用位置標頭中的 URL 來重試或存取結果。

標題

Location: string

Other Status Codes

ErrorResponse

發生未預期的錯誤。

安全性

AADToken

這些是 Entra OAuth 2.0 流程 Microsoft。 與 Azure 角色型存取配對時, 控制它可用來控制 Azure 地圖服務 REST API 的存取。 Azure 角色型訪問控制可用來指定一或多個 Azure 地圖服務資源帳戶或子資源的存取權。 任何使用者、群組或服務主體都可以透過內建角色或由一或多個 Azure 地圖服務 REST API 許可權所組成的自定義角色來授與存取權。

若要實作案例,建議您檢視 驗證概念。 總而言之,此安全性定義會透過能夠針對特定 API 和範圍進行訪問控制的物件,提供模型化應用程式的解決方案。

筆記

  • 此安全性定義 需要 使用 x-ms-client-id 標頭來指出應用程式要求存取的 Azure 地圖服務資源。 這可以從 地圖管理 API取得。

Authorization URL 專屬於 Azure 公用雲端實例。 主權雲端具有唯一的授權 URL,Microsoft Entra ID 設定。 * 透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API,從 Azure 管理 平面設定 Azure 角色型存取控制。 * Azure 地圖服務 Web SDK 的使用方式允許針對多個使用案例設定應用程式。

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱 Description
https://atlas.microsoft.com/.default https://atlas.microsoft.com/.default

subscription-key

這是當您 在 Azure 入口網站或使用 PowerShell、CLI、Azure SDK 或 REST API 建立 Azure 地圖服務帳戶時所佈建的共用密鑰。

使用此金鑰,任何應用程式都可以存取所有 REST API。 換句話說,此金鑰可用來做為帳戶中核發的主要密鑰。

針對公開的應用程式,我們建議使用 機密用戶端應用程式 方法來存取 Azure 地圖服務 REST API,以便安全地儲存您的密鑰。

類型: apiKey
位於: query

SAS Token

這是透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API,從 azure 地圖服務資源 列表 SAS 作業建立共用存取簽章令牌。

使用此令牌時,任何應用程式都有權使用 Azure 角色型訪問控制進行存取,並更精細地控制特定令牌的到期、速率和區域。 換句話說,SAS 令牌可用來讓應用程式以比共用密鑰更安全的方式控制存取。

對於公開的應用程式,我們建議在 對應帳戶資源上設定允許的來源特定清單, 以限制轉譯濫用,並定期更新 SAS 令牌。

類型: apiKey
位於: header

範例

Successfully submit a route direction batch request

範例要求

POST https://atlas.microsoft.com/route/directions/batch/json?api-version=1.0

{
  "batchItems": [
    {
      "query": "?query=47.639987,-122.128384:47.621252,-122.184408:47.596437,-122.332000&routeType=fastest&travelMode=car&maxAlternatives=99"
    },
    {
      "query": "?query=47.620659,-122.348934:47.610101,-122.342015&travelMode=bicycle&routeType=eco&traffic=false"
    },
    {
      "query": "?query=40.759856,-73.985108:40.771136,-73.973506&travelMode=pedestrian&routeType=shortest"
    }
  ]
}

範例回覆

{
  "batchItems": [
    {
      "statusCode": 400,
      "response": {
        "error": {
          "code": "400 BadRequest",
          "message": "maxAlternatives parameter value should be between 0 and 5 inclusive"
        }
      }
    },
    {
      "statusCode": 200,
      "response": {
        "formatVersion": "0.0.12",
        "routes": [
          {
            "summary": {
              "lengthInMeters": 1754,
              "travelTimeInSeconds": 386,
              "trafficDelayInSeconds": 0,
              "departureTime": "2019-06-21T22:56:23+00:00",
              "arrivalTime": "2019-06-21T23:02:49+00:00"
            },
            "legs": [
              {
                "summary": {
                  "lengthInMeters": 1754,
                  "travelTimeInSeconds": 386,
                  "trafficDelayInSeconds": 0,
                  "departureTime": "2019-06-21T22:56:23+00:00",
                  "arrivalTime": "2019-06-21T23:02:49+00:00"
                },
                "points": [
                  {
                    "latitude": 47.62094,
                    "longitude": -122.34892
                  },
                  {
                    "latitude": 47.62094,
                    "longitude": -122.3485
                  },
                  {
                    "latitude": 47.62095,
                    "longitude": -122.3476
                  },
                  {
                    "latitude": 47.60995,
                    "longitude": -122.34174
                  },
                  {
                    "latitude": 47.61011,
                    "longitude": -122.342
                  }
                ]
              }
            ],
            "sections": [
              {
                "startPointIndex": 0,
                "endPointIndex": 44,
                "sectionType": "TRAVEL_MODE",
                "travelMode": "bicycle"
              }
            ]
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "formatVersion": "0.0.12",
        "routes": [
          {
            "summary": {
              "lengthInMeters": 1772,
              "travelTimeInSeconds": 1276,
              "trafficDelayInSeconds": 0,
              "departureTime": "2019-06-21T22:56:23+00:00",
              "arrivalTime": "2019-06-21T23:17:38+00:00"
            },
            "legs": [
              {
                "summary": {
                  "lengthInMeters": 1772,
                  "travelTimeInSeconds": 1276,
                  "trafficDelayInSeconds": 0,
                  "departureTime": "2019-06-21T22:56:23+00:00",
                  "arrivalTime": "2019-06-21T23:17:38+00:00"
                },
                "points": [
                  {
                    "latitude": 40.75982,
                    "longitude": -73.98493
                  },
                  {
                    "latitude": 40.7601,
                    "longitude": -73.98483
                  },
                  {
                    "latitude": 40.75984,
                    "longitude": -73.98417
                  },
                  {
                    "latitude": 40.76047,
                    "longitude": -73.9837
                  },
                  {
                    "latitude": 40.77095,
                    "longitude": -73.9736
                  },
                  {
                    "latitude": 40.77114,
                    "longitude": -73.97356
                  }
                ]
              }
            ],
            "sections": [
              {
                "startPointIndex": 0,
                "endPointIndex": 47,
                "sectionType": "TRAVEL_MODE",
                "travelMode": "pedestrian"
              }
            ]
          }
        ]
      }
    }
  ],
  "summary": {
    "successfulRequests": 2,
    "totalRequests": 3
  }
}
operation-Location: URL to download the results of the long-running batch request.

定義

名稱 Description
BatchRequest

此類型代表 Batch 服務的要求本文。

BatchRequestItem

Batch 要求物件

DelayMagnitude

事件造成的延遲幅度。 這些值會對應至 取得流量事件詳細數據 API回應欄位 ty 的值。

DrivingSide

表示在機動點的左側與右側駕駛。

EffectiveSetting

呼叫此路由 API 時所使用的有效參數或數據。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

ErrorDetail

錯誤詳細數據。

ErrorResponse

錯誤回應

GuidanceInstructionType

指示的類型,例如,轉向或變更道路形式。

GuidanceManeuver

識別動作的程序代碼。

JsonFormat

回應所需的格式。 僅支援 json 格式。

JunctionType

動作的交匯點類型。 對於較大的環圈,會產生兩個不同的指示來輸入和離開環島。

LatLongPair

以緯度和經度表示的位置。

Response

查詢的結果。 如果查詢成功完成,則 RouteDirectionss 為 ErrorResponse,否則為 ErrorResponse。

ResponseSectionType

回報路由回應的區段類型

ResponseTravelMode

匯出路線的行進模式。 如果本節中不可能有要求的傳輸模式,此值將會設定為 other

Route
RouteDirectionsBatchItem

從路由方向 Batch 服務呼叫傳回的專案。

RouteDirectionsBatchResult

此物件會從成功的路由方向 Batch 服務呼叫傳回。

RouteGuidance

包含指引相關元素。 只有在要求指導方針且可供使用時,才會顯示此欄位。

RouteInstruction

一組描述機動的屬性,例如「向右轉」、「保持左轉」、「乘坐渡輪」、「乘坐高速公路」、「到達」。

RouteInstructionGroup

將彼此相關的指令元素序列分組。 序列範圍受限於 firstInstructionIndex 和 lastInstructionIndex。 當要求人類可讀取的文字訊息以取得指引時(instructionType=text 或標記),則 instructionGroup 會在可用時傳回摘要訊息。

RouteLeg

由點清單所組成的路線部分描述。 要求中提供的每個額外導航點,都會在傳回的路線中再增加一條腿。

RouteLegSummary

路由區段的 Summary 物件。

RouteOptimizedWaypoint

優化的方式點物件。

RouteReport

報告目前呼叫中使用的有效設定。

RouteSection

路由區段包含路由部分的其他資訊。 每個區段至少包含 startPointIndexendPointIndexsectionType的專案。

RouteSectionTec

流量事件的詳細數據,使用 TPEG2-TEC 標準中的定義。 可以包含 effectCode 並造成專案。

RouteSectionTecCause

流量事件的原因。 可以包含mainCauseCode和subCauseCode元素。 可以用來定義圖示和描述。

RouteSummary

Summary 物件

SimpleCategory

事件的類型。 目前可以是 JAM、ROAD_WORK、ROAD_CLOSURE 或其他。 如需詳細資訊,請參閱 「tec」。

Summary

批次要求結果的摘要

BatchRequest

此類型代表 Batch 服務的要求本文。

名稱 類型 Description
batchItems

BatchRequestItem[]

要處理的查詢清單。

BatchRequestItem

Batch 要求物件

名稱 類型 Description
query

string

此參數包含用來執行非結構化地理編碼作業的查詢字串。 查詢字串將會逐字傳遞至搜尋 API 進行處理。

DelayMagnitude

事件造成的延遲幅度。 這些值會對應至 取得流量事件詳細數據 API回應欄位 ty 的值。

名稱 類型 Description
0

string

未知。

1

string

次要。

2

string

溫和。

3

string

主要。

4

string

未定義,用於道路封閉和其他無限期延誤。

DrivingSide

表示在機動點的左側與右側駕駛。

名稱 類型 Description
LEFT

string

左。

RIGHT

string

右。

EffectiveSetting

呼叫此路由 API 時所使用的有效參數或數據。

名稱 類型 Description
key

string

所使用的參數名稱。

value

string

所使用的參數值。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱 類型 Description
info

object

其他資訊。

type

string

其他信息類型。

ErrorDetail

錯誤詳細數據。

名稱 類型 Description
additionalInfo

ErrorAdditionalInfo[]

錯誤其他資訊。

code

string

錯誤碼。

details

ErrorDetail[]

錯誤詳細數據。

message

string

錯誤訊息。

target

string

錯誤目標。

ErrorResponse

錯誤回應

名稱 類型 Description
error

ErrorDetail

error 物件。

GuidanceInstructionType

指示的類型,例如,轉向或變更道路形式。

名稱 類型 Description
DIRECTION_INFO

string

方向資訊。

LOCATION_ARRIVAL

string

抵達位置。

LOCATION_DEPARTURE

string

出發地點。

LOCATION_WAYPOINT

string

方向點位置。

ROAD_CHANGE

string

道路變更。

TURN

string

轉。

GuidanceManeuver

識別動作的程序代碼。

名稱 類型 Description
ARRIVE

string

你已經到達了。

ARRIVE_LEFT

string

你已經到達了。 您的目的地位於左側。

ARRIVE_RIGHT

string

你已經到達了。 您的目的地位於右側。

BEAR_LEFT

string

熊左。

BEAR_RIGHT

string

熊右。

DEPART

string

離開。

ENTER_FREEWAY

string

走高速公路。

ENTER_HIGHWAY

string

走高速公路。

ENTER_MOTORWAY

string

走高速公路。

ENTRANCE_RAMP

string

走坡道。

FOLLOW

string

跟隨。

KEEP_LEFT

string

保持左。

KEEP_RIGHT

string

保持正確。

MAKE_UTURN

string

製作U轉彎。

MOTORWAY_EXIT_LEFT

string

離開左側。

MOTORWAY_EXIT_RIGHT

string

離開右側。

ROUNDABOUT_BACK

string

四處走動。

ROUNDABOUT_CROSS

string

越過環島。

ROUNDABOUT_LEFT

string

在環形交叉路口,左方結束。

ROUNDABOUT_RIGHT

string

在環形交叉路口,右方結束。

SHARP_LEFT

string

左轉尖銳。

SHARP_RIGHT

string

向右翻轉。

STRAIGHT

string

保持直截了當。

SWITCH_MAIN_ROAD

string

切換到主幹道。

SWITCH_PARALLEL_ROAD

string

切換至平行道路。

TAKE_EXIT

string

結束。

TAKE_FERRY

string

乘坐渡輪。

TRY_MAKE_UTURN

string

嘗試進行U轉彎。

TURN_LEFT

string

左轉。

TURN_RIGHT

string

向右轉。

WAYPOINT_LEFT

string

您已到達路點。 它位於左邊。

WAYPOINT_REACHED

string

您已到達路點。

WAYPOINT_RIGHT

string

您已到達路點。 它就在右邊。

JsonFormat

回應所需的格式。 僅支援 json 格式。

名稱 類型 Description
json

string

JavaScript 物件表示法數據交換格式

JunctionType

動作的交匯點類型。 對於較大的環圈,會產生兩個不同的指示來輸入和離開環島。

名稱 類型 Description
BIFURCATION

string

分 岔

REGULAR

string

定期

ROUNDABOUT

string

環形交叉

LatLongPair

以緯度和經度表示的位置。

名稱 類型 Description
latitude

number

Latitude 屬性

longitude

number

經度屬性

Response

查詢的結果。 如果查詢成功完成,則 RouteDirectionss 為 ErrorResponse,否則為 ErrorResponse。

名稱 類型 Description
error

ErrorDetail

error 物件。

formatVersion

string

Format Version 屬性

optimizedWaypoints

RouteOptimizedWaypoint[]

優化的方式點序列。 它會顯示使用者針對原始和優化清單提供之導航點序列的索引。 例如,回應:

<optimizedWaypoints>
<waypoint providedIndex="0" optimizedIndex="1"/>
<waypoint providedIndex="1" optimizedIndex="2"/>
<waypoint providedIndex="2" optimizedIndex="0"/>
</optimizedWaypoints>

表示原始序列為 [0, 1, 2] 且優化序列為 [1, 2, 0]。 由於索引從 0 開始,原始為 “first, second, third” ,而優化則為 “second, third, first” 。

report

RouteReport

報告目前呼叫中使用的有效設定。

routes

Route[]

路由陣列

ResponseSectionType

回報路由回應的區段類型

名稱 類型 Description
CARPOOL

string

需要使用拼車(HOV/高佔用車輛)車道的路線區段。

CAR_TRAIN

string

汽車或火車路線的區段。

COUNTRY

string

區段,指出路由所在的國家/地區。

FERRY

string

渡輪路線的區段。

MOTORWAY

string

高速公路路線的路段。

PEDESTRIAN

string

僅適用於行人的路線區段。

TOLL_ROAD

string

需要付費的路線區段。

TOLL_VIGNETTE

string

需要有收費 Vignette 的路線區段。

TRAFFIC

string

包含流量資訊的路由區段。

TRAVEL_MODE

string

與要求參數相關的區段 travelMode

TUNNEL

string

屬於通道之路由的區段。

URBAN

string

位於城市區域內的路線區段。

ResponseTravelMode

匯出路線的行進模式。 如果本節中不可能有要求的傳輸模式,此值將會設定為 other

名稱 類型 Description
bicycle

string

傳回的路線已針對自行車進行優化,包括使用自行車道。

bus

string

傳回的路線已針對公交車進行優化,包括只使用公交車車道。 BETA 功能。

car

string

傳回的路線已針對汽車進行優化。

motorcycle

string

傳回的路線已針對摩托車進行優化。 BETA 功能。

other

string

本節中無法提供指定的傳輸模式

pedestrian

string

傳回的路線已針對行人進行優化,包括人行道的使用。

taxi

string

傳回的路線已針對計程車進行優化。 BETA 功能。

truck

string

傳回的路線已針對商用車輛進行優化,例如卡車。

van

string

傳回的路線已針對麵包車進行優化。 BETA 功能。

Route

名稱 類型 Description
guidance

RouteGuidance

包含指引相關元素。 只有在要求指導方針且可供使用時,才會顯示此欄位。

legs

RouteLeg[]

Legs 陣列

sections

RouteSection[]

Sections 陣列

summary

RouteSummary

Summary 物件

RouteDirectionsBatchItem

從路由方向 Batch 服務呼叫傳回的專案。

名稱 類型 Description
response

Response

查詢的結果。 如果查詢成功完成,則 RouteDirectionss 為 ErrorResponse,否則為 ErrorResponse。

statusCode

integer

HTTP 要求狀態代碼。

RouteDirectionsBatchResult

此物件會從成功的路由方向 Batch 服務呼叫傳回。

名稱 類型 Description
batchItems

RouteDirectionsBatchItem[]

包含批次結果的陣列。

summary

Summary

批次要求結果的摘要

RouteGuidance

包含指引相關元素。 只有在要求指導方針且可供使用時,才會顯示此欄位。

名稱 類型 Description
instructionGroups

RouteInstructionGroup[]

將彼此相關的指令元素序列分組。

instructions

RouteInstruction[]

描述動作的指示清單。

RouteInstruction

一組描述機動的屬性,例如「向右轉」、「保持左轉」、「乘坐渡輪」、「乘坐高速公路」、「到達」。

名稱 類型 Description
combinedMessage

string

動作的人類可讀取訊息,結合下一個指示中的訊息。 有時候,可以將兩個連續的指示合併成單一指令,以便更容易遵循。 當發生這種情況時,possibleCombineWithNext 旗標會是 true。 例如:

10. Turn left onto Einsteinweg/A10/E22 towards Ring Amsterdam
11. Follow Einsteinweg/A10/E22 towards Ring Amsterdam

指令 10 上的 possibleCombineWithNext 旗標為 true。 這向程式代碼指引的用戶端表示,它可以與指令 11 結合。 系統會針對要求人類可讀取指引的用戶端,自動合併這些指示。 combinedMessage 字段包含合併的訊息:

Turn left onto Einsteinweg/A10/E22 towards Ring Amsterdam
then follow Einsteinweg/A10/E22 towards Ring Amsterdam.
countryCode

string

3 個字元 ISO 3166-1 alpha-3 國家/地區代碼。 例如美國

drivingSide

DrivingSide

表示在機動點的左側與右側駕駛。

exitNumber

string

目前機動的高速公路出口數目。 如果結束有多個結束號碼,它們會以 “,”分隔,而且可能由 “-” 匯總,例如 “10, 13-15”。

instructionType

GuidanceInstructionType

指示的類型,例如,轉向或變更道路形式。

junctionType

JunctionType

動作的交匯點類型。 對於較大的環圈,會產生兩個不同的指示來輸入和離開環島。

maneuver

GuidanceManeuver

識別動作的程序代碼。

message

string

人類可讀的動作訊息。

point

LatLongPair

以緯度和經度表示的位置。

pointIndex

integer

與指令點相對應之聚合線條 「points」 清單中的點索引。

possibleCombineWithNext

boolean

您可以選擇性地結合指令與下一個指令。 這可用來建置訊息,例如「向左轉,然後向右轉」。

roadNumbers

string[]

下一個重大路段的路號(s)在機動后,或道路(s)的路號要跟隨。 範例:[“E34”, “N205”]

roundaboutExitNumber

integer

這表示在環島採取哪一個結束。

routeOffsetInMeters

integer

從路線起點到指令點的距離。

signpostText

string

路標上的文字,與機動最相關的文字,或應遵循的方向。

stateCode

string

ISO 3166-2 代碼的第二個部分表示的國家/地區的細分(例如,州)。 這僅適用於某些國家/地區,例如美國、加拿大和墨西哥。

street

string

動作之後下一條重要路段的街道名稱,或應遵循的街道名稱。

travelTimeInSeconds

integer

估計行進時間到對應至 routeOffsetInMeters 的點。

turnAngleInDecimalDegrees

integer

指示的方向。 如果 junctionType 指出回合指示:

  • 180 = U-turn
  • [-179, -1] = 左轉
  • 0 = 直接開啟 (0 度』 回合 )
  • [1, 179] = 右轉

如果 junctionType 表示 bifurcation 指令:

  • <0 - 保留左
  • >0 - 保持正確

RouteInstructionGroup

將彼此相關的指令元素序列分組。 序列範圍受限於 firstInstructionIndex 和 lastInstructionIndex。 當要求人類可讀取的文字訊息以取得指引時(instructionType=text 或標記),則 instructionGroup 會在可用時傳回摘要訊息。

名稱 類型 Description
firstInstructionIndex

integer

指示中第一個指令的索引,並屬於此群組。

groupLengthInMeters

integer

群組的長度。

groupMessage

string

當要求人類可讀取的文字訊息以取得指引時摘要訊息(instructionType=text 或已標記)。

lastInstructionIndex

integer

指示中最後一個指令的索引,並屬於此群組。

RouteLeg

由點清單所組成的路線部分描述。 要求中提供的每個額外導航點,都會在傳回的路線中再增加一條腿。

名稱 類型 Description
points

LatLongPair[]

Points 陣列

summary

RouteLegSummary

路由區段的 Summary 物件。

RouteLegSummary

路由區段的 Summary 物件。

名稱 類型 Description
arrivalTime

string

路線或腿部的估計抵達時間。 時間以UTC為單位。

batteryConsumptionInkWh

number

使用電耗模型估計千瓦時(kWh)的電力能耗。 如果 vehicleEngineType 設定為電動,且指定 constantSpeedConsumptionInkWhPerHundredkm,則包含 。 batteryConsumptionInkWh 的值包括回收的電力,因此可以是負數(這表示獲得能量)。 如果同時指定 maxChargeInkWh 和 currentChargeInkWh,則會封存,以確保電池電量永遠不會超過 maxChargeInkWh。 如果未指定 maxChargeInkWh 和 currentChargeInkWh,則會在耗用量計算中假設未受限制的回收。

departureTime

string

路線或腿部的估計出發時間。 時間以UTC為單位。

fuelConsumptionInLiters

number

使用燃燒耗用量模型以升為單位的估計燃料耗用量。 如果 vehicleEngineType 設定為 燃燒,且指定 constantSpeedConsumptionInLitersPerHundredkm,則包含 。 值將是非負數。

historicTrafficTravelTimeInSeconds

integer

使用時間相依的歷史流量數據計算的預估行進時間。 只有當 computeTravelTimeFor = 全部用於查詢時,才會包含 。

lengthInMeters

integer

Length In Meters 屬性

liveTrafficIncidentsTravelTimeInSeconds

integer

使用即時速度數據計算的預估行進時間。 只有當 computeTravelTimeFor = 全部用於查詢時,才會包含 。

noTrafficTravelTimeInSeconds

integer

由於交通狀況(例如擁堵)而計算的估計行程時間,好像路線上沒有延誤。 只有當 computeTravelTimeFor = 全部用於查詢時,才會包含 。

trafficDelayInSeconds

integer

根據交通資訊,由即時事件造成的秒數估計延遲。 對於規劃未來出發時間的航線,延誤一律為 0。 若要使用不同類型的流量資訊傳回其他旅行時間,必須新增parameter computeTravelTimeFor=all。

travelTimeInSeconds

integer

估計的行進時間,以秒為單位屬性,其中包含由於即時流量造成的延遲。 請注意,即使 traffic=false travelTimeInSeconds 仍然包含流量造成的延遲。 如果 DepartAt 是未來,則會使用時間相依的歷史交通數據來計算行進時間。

RouteOptimizedWaypoint

優化的方式點物件。

名稱 類型 Description
optimizedIndex

integer

從系統優化的方式點索引。

providedIndex

integer

使用者提供的方式點索引。

RouteReport

報告目前呼叫中使用的有效設定。

名稱 類型 Description
effectiveSettings

EffectiveSetting[]

呼叫此路由 API 時所使用的有效參數或數據。

RouteSection

路由區段包含路由部分的其他資訊。 每個區段至少包含 startPointIndexendPointIndexsectionType的專案。

名稱 類型 Description
delayInSeconds

integer

事件造成的延遲以秒為單位。

effectiveSpeedInKmh

integer

以公里/小時為單位的事件有效速度,平均超過其整個長度。

endPointIndex

integer

本節所套用路由中最後一個點 (位移 0) 的索引。

magnitudeOfDelay

DelayMagnitude

事件造成的延遲幅度。 這些值會對應至 取得流量事件詳細數據 API回應欄位 ty 的值。

sectionType

ResponseSectionType

回報路由回應的區段類型

simpleCategory

SimpleCategory

事件的類型。 目前可以是 JAM、ROAD_WORK、ROAD_CLOSURE 或其他。 如需詳細資訊,請參閱 「tec」。

startPointIndex

integer

本節所套用路由中第一個點 (位移 0) 的索引。

tec

RouteSectionTec

流量事件的詳細數據,使用 TPEG2-TEC 標準中的定義。 可以包含 effectCode 並造成專案。

travelMode

ResponseTravelMode

匯出路線的行進模式。 如果本節中不可能有要求的傳輸模式,此值將會設定為 other

RouteSectionTec

流量事件的詳細數據,使用 TPEG2-TEC 標準中的定義。 可以包含 effectCode 並造成專案。

名稱 類型 Description
causes

RouteSectionTecCause[]

造成陣列

effectCode

integer

對流量的影響。 包含 tec001:EffectCode 數據表中的值,如 TPEG2-TEC 標準中所定義。 可用來根據嚴重性來色彩編碼流量事件。

RouteSectionTecCause

流量事件的原因。 可以包含mainCauseCode和subCauseCode元素。 可以用來定義圖示和描述。

名稱 類型 Description
mainCauseCode

integer

流量事件的主要原因。 包含 tec002:CauseCode 數據表中的值,如 TPEG2-TEC 標準中所定義。

subCauseCode

integer

流量事件的子類別。 在mainCauseCode所定義的子原因數據表中包含值,如 TPEG2-TEC 標準中所定義。

RouteSummary

Summary 物件

名稱 類型 Description
arrivalTime

string

路線或腿部的估計抵達時間。 時間以UTC為單位。

departureTime

string

路線或腿部的估計出發時間。 時間以UTC為單位。

lengthInMeters

integer

Length In Meters 屬性

trafficDelayInSeconds

integer

根據交通資訊,由即時事件造成的秒數估計延遲。 對於規劃未來出發時間的航線,延誤一律為 0。 若要使用不同類型的流量資訊傳回其他旅行時間,必須新增parameter computeTravelTimeFor=all。

travelTimeInSeconds

integer

估計的行進時間,以秒為單位屬性,其中包含由於即時流量造成的延遲。 請注意,即使 traffic=false travelTimeInSeconds 仍然包含流量造成的延遲。 如果 DepartAt 是未來,則會使用時間相依的歷史交通數據來計算行進時間。

SimpleCategory

事件的類型。 目前可以是 JAM、ROAD_WORK、ROAD_CLOSURE 或其他。 如需詳細資訊,請參閱 「tec」。

名稱 類型 Description
JAM

string

塞車。

OTHER

string

其他。

ROAD_CLOSURE

string

道路封閉。

ROAD_WORK

string

道路工作。

Summary

批次要求結果的摘要

名稱 類型 Description
successfulRequests

integer

批次中成功的要求數目

totalRequests

integer

批次中的要求總數