ルートハンドルの概要

ルートハンドルは以前に計算されたルートをエンコードします。ルートハンドルを使用すると、ルートを一定期間キャッシュしたり、ルートに沿った追加データを取得したり、最新の交通情報を取得したりできます。

ルートハンドルにはルートデータは保存されないため、これを用いて元のルート計算時と同じ交通データを取得することはできません。

📘
注
ルートハンドルはルートの永続的な保存には適していません。いつでも無効化される可能性があります。

ルートハンドルを生成する

ルートハンドルを生成するには、ルート計算リクエストにreturn=routeHandleを含めます。

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.550028,13.302349&'\
'destination=52.553272,13.305195&'\
'return=routeHandle&'\
'transportMode=car&'\
'apiKey=YOUR_API_KEY'

レスポンスには、ルートレベルでrouteHandleフィールドが含まれます。

{
  "routes": [
    {
      "id": "84cfeded-3a5c-4cc2-8b74-1dce40f36710",
      "sections": [
        {
          ...
        }
      ],
      "routeHandle": "{ROUTE_HANDLE}"
    }
  ]
}

ハンドルはルートが通るパスをエンコードします。transportModeやdepartureTimeなどのリクエストパラメーターは一切保存されません。

ルートハンドルを使用する

以前に生成されたハンドルからルートを再現するには、そのハンドルを他の必要なパラメーターとともに、/v8/routes/{routeHandle}エンドポイントに送信します。

curl -gX GET 'https://router.hereapi.com/v8/routes/{ROUTE_HANDLE}?'\
'transportMode=car&'\
'apiKey=YOUR_API_KEY'

元のリクエストと同じパラメーターを使用する必要はありません。例については、「さまざまなオプションでルートを再評価する」を参照してください。

サポートされるパラメーター

/routes/{routeHandle}エンドポイントは、/routesエンドポイントのすべてのパラメーターをサポートしています。ただし、次のパラメーターは除きます。

destination
via
alternatives
routingMode

originパラメーターを指定すると、以前に計算されたルートの出発地点を更新できます。詳細については、「現在のルートを更新する」および「逸脱後に現在のルートを調整する」を参照してください。

transportModeパラメーターは、元のリクエストで使用された移動モードと一致している必要はありません。ただし、異なる移動モードを使用すると、ルートにその移動モードで通行が禁止されている道路セグメントが含まれる場合、リクエストが失敗する可能性があります。

EVパラメーター

ルートハンドルは、元のルートの計算に使用されるすべての電気自動車 (EV) パラメーターをサポートしています。ただし、次のパラメーターは除きます。

makeReachable
preferredBrands
preferredChargePointOperators
excludeChargePointOperators
excludeChargingStations

有効性

ルートハンドルは、基盤となるマップデータと密接に関連しています。次の変更により、ルートハンドルが無効になる場合があります。

**エンコーディングの変更：**エンコード方法やデコード方法が変更されると、既存のハンドルがすべて無効になります。これが発生することはほとんどありません。
**地図のトポロジーの変更：**マップデータのトポロジーが変更されると、影響を受けるすべてのハンドルが無効になります。例としては、ハイウェイ出口が追加または削除されたり、道路がマルチデジタル化された道路に分割されたりする場合が挙げられます。変更されたセグメントを含むすべてのハンドルが無効になります。また、セグメントの先頭や末尾で道路が追加や削除された場合は、この道路がルートに含まれていない場合でも、セグメントは変更されたと見なされます。トポロジーの変更はめったに発生しませんが、ルートの長さが増すにつれて発生する可能性が高くなります。
**充電スタンドの更新 (EVルート)：**充電スタンドを更新または削除すると、これらの充電スタンドを使用しているすべてのハンドルが無効になります。

ハンドルの無効化エラー

ルートハンドルはサービスの変更により無効になることもあります。この場合、サービスは次のエラーを返します。

{
  "title": "Invalid request",
  "status": 400,
  "code": "E605201",
  "cause": "RouteHandle not valid (anymore). (Re-)calculate route to retrieve new handle.",
  "action": "",
  "correlationId": "bf58bdea-ae23-49f5-8323-ad3a05fafb33"
}

このエラーが発生した場合は、元のルートを再計算して新しいルートハンドルを取得してください。

制限

ルートハンドルは最大250セクションのルートをサポートします。