大型車両のルートと到着予定時刻を生成する

このガイドの対象読者: トラックやその他の大型車両を使用してトラベル プランニングと実行を行うサービスを構築するデベロッパー。関連するユースケースには、移動時間と距離の計算、到着予定時刻の計算、ナビゲーション アプリで使用されるルートの生成などがあります。

このガイドの内容: このガイドでは、大型車両向けルート検索機能で Routes API を使用して、大型車両（商用トラックや乗客バスなど）の特定の属性を考慮したルート、移動距離、予測移動時間、到着予定時刻をリクエストする方法について説明します。

Route Optimization API を使用して大型車両のフリートレベルの計算を行う方法については、Route Optimization トラック ルーティングのドキュメントをご覧ください。

学習内容

以下の操作について学習します。

  • 有効なルーティング リクエストを作成します。
  • 寸法、重量、その他の特性を使用して、実際の車両の車両情報を指定します。
  • ルートトークンや移動安全フラグなどのレスポンスを解釈します。

前提条件

  1. Google Cloud プロジェクトを作成し、Routes API を有効にする必要があります。
  2. プロジェクトが大型車両のルート設定用にプロビジョニングされている必要があります。大型車両のルート設定は、一部のお客様のみご利用いただけます。アクセスをリクエストするには、お問い合わせください。

制限事項

始める前に、次の制限事項と要件を把握しておく必要があります。

  • 利用可能な地域: 大型車両のルートは、米国本土 48 州（一般提供）と日本（試験運用版）で利用できます。アラスカ、ハワイ、米国領ではご利用いただけません。
  • ドライバーへのアドバイスと安全性。ドライバーは、この API から返されるルートが安全または合法であると、それのみに依存してはなりません。ルートが車両に適しているとは限らず、ルートに従うと、低い橋や大型車両が通行できない道路などの危険にドライバーがさらされる可能性があります。
  • ベスト エフォート ルート。場合によっては、API が移動制限に完全に準拠するルートを見つけられないことがあります。代わりに、制限区域を通過する可能性のある「ベスト エフォート」ルートを返します。Routes API レスポンスでは、これらのルートが routeRestrictionsPartiallyIgnored フィールドに明確にフラグ付けされます。このような場合は、他のソースデータを使用して、ルートを慎重に計画してください。計画やナビゲーションの信頼できる唯一の情報源として、フラグ付きルートを使用しないでください。
  • サポートされていない機能: 大型車両向けルート検索では、次の機能はサポートされていません。
    • トラックの通行料金
    • 制限速度
    • 放射性危険物のルーティング
  • 使用量上限: すべてのリクエストは、標準の秒間クエリ数（QPS）の上限の対象となります。

トラックのルート リクエストを作成する

トラックのルートを取得するには、車両を記述する特定のパラメータを含む HTTPS リクエストを Routes API エンドポイントに送信します。このセクションのコンセプトは、単一ルート リクエストとルート マトリックス リクエストの両方に適用されます。

エンドポイント

トラックのルート設定には、次の 2 つのエンドポイントを使用できます。

  • computeRoutes: 1 つの出発地と 1 つの目的地の間の単一のルートを計算します。
  • computeRouteMatrix: 出発地と目的地のマトリックスの距離と所要時間を計算しますが、ルート ポリラインは返しません。

主なリクエスト パラメータ

トラックのルート設定を有効にするには、リクエスト本文に次のパラメータを含める必要があります。

  • travelMode: この値を TRUCK に設定します。
  • routingPreference: この値を TRAFFIC_AWARE_OPTIMAL に設定します。
  • routeModifiers: このオブジェクトには、車両の属性を定義する vehicleInfo オブジェクトが含まれています。vehicleInfo オブジェクトについては、以下で詳しく説明します。

車両属性を指定する

リクエストを送信するには、車両を記述する vehicleInfo オブジェクトを含むリクエスト本文を指定する必要があります。この情報は、実際の車両の物理的な詳細に一致する仕様と考えてください。このサービスでは、車両の属性に基づいて道路の制限を考慮したルートを返すために、これらの詳細情報が必要です。

車両の測定

フィールド名で示されているように、車両の重量をキログラム単位で、車両の寸法をミリメートル単位で指定します。たとえば、全高はミリメートル（totalHeightMm）で指定する必要があります。トラックの寸法はフィートまたはメートルで表されることが多いため、単位の変換が必要になる場合があります。

ヤードポンド法からメートル法への変換

ヤードポンド法から変換する場合は、標準的な道路やアンダーパスのサイズ制限とともに、車両の具体的な寸法を常に考慮してください。これは、小数値の場合に特に重要です。実際の車両のサイズによっては、端数を切り上げると、車両のルートが過度に制限される可能性があります。

次に例を示します。

  • 幅: 米国のトレーラーの多くは幅が 8 フィート 6 インチ（2,590.8 mm）です。2,591 mm に切り上げると、車両が 8 フィート 6 インチを超えていることを示し、米国の道路では大型車両に分類されます。その結果、意図したものとは大きく異なる制約に従ってルートが計算されることになります。
  • 高さ: 高さ 11 フィートの橋の下を通るルートは、高さ 13.5 フィートの一般的なトラクター トレーラーには適していません。ただし、10 フィート程度の小型のボックストラックであれば、アンダーパスを通過できます。したがって、車両属性を正確に指定することが重要です。

トラックの寸法とアンダーパスの寸法を比較した図

次のコード スニペットは、vehicleInfo オブジェクトの例を示しています。

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

vehicleInfo オブジェクト フィールド

次の表に、リクエストで送信できるすべての車両と負荷の定義を示します。

フィールド 説明 メモ / 値
totalHeightMm 車両の最大高さ。 ミリメートル単位で、端数は切り捨てられます。丸め処理の詳細については、ヤードポンド法からメートル法への変換をご覧ください。
totalWidthMm 車両の最大幅。 ミリメートル単位（端数切り捨て）。
totalLengthMm 車両とトレーラーの合計の長さ。 ミリメートル単位（端数切り捨て）。
totalWeightKg 車両総重量（トレーラーと積載物を含む）。 キログラム単位で、端数は切り捨てられます。
totalAxleCount 車両とトレーラーの車軸の総数。 完全一致。
trailerInfo（省略可） オブジェクトの配列。トレーラーごとに 1 つ。 トレーラーのない車両（箱型トラックなど）の場合は省略します。
hazardousGoodsTypes（省略可） 車内の危険物を指定する配列。 EXPLOSIVES、GASES、FLAMMABLE、COMBUSTIBLE、ORGANIC、POISON、CORROSIVE、ASPIRATION_HAZARD、ENVIRONMENTAL_HAZARD、OTHER

フィールド マスクを使用する

最適な結果を得るには、リクエストに X-Goog-FieldMask ヘッダーを含めて、レスポンスに含めるフィールドを正確に指定します。フィールド マスクを使用すると、レイテンシが短縮され、重要なアドバイザリ フィールドを確実に受信できます。少なくとも、routes.travelAdvisory.routeRestrictionsPartiallyIgnored は常にフィールド マスクに含めてください。これは、ルートに車両に適用される制限が 1 つ以上あるかどうかを示すためです。

Routes API での FieldMasks の詳細については、こちらの記事をご覧ください。

有料道路

有料道路のないルートを優先するには、リクエストの routeModifiers プロパティに avoidTolls を指定します。ルート修飾子の詳細については、回避するルート機能を指定するをご覧ください。

avoidTolls を指定しても、レスポンスで有料道路を使用しないルートが返されるとは限りません。出発地と目的地の間の移動に有料道路の使用が必要になる場合があります。Routes API リクエストのフィールド マスクに routes.warnings を含めると、有料道路を含むルートには、このフィールド内で適切なアノテーションが付けられます。

その他のルーティング動作

travelMode を TRUCK に設定すると、API は大型車両の操縦性に合わせてルートを自動的に最適化します。生成されたルートでは、U ターンが回避され、小さな道路よりも州間高速道路や高速道路が優先されます。これらの動作を有効にするために、追加のパラメータや修飾子を設定する必要はありません。

computeRoutes を使用して単一のルートを計算する

computeRoutes エンドポイントを使用して、1 つの出発地と 1 つの目的地の間のトラック固有のルートを計算します。

computeRoutes リクエストの例

一般的なセミトレーラー トラックの完全な curl リクエストを次に示します。この例には、エンドポイント、ヘッダー、リクエスト本文が含まれています。

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

computeRoutes の回答の例

以下は、上記のリクエストに対するレスポンスの例です。travelAdvisory オブジェクトには routeRestrictionsPartiallyIgnored フラグが含まれていません。これは、ルートにフラグが設定されておらず、車両の属性に完全に準拠していると見なされることを示します。

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

computeRoutes レスポンスを解釈する

computeRoutes エンドポイントへのリクエストが成功すると、1 つ以上のルート候補を含む JSON レスポンス オブジェクトが返されます。

主なレスポンス フィールド
  • エンコードされたルート ジオメトリ: routes.polyline。これを使用して、地図上にルートをレンダリングできます。
  • 推定移動時間: routes.duration（秒）。大型車両のルート設定の移動時間は、道路網上の実際のトラックの観測された移動速度でトレーニングされた新しいモデルを使用します。また、予想される出発時刻に推定移動時間を加算して、到着予定時刻を計算することもできます。
  • ルートの合計距離: routes.distanceMeters（メートル単位）。
  • ルートトークン: routes.routeToken。これは、計算された正確なルートを表す不透明なトークンです。このトークンを Navigation SDK に渡すと、ドライバーに同じトラック固有のルートが表示されます。詳細については、Android または iOS の Navigation SDK ガイドをご覧ください。
ルートの安全フラグを確認する

レスポンスを受け取ったら、まずルートの安全フラグを確認する必要があります。提供されたルートに、車両に適さない制限が 1 つ以上含まれている場合、travelAdvisory.routeRestrictionsPartiallyIgnored フィールドは true に設定されます。

このフィールドは、「このルートに潜在的な問題があるかどうか」という質問に答えるフラグとして機能します。

  • false（またはレスポンスから省略）: ルートはフラグ設定されていません。リクエストで指定したパラメータに完全に準拠していると思われるルートが見つかりました。
  • true: ルートが報告されています。システムが完全に準拠したルートを見つけることができず、安全でない、または合法でない可能性がある「ベスト エフォート」ルートを返しました。このルートは細心の注意を払って使用する必要があります。

ルートのマトリックスを計算する（computeRouteMatrix）

computeRouteMatrix エンドポイントを使用すると、多数の出発地と目的地間の移動時間と距離を効率的に比較できます。たとえば、新しい集荷場所に最も近いトラックを見つけるために使用できます。目的に合った車両の出発地を特定したら、computeRoutes リクエストを発行して、提案された車両のルートの詳細とルートトークンを取得できます。

computeRouteMatrix を使用するには、リクエストのルートではなく、各 origin オブジェクト内で vehicleInfo を指定します。

computeRouteMatrix リクエストの例

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

computeRouteMatrix の回答の例

レスポンスは配列で、各オブジェクトには 1 つの出発地と目的地のペアの所要時間と distanceMeters が含まれます。

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

次のステップ