Directions API（従来版）によるルート検索

Directions API（従来版）を使用すると、次のことが可能になります。

• 公共交通機関、車、徒歩、自転車など、複数の移動手段のルートを検索します。
• ルートサービスは一連のウェイポイントを使用して、複数の部分から成るルートを返すことができます。
• 出発地、目的地、ウェイポイントを、テキスト文字列（「シカゴ、イリノイ」、「ダーウィン、NT、オーストラリア」など）、プレイス ID、または緯度/経度座標として指定します。

この API は、ルートを計算する際に最も効率的なルートを返します。最適化で最も重視されるのは移動時間ですが、最も効率的なルートを判断する際は、距離や進路変更の回数なども考慮される場合があります。

始める前に

Directions API（従来版）を使用するには、請求先アカウントが登録され、Directions API（従来版）が有効になっているプロジェクトが必要です。詳しくは、Cloud コンソールでのセットアップをご覧ください。

Directions API（従来版）リクエストを作成する

Directions API（従来版）のリクエストは、次の形式になります。

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

ここで、outputFormat は次のいずれかの値になります。

• json（推奨）は、JavaScript Object Notation（JSON）での出力を示します。
• xml は、XML としての出力を示します。

注: URL は、有効にするために適切にエンコードされている必要があります。また、すべてのウェブサービスで 16,384 文字に制限されています。URL を作成する際は、この上限に注意してください。

URL の標準規則と同様に、すべてのパラメータはアンパサンド（&）文字を使用して区切ります。すべての予約文字（プラス記号「+」など）は URL エンコードする必要があります。各パラメータと有効な値のリストを次に示します。

必須パラメータ

• destination

  ルートを計算するプレイス ID、住所、または緯度/経度のテキスト値。destination パラメータのオプションは、origin パラメータと同じです。

• origin

  ルートを計算する出発地のプレイス ID、住所、または緯度/経度のテキスト値。

  • プレイス ID の先頭には place_id: を付ける必要があります。プレイス ID は、Geocoding API と Places API（Place Autocomplete を含む）から取得できます。Place Autocomplete から取得したプレイス ID の使用例については、Place Autocomplete とルートをご覧ください。プレイス ID について詳しくは、プレイス ID の概要をご覧ください。

    origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
    

  • 住所を渡すと、Directions サービスはその文字列をジオコーディングして緯度と経度の座標に変換し、ルートを計算します。この座標は、Geocoding API から返される座標（建物の中心など）とは異なる場合があります（建物の入り口など）。

    origin=24+Sussex+Drive+Ottawa+ON
    

    住所や緯度/経度座標ではなく、プレイス ID を使用することをおすすめします。座標を使用すると、ポイントは常にその座標に最も近い道路にスナップされます。その道路は、目的地へのアクセス ポイントではない場合や、目的地に迅速かつ安全に到達できる道路ではない場合もあります。

  • 座標を渡すと、ポイントは最も近い道路にスナップされます。 プレイス ID を渡すことをおすすめします。座標を渡す場合は、緯度と経度の値の間にスペースを入れないでください。

    origin=41.43206,-81.38992
    

  • Plus Code は、グローバル コードまたは複合コードの形式にする必要があります。 plus code を次のような形式にします（プラス記号は %2B に URL エスケープされ、スペースは %20 に URL エスケープされます）。

    • グローバル コードは、4 文字の市外局番と 6 文字以上のローカルコードです（849VCW8+R9 は 849VCWC8%2BR9）。
    • 複合コード は、明示的な場所を含む 6 文字以上のローカルコードです（CWC8+R9 Mountain View, CA, USA は CWC8%2BR9%20Mountain%20View%20CA%20USA）。
  注: 効率と精度を高めるため、可能な場合はプレイス ID を使用してください。これらの ID は、緯度/経度の値のペアのように一意に明示され、アクセス ポイントや交通変数などのルート設定にジオコーディングのメリットをもたらします。住所とは異なり、ID を使用する場合は、サービスが検索や場所の詳細に関する中間リクエストを実行する必要がないため、パフォーマンスが向上します。

オプション パラメータ

• alternatives

  true に設定した場合、ルートサービスで複数の代替ルートを返すよう指定します。代替ルートの提供は、サーバーからの応答時間が長くなることがあるので、注意してください。これは、中間地点がないリクエストに対してのみ使用できます。詳細については、ウェイポイントに関するガイドをご覧ください。

• arrival_time

  乗換案内で優先する到着時刻を、1970 年 1 月 1 日午前 0 時（UTC）からの経過秒数で指定します。departure_time または arrival_time のいずれかを指定できますが、両方は指定できません。arrival_time は整数として指定する必要があります。

• 避ける

  指定された対象物を避けてルートを計算するよう指定します。このパラメータは、次の引数をサポートしています。

  • tolls は、有料道路や有料の橋を避けたルートを計算するよう指定します。
  • highways は、高速道路を避けたルートを計算するよう指定します。
  • ferries は、フェリーを避けたルートを計算するよう指定します。
  • indoor は、徒歩と乗換案内で屋内の階段を避けたルートを計算するよう指定します。

  avoid パラメータに複数の制限を渡すことで、有料道路、高速道路、フェリーの任意の組み合わせを避けるルートをリクエストできます。次に例を示します。

  avoid=tolls|highways|ferries.
  

• departure_time

  希望する出発時刻を指定します。時間は、1970 年 1 月 1 日午前 0 時（UTC）からの経過時間（秒）を整数で指定できます。9999-12-31T23:59:59.999999999Z より後の departure_time が指定されている場合、API は departure_time を 9999-12-31T23:59:59.999999999Z にフォールバックします。または、値として now を指定することもできます。この場合、出発時刻は現在時刻（秒単位で正確）に設定されます。出発時刻は、次の 2 つのケースで指定できます。

  • 移動手段が交通機関のリクエストの場合: 必要に応じて、departure_time または arrival_time のいずれかを指定できます。どちらの時刻も指定されていない場合、departure_time のデフォルトは現在時刻になります（つまり、出発時刻のデフォルトは現在時刻になります）。
  • 移動手段が運転のリクエストの場合: departure_time を指定すると、交通状況を考慮したルートと所要時間（レスポンス フィールド: duration_in_traffic）を取得できます。departure_time は、現在時刻または将来の時刻に設定する必要があります。過去の時刻は指定できません。
  注: 出発時刻が指定されていない場合、ルートと所要時間は、道路網と平均的な交通状況（時間的な要素を考慮に入れない）に基づいて選択されます。道路網における状況の変化、平均的な交通状況の最新情報、サービスの分散性などにより、リクエストの結果が時間の経過とともに変化する可能性があります。また、結果は、ほぼ同等のルートでも、時刻やリクエストの頻度によって異なる場合があります。
  注: mode=driving の場合に departure_time を指定する距離行列リクエストは、リクエストあたり最大 100 要素に制限されます。要素の数は、出発地の数に目的地の数を掛けた値です。

• 言語

  結果を返す言語。これは、start_address と end_address のジオコーディングされた住所、distance と duration フィールド（区間とステップ）のローカライズされたテキスト、html_instructions の操作の説明にのみ適用されます。html_instructions の名前と住所は、現地の言語と文字でフォーマットされているため、適用されません。

  • サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
  • language が指定されていない場合、API は Accept-Language ヘッダーで指定された優先言語を使用しようとします。
  • API は、ユーザーと現地の人の両方が読み取れる番地を提供するように最善を尽くします。この目標を達成するため、住所は現地語で返されます。必要に応じて、ユーザーが読み取れる文字に変換され、優先言語が考慮されます。その他の住所はすべて、優先言語で返されます。住所コンポーネントはすべて同じ言語で返されます。この言語は、最初のコンポーネントから選択されます。
  • 優先言語で名前が利用できない場合、API は最も近い一致を使用します。
  • 優先言語は、API が返す結果のセットと、それらが返される順序にわずかに影響します。ジオコーダは、言語に応じて略語を異なる方法で解釈します。たとえば、道路タイプの略語や、ある言語では有効でも別の言語では有効でない類義語などです。たとえば、utca と tér は、ハンガリー語で「通り」の同義語です。

• モード

  距離とルートの計算では、使用する移動手段を指定できます。デフォルトでは、driving モードが使用されます。デフォルトでは、ルートは運転ルートとして計算されます。サポートされている移動手段は次のとおりです。

  • driving（デフォルト）は、道路網を利用した標準の運転ルートまたは距離を示します。
  • walking は、歩行者専用道路と歩道（利用可能な場合）を通る徒歩経路または距離をリクエストします。
  • bicycling は、自転車専用道路と優先道路（利用可能な場合）を使って自転車ルートまたは距離をリクエストします。
  • transit は、公共交通機関を使用するルート（利用可能な場合）を使用して、ルートまたは距離をリクエストします。モードを乗換案内に設定した場合は、必要に応じて departure_time または arrival_time を指定できます。どちらの時刻も指定されていない場合、departure_time のデフォルトは現在時刻になります（つまり、出発時刻のデフォルトは現在時刻になります）。必要に応じて、transit_mode や transit_routing_preference を含めることもできます。乗換案内は、過去 7 日間または将来 100 日間まで利用できます。ただし、データ プロバイダから提供される乗換案内の情報が利用可能であることが条件となります。交通機関のスケジュールは頻繁に変更され、利用可能な交通機関のルートは時間の経過とともに変更される可能性があるため、かなり先の予測に対して一貫した結果を提供することは保証されません。
  注: 徒歩経路と自転車ルートには、明確な歩道や自転車専用道路が含まれていないことがあるため、これらの経路をリクエストすると、返される結果に警告が含まれます。この警告はユーザーに表示する必要があります。

• 地域

  地域コード。ccTLD（「トップレベル ドメイン」）の 2 文字の値として指定します。ほとんどの ccTLD コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、ISO 3166-1 コードは「gb」（厳密には「グレート ブリテンおよび北アイルランド連合王国」のエンティティ）です。

• traffic_model

  所要時間を計算する上での仮定条件を指定します。この設定に応じて、レスポンスで duration_in_traffic フィールドに返される値が変わります。この値は、過去の平均データに基づく予測所要時間となります。traffic_model パラメータは、リクエストに departure_time が含まれている運転ルートにのみ指定できます。このパラメータで使用できる値は次のとおりです。

  • best_guess（デフォルト）は、過去と現在の交通状況のデータを基に見積もった最適な移動時間を、duration_in_traffic で返すよう指定します。departure_time が現在時刻に近いほど、現在の交通状況が重視されます。
  • pessimistic は、普段の実際の移動時間よりも大きい値を duration_in_traffic で返すよう指定します。ただし、交通状況が極端に悪い場合は、この値よりも長い時間を要する可能性があります。
  • optimistic は、普段の実際の移動時間よりも小さい値を duration_in_traffic で返すよう指定します。ただし、交通状況が非常に良い場合は、この値よりも短時間で到着する可能性があります。

  best_guess のデフォルト値は、ほとんどのユースケースで最も有用な予測を提供します。best_guess の予測モデルがリアルタイムの交通情報を統合する方法によっては、best_guess の移動時間の予測が optimistic より短くなることも、pessimistic より長くなることもあります。

• transit_mode

  希望する移動手段を 1 つ以上指定します。このパラメータは、乗換案内でのみ指定できます。このパラメータは、次の引数をサポートしています。

  • bus は、バスを使ったルートを計算するよう指定します。
  • subway は、地下鉄を使ったルートを計算するよう指定します。
  • train は、電車を使ったルートを計算するよう指定します。
  • tram は、市街電車と路面電車を使ったルートを計算するよう指定します。
  • rail は、電車、市街電車、路面電車、地下鉄を使ったルートを計算するよう指定します。これは transit_mode=train|tram|subway と同じです。

• transit_routing_preference

  乗換ルートの設定を指定します。このパラメータを使うと、API がデフォルトで選択した最適ルートを受け取る代わりに、返されるオプションにバイアスをかけることができます。このパラメータは、乗換案内でのみ指定できます。このパラメータは、次の引数をサポートしています。

  • less_walking は、歩行距離に制限を付けてルートを計算するよう指定します。
  • fewer_transfers は、乗り換え回数に制限を付けてルートを計算するよう指定します。

• ユニット

  結果を表示するときに使用する単位系を指定します。

  ルートの結果には、距離フィールド内にテキストが含まれます。このテキストは、ルートの特定の「ステップ」の距離を示すためにユーザーに表示されることがあります。デフォルトでは、このテキストは出発地の国や地域の単位系を使用します。

  たとえば、「シカゴ、イリノイ」から「トロント、オンタリオ」へのルートはマイルで表示され、この逆のルートはキロメートルで表示されます。この単位系は、リクエストの units パラメータ内で明示的に設定することでオーバーライドできます。その場合は、次のいずれかの値を渡します。

  • metric はメートル系を使用するよう指定します。テキスト形式の距離は、キロメートルとメートルで返されます。
  • imperial はヤード・ポンド法を使用するよう指定します。テキスト形式の距離はマイルとフィートで返されます。
  注: この単位系設定は、距離フィールド内に表示されるテキストにのみ影響します。距離フィールドには、常にメートルで表現された値が格納されます。

• ウェイポイント

  注意: 10 を超える地点（11 ～ 25）、または地点の最適化を使用するリクエストは、課金レートが高くなります。Google Maps Platform サービスの課金の詳細をご覧ください。

  出発地と目的地の間のルートに含める中間地点の配列を、通過地点または経由地点として指定します。地点とは指定された場所を経由するようにルートを変更するもので、この API は、車、徒歩、自転車の移動手段のウェイポイントをサポートしています。公共交通機関はサポートしていません。プレイス ID、住所、緯度と経度の座標の形式で、1 つ以上の場所をパイプ文字（| または %7C）で区切って指定できます。デフォルトでは、指定した地点を指定した順番で通るルートが計算されます。ウェイポイントの値を解析する優先順位は、プレイス ID、緯度/経度座標、住所の順です。

  • プレイス ID を渡す場合は、先頭に place_id: を付ける必要があります。プレイス ID は、Geocoding API と Places API（Place Autocomplete を含む）から取得できます。Place Autocomplete から取得したプレイス ID の使用例については、Place Autocomplete とルートをご覧ください。プレイス ID について詳しくは、プレイス ID の概要をご覧ください。
    効率性と正確性を高めるため、可能な場合はプレイス ID を使用してください。これらの ID は、緯度と経度の値のペアのように一意に明示され、アクセス ポイントや交通変数などのルート設定にジオコーディングのメリットをもたらします。住所とは異なり、ID では、サービスが検索を実行したり、場所の詳細をリクエストしたりする必要がないため、パフォーマンスが向上します。
  • 緯度と経度の座標を渡すと、その値はフロントエンド サーバーに直接送信され、ジオコーディングなしでルートが計算されます。ポイントは道路にスナップされるため、アプリに必要な精度が得られない場合があります。座標は、アクセス ポイントや追加のジオコーディングの詳細を考慮せずに、アプリがルート設定に必要なポイントを正確に指定していることが確実な場合に使用します。緯度と経度の値は、スペース（%20）ではなくカンマ（%2C）で区切ってください。
  • 住所を渡すと、Directions サービスはその文字列をジオコーディングして緯度と経度の座標に変換し、ルートを計算します。アドレス値が曖昧な場合、類似したアドレスとの曖昧さを解消するために検索が呼び出されることがあります。たとえば、「1st Street」は完全な値である場合もあれば、「1st street NE」や「1st St SE」の部分的な値である場合もあります。この結果は、Geocoding API から返される結果とは異なる場合があります。プレイス ID を使用すると、誤解を避けることができます。
  • または、エンコード化ポリライン アルゴリズムを使用して、エンコードされた一連のポイントを指定することもできます。エンコードされたセットは、URL が大幅に短くなるため、多数のウェイポイントがある場合に便利です。すべてのウェブサービスで、URL の文字数は 16,384 文字に制限されています。
    • エンコードされたポリラインの先頭には enc: を付け、その後にコロン（:）を付ける必要があります。例: waypoints=enc:gfo}EtohhU:。
    • 複数のエンコードされたポリラインをパイプ文字（|）で区切って指定することもできます。例: waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:

  経由地と通過地点を指定してルートを調整する

  リクエスト内の各ウェイポイントについて、ルート レスポンスは legs 配列にエントリを追加して、その区間の経由地の詳細を提供します。

  立ち寄り地点を追加せずに、ウェイポイントを使用してルートに影響を与える場合は、ウェイポイントに接頭辞 via: を追加します。via: が先頭に付加されたウェイポイントは、legs 配列にエントリを追加しませんが、そのウェイポイントを経由するルートを生成します。

  次の URL は、レキシントンを通過するルートをリクエストするように、前のリクエストを変更したものです。

  https://maps.googleapis.com/maps/api/directions/json?
  origin=Boston,MA&destination=Concord,MA
  &waypoints=Charlestown,MA|via:Lexington,MA
  

  via: 接頭辞は、ユーザーが地図上でウェイポイントをドラッグしたときにルートを作成する場合に最も効果的です。これにより、ユーザーは最終的なルートをリアルタイムで確認でき、Directions API でアクセス可能な場所にウェイポイントを配置できるようになります。

  注意: 立ち寄りを避けるために via: 接頭辞を使用すると、地点の解釈が厳密なルートになります。これにより、かなりの回り道になったり、Directions API がその地点を通過するルートを作成できない場合に、ZERO_RESULTS というレスポンスのステータス コードが返されたりすることになります。

  ウェイポイントを最適化する

  デフォルトでは、指定した地点を指定した順番で通るルートが計算されます。オプションで、optimize:true を waypoints パラメータ内の最初の引数として渡すと、ルートサービスで、より効率的な順序に地点を並べ替えて、指定されたルートを最適化できます（この最適化には巡回セールスマン問題が応用されています）。最適化で最も重視されるのは移動時間ですが、最も効率的なルートを判断する際は、距離や進路変更の回数なども考慮される場合があります。ルートサービスでルートを最適化するには、すべての地点が立ち寄り場所である必要があります。

  ルートサービスで地点の順序を最適化するよう指定した場合は、その順序が routes オブジェクト内の waypoint_order フィールドで返されます。waypoint_order フィールドは、ゼロベースの値を返します。

  次の例では、ルート最適化を使用して、南オーストラリア州のアデレードから南オーストラリア州の主要なワイン産地への道路移動を計算します。

  https://maps.googleapis.com/maps/api/directions/json?
  origin=Adelaide,SA&destination=Adelaide,SA
  &waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA
  

  計算されたルートを調べると、計算では次のウェイポイント順序でウェイポイントが使用されていることがわかります。

  "waypoint_order": [ 3, 2, 0, 1 ]
  

  注意: ウェイポイントの最適化を使用するリクエストは、課金レートが高くなります。詳しくは、Google Maps Platform サービスの料金体系に関する説明をご確認ください。

次のステップ

経路の例

• 移動手段
• 交通情報
• ウェイポイントとウェイポイントの最適化
• ルートの制限
• 単位系
• 地域バイアス
• 場所の修飾子

経路検索のレスポンス

• DirectionsResponse
• DirectionsRoute
• DirectionsLeg
• DirectionsStep と DirectionsPolyline
• DirectionsTransitDetails
• DirectionsStatus
• DirectionsGeocodedWaypoint