Routes API は現在プレビュー版(一般提供前)です。一般提供前のプロダクトや機能では、サポートが制限されることがあります。また、一般提供前のプロダクトや機能の変更は、他の一般提供前のバージョンと互換性がない可能性があります。一般提供前のサービスには、Google Maps Platform サービス固有の規約が適用されます。詳細については、リリース ステージの説明をご覧ください。

Routes API 移行ガイド

現在、Google Maps Platform では Directions APIDistance Matrix API がサポートされています。今回の Routes API のこのリリースには、既存の Directions API と Distance Matrix API の、次世代のパフォーマンス最適化バージョンが含まれています。

  • コンピューティング ルート: 包括的なグローバル ルーティング データとリアルタイムのトラフィックを使用して、ロケーション間のルートを計算します。
  • Compute Route Matrix: 出発地と目的地のペアについて、距離と移動時間を計算します。

Routes API には、次のような多くの新機能が含まれています。

  • TWO_WHEELER のルーティング
  • 通行料金の計算
  • トラフィックに対応したポリライン
  • ポリラインの品質管理
  • 品質レイテンシ管理
  • 結果ストリーミング(gRPC を使用する Compute Route Matrix のみ)
  • gRPC のサポート

Routes API の詳細については、Routes API をご覧ください。

このガイドでは、Directions API と Distance Matrix API を使用する既存のアプリを、新しい Routes API を使用するように移行する方法について説明します。

新しい Routes API の機能変更

Routes API では、大きく分けて Directions API と Distance Matrix API が次のように変更されます。

  • Computes ルートと Compute Route Matrix を Routes API という単一のサービスに統合

    Compute Route と Compute Route Matrix を使用するには、API Console で Routes API を有効にする必要があります。現在、Directions API と Distance Matrix API は、API Console で個別のサービスとして有効にしています。

    詳細については、Google API Console での設定をご覧ください。

  • 新しい Routes API は HTTP POST リクエストを使用します

    新しい Routes API では、HTTP POST リクエストの一部としてリクエスト本文またはヘッダーでパラメータを渡します。Directions API と Distance Matrix API では、HTTP GET リクエストを使用して URL パラメータを渡します。

    次に例を示します。

  • フィールド マスキングは必須です

    新しい Routes API を呼び出してルートを計算したり、ルート マトリックスを計算したりする場合は、レスポンスで返すフィールドを指定する必要があります。返されるフィールドのデフォルト リストはありません。このリストを省略すると、メソッドはエラーを返します。

    レスポンス フィールド マスクを作成してフィールド リストを指定します。次に、URL パラメータ $fields または fields を使用するか、HTTP/gRPC ヘッダー X-Goog-FieldMask を使用して、レスポンス フィールド マスクを各メソッドに渡します。

    フィールド マスキングは、不要なデータをリクエストしないように設計することをおすすめします。これにより、不要な処理時間と課金を防ぐことができます。

    詳しくは、返すフィールドを選択するをご覧ください。

  • Compute Route Matrix の新しいリクエスト上限

    Distance Matrix API では、次のリクエストの上限が適用されました。

    • 1 回のリクエストあたり最大 25 個の出発地または 25 か所の目的地。
    • サーバー側のリクエスト 1 回あたり最大 100 個の要素(出発地の数 x 目的地の数)。

    Compute Route Matrix には、次のリクエスト上限が適用されます。

    • 要素の数は 625 以下にしてください。

    • TRAFFIC_AWARE_OPTIMAL を指定する場合、要素の数は 100 以下にする必要があります。TRAFFIC_AWARE_OPTIMAL の詳細については、品質とレイテンシを構成するをご覧ください。

    • 場所 ID を使用して指定できる地点(出発地 + 目的地)は最大 50 個です。

  • 品質ではなくレイテンシを構成するための新しいオプション

    新しい Routes API では、ルート品質とレスポンス レイテンシを明示的に構成するために使用できる 3 つのルーティング設定がサポートされています。

    • TRAFFIC_UNAWARE(デフォルト) - ライブ トラフィック データではなく、時間に依存しない平均的なトラフィック データを使用してルートを計算します。これにより、レスポンスのレイテンシが最短になります。この設定は、Directions API と Distance Matrix API でトラフィックを使用していない場合と同じです。

    • TRAFFIC_AWARE - パフォーマンスを最適化したライブ トラフィック品質でレイテンシを削減します。この設定は Routes API で導入されたもので、Directions API や Distance Matrix API に相当する設定はありません。

      TRAFFIC_AWARE_OPTIMAL とは対照的に、一部の最適化ではレイテンシが大幅に短縮されます。

    • TRAFFIC_AWARE_OPTIMAL - 高パフォーマンスの包括的なトラフィック データ。パフォーマンスを最適化する必要はありません。この設定では、レイテンシが最も高く、Directions API と Distance Matrix API の departure_time の設定と同等になります。

      TRAFFIC_AWARE_OPTIMAL ルーティングの設定は、maps.google.com と Google マップ モバイルアプリで使用されるモードと同じです。

    Directions API と Distance Matrix API には、TRAFFIC_AWARE_OPTIMALTRAFFIC_UNAWARE と同等のオプションのみが用意されています。これらのオプションは、departure_time を設定したかどうかに基づいて暗黙的に設定されました。

    次の表は、現在の Directions API と Distance Matrix API のオプションと、新しい Routes API オプションを比較したものです。

    モード 現在 Routes API 備考
    リアルタイム交通情報なし departure_time プロパティが設定されていません TRAFFIC_UNAWARE 3 つのモードのレイテンシが最も高速です。
    リアルタイムの交通状況を適用 同等のものはありません TRAFFIC_AWARE

    Routes API によって追加された新しいモード。ETA 品質を低価格で実現し、TRAFFIC_UNAWARE よりもわずかに大きなレイテンシを提供します。

    レイテンシは TRAFFIC_AWARE_OPTIMAL よりもはるかに低くなります。

    高品質で包括的なリアルタイム トラフィック データを適用 departure_time 個のプロパティ セット TRAFFIC_AWARE_OPTIMAL

    maps.google.com や Google マップのモバイルアプリで使用されるモードと同じです。

    Compute Route Matrix の場合、リクエストの要素数(出発地の数 × 目的地の数)は 100 を超えることはできません。

    Routes API では、次の表に示すように、duration レスポンス プロパティの設定方法も変更し、現在のレスポンスで返されるプロパティを変更します。

    移動手段の種類 現在 Routes API
    時間に依存しない到着時間のないトラフィック。

    リクエストで departure_time が設定されていません。

    • duration レスポンス プロパティに含まれる到着予定時刻。
    • duration_in_traffic レスポンス プロパティは返されません。

    TRAFFIC_UNAWARE に対応しています。

    • duration レスポンス プロパティに含まれる到着予定時刻。
    • durationstaticDuration レスポンスのプロパティには同じ値が含まれます。
    リアルタイムの交通状況を考慮した到着予定時刻。

    リクエストでの departure_time の設定に対応します。

    • リアルタイムの交通状況を考慮した到着予定時刻は、duration_in_traffic レスポンス プロパティに含まれます。

    TRAFFIC_AWARE または TRAFFIC_AWARE_OPTIMAL に対応します。

    • リアルタイムの交通状況を考慮した到着予定時刻は、duration レスポンス プロパティに含まれます。
    • staticDuration レスポンス プロパティには、交通状況を考慮しないルートの移動所要時間が格納されます。
    • duration_in_traffic プロパティは返されなくなりました。

    詳細については、品質とレイテンシの構成をご覧ください。

Routes API ではサポートされていない既存の機能

次の機能は Routes API でサポートされません。

  • レスポンス形式としての XML。JSON と gRPC のみがサポートされています。

  • 逆ジオコーディング

    この機能では、Reverse Geocoding API を使用します。この API は、このユースケース向けに構築されており、高品質の結果を提供します。

Routes API に移行する

Routes API にいくつかの変更を加えました。変更の大半は現在の API と下位互換性がありますが、アプリを Routes API に移行する際に注意すべき変更点がいくつかあります。

REST API エンドポイントを更新する

Directions API を使用している場合は、新しい Routes API エンドポイントを使用するようにコードを更新します。

Directions API https://maps.googleapis.com/maps/api/directions/outputFormat?parameters
Routes API https://routes.googleapis.com/directions/v2:computeRoutes

Distance Matrix API を使用している場合は、新しい Routes API エンドポイントを使用するようにコードを更新します。

Distance Matrix API https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters
Routes API https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

HTTP リクエスト本文を使用するように URL パラメータを変換する

Directions API と Distance Matrix API を使用する場合は、構成プロパティを URL パラメータとして HTTP GET リクエストに渡します。たとえば、Directions API の場合は、次のようになります。

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

Routes API では、HTTP POST リクエストの一部として、リクエスト本文またはヘッダーでパラメータを渡します。次に例を示します。

現在のパラメータを Routes API パラメータに変換する

次の表に、現在の Directions API と Distance Matrix API で名前が変更されたパラメータ、変更されたパラメータ、プレビュー リリースでサポートされていないパラメータを示します。これらのパラメータを使用している場合は、コードを更新してください。

現在のパラメータ Routes API パラメータ 備考
destination destination 住所と Plus コードはプレビュー リリースでは使用できません。
origin origin 住所と Plus コードはプレビュー リリースでは使用できません。
alternatives computeAlternativeRoutes
arrival_time プレビューでは TRANSIT モードを使用できないため、ご利用いただけません。
avoid routeModifiers
copyrights プレビュー版リリースでは使用できません。
departure_time departureTime
distance distanceMeters 距離はメートル単位です。
duration_in_traffic Routes API で削除しました。duration を使用してください。詳細については、上記の新しい Routes API の機能の変更をご覧ください。
language languageCode
mode travelMode

TWO_WHEELER のサポートを追加しました。

TRANSIT モードはプレビューでは使用できません。

region 住所はサポートされていないため、プレビュー リリースでは使用できません。
status プレビュー版リリースでは使用できません。API から報告されたエラーには HTTP レスポンス コードを使用します。詳しくは、リクエスト エラーを処理するをご覧ください。
traffic_model プレビュー版リリースでは使用できません。
transit_mode プレビューでは TRANSIT モードを使用できないため、ご利用いただけません。
transit_routing_preference プレビューでは TRANSIT モードを使用できないため、ご利用いただけません。
units プレビュー リリースでは、距離行列では使用できません。
waypoints intermediates 住所とポリラインは、プレビュー リリースでは使用できません。
地点: optimize=true プレビュー版リリースでは使用できません。