Google Maps Directions API

はじめに

Google Maps Directions API は、HTTP リクエストを使用して地点間のルートを計算するサービスです。

このビデオでは、Google Maps Directions API を活用してユーザーがルートを検索できるようにする方法を示しています。ビデオでは、モバイルアプリで API を使用している場合に API キーを保護するにはサーバー経由のウェブサービスをプロキシするようアドバイスしています。

複数の移動モード（交通機関、車、徒歩、自転車など）のルートを検索できます。ルートでは、出発地、目的地、ウェイポイントをテキスト文字列（「Chicago, IL」や「Darwin, NT, Australia」など）または緯度と経度の座標で指定できます。Directions API は一連のウェイポイントを使用して、複数の部分から成るルートを返すことができます。

このサービスは、主に静的な（既知の）住所のルートを計算してアプリケーションの内容をマップ上に配置することを目的に設計されています。リアルタイムのユーザー入力に応答することなどを目的とはしていません。ユーザー インターフェース要素内などでの動的ルート計算については、Google Maps JavaScript API ルートサービスのドキュメントをご覧ください。

ルート計算は、多くの時間とリソースを消費するタスクです。可能な場合は、ここで説明するサービスを使用して既知の住所をあらかじめ計算し、結果を専用の一時キャッシュに格納しておきます。

キーの取得 使用制限

対象読者

このドキュメントは、Google Maps API のいずれかが提供するマップでルートデータを計算するウェブサイトやモバイル端末のデベロッパーを対象としています。また、API の使用の概要や使用可能なパラメータに関するリファレンス マテリアルを示しています。

ルート リクエスト

Google Maps Directions API リクエストの形式は次のとおりです。

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

output には次のいずれかの値を設定します。

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

HTTP で Google Maps Directions API にアクセスするには、次を使用します。

http://maps.googleapis.com/maps/api/directions/output?parameters

機密性の高いユーザーデータ（ユーザーの位置情報など）を含むアプリケーションでは、リクエストに HTTPS を使用することをお勧めします。

Google Maps Directions API の URL は約 2,000 文字（URL のエンコード後）に制限されます。一部の Google Maps Directions API の URL には経路に沿って多数の地点が含まれている可能性があるため、URL の作成時にはこの制限に注意してください。

リクエスト パラメータ

パラメータには、必須パラメータと省略可能なパラメータがあります。URL の標準に従い、すべてのパラメータはアンパサンド（&）文字で区切ります。各パラメータと有効な値のリストを次に示します。

必須パラメータ

• origin: ルート計算の始点となる住所、テキスト表記の緯度と経度の値、プレイス ID。
  • 住所を文字列として渡す場合、ルートサービスは文字列をジオコーディングして緯度と経度の座標に変換し、ルートを計算します。この座標は、Google Maps Geocoding API で返された座標とは異なる場合があります（建物の中心ではなく建物の入り口など）。
  • 座標が渡されると、座標をそのまま使用してルートを計算します。緯度と経度の値の間にはスペースを入れないようにしてください。
  • プレイス ID には place_id: という接頭辞を付ける必要があります。プレイス ID は、リクエストに API キーまたは Google Maps API for Work クライアント ID が含まれている場合にのみ指定できます。プレイス ID は、Google Maps Geocoding API と Google Places API（プレイス オートコンプリートを含む）から取得できます。プレイス オートコンプリートのプレイス ID の使用例については、プレイス オートコンプリートとルートをご覧ください。プレイス ID の詳細については、プレイス ID の概要をご覧ください。
• destination: ルート計算の終点となる住所、テキスト表記の緯度と経度の値、プレイス ID。destination パラメータのオプションは、上記の origin パラメータと同じです。
• key: アプリケーションの API キーです。このキーを使ってアプリケーションを識別し、割り当て量を管理します。詳細については、キーの取得をご覧ください。

注: Google Maps API for Work のユーザーは、ルート リクエストに有効な client と signature のパラメータを含める必要があります。詳細については、Google Maps API for Work ウェブサービスの章をご覧ください。

省略可能なパラメータ

• mode（デフォルトは driving）: ルートを計算する際に使用する移動モードを指定します。有効な値と他のリクエストの詳細は、交通手段に記載しています。
• waypoints: ウェイポイントの配列を指定します。ウェイポイントとは指定された場所を経由するようにルートを変更するもので、緯度と経度の座標、プレイス ID、ジオコーディングされる住所のいずれかで指定されます。プレイス ID には place_id: という接頭辞を付ける必要があります。プレイス ID は、リクエストに API キーまたは Google Maps API for Work クライアント ID が含まれている場合にのみ指定できます。ウェイポイントは車、徒歩、自転車のルートでのみサポートされます（ウェイポイントの詳細については、後述のルート内でのウェイポイントの使用をご覧ください）。
• alternatives: true に設定すると、ルートサービスがレスポンスで複数の代替ルートを提供することを指定します。代替ルートの提供は、サーバーからの応答時間が長くなることがあるので、注意してください。
• avoid: 指定された対象物を避けたルートを計算するよう指定します。このパラメータは次の引数をサポートします。
  • tolls は有料道路や有料橋を避けたルートを計算するよう指定します。
  • highways は幹線道路を避けたルートを計算するよう指定します。
  • ferries はフェリーを避けたルートを計算するよう指定します。
  • indoor は徒歩や交通機関のルートの場合に屋内のルートを避けて計算するよう指定します。デフォルトで屋内ルートを受け取るのは、API キーまたは Google Maps API for Work クライアント ID を含むリクエストのみです。
  詳細については、下記のルート制限をご覧ください。
• language: 結果を返すときの言語を指定します。サポートされるドメイン言語のリストをご覧ください。サポートされる言語は頻繁に更新されるため、このリストがすべてのサポート言語を網羅しているとは限りません。language を指定しないと、このサービスではリクエストの送信元のドメインの言語が使用されます。
• units: 結果を表示する際に使用する単位系を指定します。使用可能な値については、後述の単位系をご覧ください。
• region: ccTLD（「トップレベル ドメイン」）の 2 文字の値として指定される地域コードを指定します（詳細については、後述の地域のバイアスをご覧ください）。
• arrival_time: 交通機関のルートに希望する到着時刻を指定します（1970 年 1 月 1 日深夜 0 時からの経過秒数（UTC））。指定できるのは、departure_time または arrival_time のいずれかです。両方は指定できません。arrival_time は、整数で指定してください。
• departure_time: 希望する出発時刻を指定します。この時刻は整数で指定できます（1970 年 1 月 1 日深夜 0 時からの経過秒数（UTC））。または、now の値を指定して、出発時刻を現在時刻に設定することもできます（正確には最も近い秒）。次の 2 つの場合に出発時刻を指定します。
  • リクエストの交通手段が交通機関の場合:必要に応じて、departure_time または arrival_time のいずれかを指定できます。いずれの時刻も指定されていない場合、デフォルト値は departure_time（now）になります（つまり、出発時刻が現在時刻にデフォルト設定されます）。
  • リクエストの交通手段が車の場合:departure_time を指定して、交通状況が考慮されたルートと移動時間を受信できます（応答フィールド: duration_in_traffic）。このオプションは、リクエストに有効な API キーが含まれているか、有効な Google Maps API for Work クライアント ID と署名が含まれている場合にのみ使用できます。departure_time は現在時刻か、それ以降の時刻に設定する必要があります。過去の時刻は指定できません。
• traffic_model（デフォルトは best_guess）- 所要時間を計算する際に使用する仮定を指定します。この設定に応じて、レスポンスで duration_in_traffic フィールドに返される値が変わります。この値は、過去の平均データに基づく予測所要時間となります。traffic_model パラメータは、リクエストに departure_time が含まれている車のルートで、リクエストに API キーまたは Google Maps API for Work クライアント ID が含まれる場合にのみ指定できます。このパラメータの使用可能な値は次のとおりです。
  • best_guess（デフォルト）は、過去と現在の交通状況のデータを基に見積もった最適な移動時間を、duration_in_traffic で返すよう指定します。departure_time が現在時刻に近いほど、現在の交通状況は重要になります。
  • pessimistic は、普段の実際の移動時間よりも大きい値を duration_in_traffic で返すよう指定します。ただし、交通状況が極端に悪い日は、この値よりも長い時間を要する可能性があります。
  • optimistic は、普段の実際の移動時間よりも小さい値を duration_in_traffic で返すよう指定します。ただし、交通状況が非常に良い日は、この値よりも短時間で到着する可能性があります。
• transit_mode: 1 つ以上の希望する交通機関モードを指定します。このパラメータは、交通機関のルートで、リクエストに API キーまたは Google Maps API for Work クライアント ID が含まれる場合にのみ指定できます。このパラメータは次の引数をサポートします。
  • bus は、バスを使ったルートを計算するよう指定します。
  • subway は、地下鉄を使ったルートを計算するよう指定します。
  • train は、列車を使ったルートを計算するよう指定します。
  • tram は、市街電車やライトレールを使ったルートを計算するよう指定します。
  • rail は、列車や市街電車、ライトレール、地下鉄を使ったルートを計算するよう指定します。これは、transit_mode=train|tram|subway と同等です。
• transit_routing_preference: 交通機関のルートの優先度を指定します。このパラメータを使用すると、API がデフォルトで選択した最適なルートを受け取る代わりに、返されるオプションにバイアスをかけることができます。このパラメータは、交通機関のルートで、リクエストに API キーまたは Google Maps API for Work クライアント ID が含まれる場合にのみ指定できます。このパラメータは次の引数をサポートします。
  • less_walking は、歩行距離に制限を付けてルートを計算するよう指定します。
  • fewer_transfers は、乗り換え回数に制限を付けてルートを計算するよう指定します。

ルート リクエストの例

次のリクエストは、オンタリオ州トロントからケベック州モントリオールまでの車のルートを返します。

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY

mode と avoid のパラメータを変更して、主要幹線道路を避けた風光明媚な自転車旅のルートを返すように最初のリクエストを変更できます。

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&key=YOUR_API_KEY

次のリクエストは、ニューヨーク市ブルックリンからニューヨーク市クイーンズまでの交通機関のルートを検索します。リクエストに departure_time が指定されていないため、出発時刻が現在時刻にデフォルト設定されます。

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&key=YOUR_API_KEY

次のリクエストには、特定の出発時刻が含まれています。

注:この例では、出発時刻は 2012 年 7 月 30 日午前 9 時 45 分に指定されています。エラーを回避するには、リクエストを送信する前にパラメータを現在時刻より後の時間に変更する必要があります。

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&departure_time=1343641500&mode=transit&key=YOUR_API_KEY

次のリクエストは、プレイス ID を使用して英国のグラスゴーから英国のパースまでの車のルートを返します。

https://maps.googleapis.com/maps/api/directions/json?origin=place_id:ChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id:ChIJA01I-8YVhkgRGJb0fW4UX7Y&key=YOUR_API_KEY

交通手段

ルートを計算する場合、使用する移動 mode を指定できます。デフォルトでは、ルートは driving のルートとして計算されます。サポートされる交通手段は次のとおりです。

• driving（デフォルト）は、道路網を使用した標準の車のルートを示します。
• walking は、歩行者専用道路と歩道を通る徒歩ルートをリクエストします（可能な場合）。
• bicycling は、自転車専用道路と優先道路を通る自転車ルートをリクエストします（可能な場合）。
• transit は、公共交通機関を使用するルートをリクエストします（可能な場合）。このモードを transit に設定する場合は、必要に応じて departure_time または arrival_time のいずれかを指定できます。いずれの時刻も指定されていない場合、デフォルト値は departure_time（now）になります（つまり、出発時刻が現在時刻にデフォルト設定されます）。また、必要に応じて transit_mode や transit_routing_preference も含めることができます。

注:徒歩と自転車のルートには、明確な歩行者専用道路や自転車専用道が含まれないことがあるため、これらのルートでは結果に warnings が返され、ユーザーに警告を表示する必要があります。

ウェイポイント

Google Maps Directions API を使用してルートを計算する場合、車、徒歩、自転車のルートにウェイポイントを指定することもできます（ウェイポイントは交通機関のルートに対しては利用できません）。ウェイポイントを使用すると、追加した地点を通るルートを計算でき、その場合返されるルートには指定した各ウェイポイントである立ち寄り地が含まれます。

ウェイポイントは waypoints パラメータ内で指定され、1 つ以上の住所または地点をパイプ（|）文字で区切って構成します。

たとえば、次の URL は、マサチューセッツ州ボストンとマサチューセッツ州コンコード間のルートでチャールズタウン、レキシントンの順に立ち寄るルート リクエストを開始します。

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

リクエストのウェイポイントごとに、ルート レスポンスは 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&key=YOUR_API_KEY

接頭辞 via: は、ユーザーがマップ上でウェイポイントをドラッグしてルートを作成する場合に最も効果的です。そうすることで、ユーザーはリアルタイムで最終ルートを確認でき、Google Maps Directions API がアクセス可能な地点に確実にウェイポイントを配置するのに役立ちます。

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

ルートサービスはデフォルトで、指定したウェイポイントを、指定した順番で通るルートを計算します。オプションで、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&key=YOUR_API_KEY

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

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

制限

ルートは特定の制限に従って計算できます。制限は avoid パラメータと避けたい制限対象を示す引数を使用して指定します。サポートされる制限は次のとおりです。

• avoid=tolls
• avoid=highways
• avoid=ferries

有料道路、幹線道路、フェリーという制限対象を avoid パラメータに渡して、これらの制限対象の組み合わせを避けるルートをリクエストできます。例: avoid=tolls|highways|ferries。

注: 制限を追加しても、制限対象を含むルートは除外されません。単に、希望のルートが優先されるだけです。

単位系

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

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

• metric はメートル法を使用するよう指定します。テキスト表記の距離はキロメートルやメートルで返されます。
• imperial はヤードポンド法を使用するよう指定します。テキスト表記の距離はマイルやフィートで返されます。

注: この単位系設定は、distance フィールド内に表示される text にのみ影響します。また、distance フィールドの values は、常にメートル単位で表されます。

地域のバイアス

region パラメータを使用して、ルートサービスが特定の地域の結果を優先して返すよう設定することもできます。このパラメータには、ccTLD（国コード トップ レベル ドメイン）で引数を渡して地域のバイアスを指定します。ccTLD コードのほとんどは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、その ISO 3166-1 コードは「gb」（厳密には「United Kingdom of Great Britain and Northern Ireland」のエンティティ）です。

Google マップのメイン アプリケーションで車のルートを開始するドメインを利用できます。

たとえば、「トレド」から「マドリッド」までのルート リクエストでは、「トレド」がスペインの都市として解釈されるよう region が es に設定されている場合に結果が返されます。

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&key=YOUR_API_KEY

{
  "status": "OK",
  "routes": [ {
    "summary": "AP-41",
    "legs": [ {
        ...
    } ],
    "copyrights": "Map data ©2010 Europa Technologies, Tele Atlas",
    "warnings": [ ],
    "waypoint_order": [ ]
  } ]
}

「トレド」から「マドリッド」までのルートを region パラメータを指定せずに送信した場合は、結果は返されません。これは「トレド」がオハイオ州の都市であると解釈されるためです。

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY

{
  "status": "ZERO_RESULTS",
  "routes": [ ]
}

ルート レスポンス

ルート レスポンスは、リクエストの URL パスの output フラグで指定された形式で返されます。

レスポンス例

次の HTTP リクエストの例は、イリノイ州シカゴからカリフォルニア州ロサンゼルスまでの間に、ミズーリ州ジョプリンとオクラホマ州オクラホマシティの 2 つのウェイポイントを通るルートを計算します。

https://maps.googleapis.com/maps/api/directions/json?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&key=YOUR_API_KEY

上記の例は JSON 出力をリクエストします。XML 出力をリクエストすることも可能です。次のタブをクリックすると、JSON と XML のレスポンスの例が表示されます。

ルート結果が詳細になりすぎる可能性があるため、レスポンス内で繰り返されている要素を省略してわかりやすくしています。

{
  "status": "OK",
  "geocoded_waypoints" : [
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ7cv00DwsDogRAMDACa2m4K8",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ69Pk6jdlyIcRDqM1KDY3Fpg",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJgdL4flSKrYcRnTpP0XQSojM",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJE9on3F3HwoAR9AhGJW_fL-I",
        "types" : [ "locality", "political" ]
     }
  ],
  "routes": [ {
    "summary": "I-40 W",
    "legs": [ {
      "steps": [ {
        "travel_mode": "DRIVING",
        "start_location": {
          "lat": 41.8507300,
          "lng": -87.6512600
        },
        "end_location": {
          "lat": 41.8525800,
          "lng": -87.6514100
        },
        "polyline": {
          "points": "a~l~Fjk~uOwHJy@P"
        },
        "duration": {
          "value": 19,
          "text": "1 min"
        },
        "html_instructions": "Head \u003cb\u003enorth\u003c/b\u003e on \u003cb\u003eS Morgan St\u003c/b\u003e toward \u003cb\u003eW Cermak Rd\u003c/b\u003e",
        "distance": {
          "value": 207,
          "text": "0.1 mi"
        }
      },
      ...
      ... additional steps of this leg
    ...
    ... additional legs of this route
      "duration": {
        "value": 74384,
        "text": "20 hours 40 mins"
      },
      "distance": {
        "value": 2137146,
        "text": "1,328 mi"
      },
      "start_location": {
        "lat": 35.4675602,
        "lng": -97.5164276
      },
      "end_location": {
        "lat": 34.0522342,
        "lng": -118.2436849
      },
      "start_address": "Oklahoma City, OK, USA",
      "end_address": "Los Angeles, CA, USA"
    } ],
    "copyrights": "Map data ©2010 Google, Sanborn",
    "overview_polyline": {
      "points": "a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\\~mbDzeVh_Wr|Efc\\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC"
    },
    "warnings": [ ],
    "waypoint_order": [ 0, 1 ],
    "bounds": {
      "southwest": {
        "lat": 34.0523600,
        "lng": -118.2435600
      },
      "northeast": {
        "lat": 41.8781100,
        "lng": -87.6297900
      }
    }
  } ]
}

<DirectionsResponse>
 <status>OK</status>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ7cv00DwsDogRAMDACa2m4K8</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ69Pk6jdlyIcRDqM1KDY3Fpg</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgdL4flSKrYcRnTpP0XQSojM</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJE9on3F3HwoAR9AhGJW_fL-I</place_id>
 </geocoded_waypoint>
 <route>
  <summary>I-40 W</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8507300</lat>
     <lng>-87.6512600</lng>
    </start_location>
    <end_location>
     <lat>41.8525800</lat>
     <lng>-87.6514100</lng>
    </end_location>
    <polyline>
     <points>a~l~Fjk~uOwHJy@P</points>
    </polyline>
    <duration>
     <value>19</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Head <b>north</b> on <b>S Morgan St</b> toward <b>W Cermak Rd</b></html_instructions>
    <distance>
     <value>207</value>
     <text>0.1 mi</text>
    </distance>
   </step>
   ...
   ... additional steps of this leg
  ...
  ... additional legs of this route
   <duration>
    <value>74384</value>
    <text>20 hours 40 mins</text>
   </duration>
   <distance>
    <value>2137146</value>
    <text>1,328 mi</text>
   </distance>
   <start_location>
    <lat>35.4675602</lat>
    <lng>-97.5164276</lng>
   </start_location>
   <end_location>
    <lat>34.0522342</lat>
    <lng>-118.2436849</lng>
   </end_location>
   <start_address>Oklahoma City, OK, USA</start_address>
   <end_address>Los Angeles, CA, USA</end_address>
  <copyrights>Map data ©2010 Google, Sanborn</copyrights>
  <overview_polyline>
   <points>a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\~mbDzeVh_Wr|Efc\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC</points>
  </overview_polyline>
  <waypoint_index>0</waypoint_index>
  <waypoint_index>1</waypoint_index>
  <bounds>
   <southwest>
    <lat>34.0523600</lat>
    <lng>-118.2435600</lng>
   </southwest>
   <northeast>
    <lat>41.8781100</lat>
    <lng>-87.6297900</lng>
   </northeast>
  </bounds>
 </route>
</DirectionsResponse>

このドキュメントではこれ以降 JSON 構文を使用します。多くの場合、このドキュメントでコンセプトやフィールド名を説明する際に出力形式は関係ありません。ただし、次の違いには注意してください。

• XML の結果はルート要素 <DirectionsResponse> でラップされます。
• JSON は複数の配列（steps）によって複数の要素を含むエントリを示しますが、XML は複数の単一要素（<step>）でこれらを示します。
• JSON では空の要素は空の配列で示しますが、XML ではそのような要素を使用しないことで示します。たとえば、結果が生成されないレスポンスの場合、JSON では空の routes 配列を返しますが、XML では <route> 要素を返しません。

ルート レスポンスの要素

ルート レスポンスには次のルート要素が含まれます。

• status にはリクエストについてのメタデータが含まれます。下記のステータス コードをご覧ください。
• geocoded_waypoints には、出発地、目的地、ウェイポイントのジオコーディングに関する詳細情報を含む配列が含まれます。下記のジオコーディングされたウェイポイントをご覧ください。
• routes には、出発地から目的地までのルートの配列が含まれます。下記のルートをご覧ください。ルートはネストされた区間とステップで構成されます。

ステータス コード

ルート レスポンス オブジェクトの status フィールドには、リクエストのステータスが含まれます。ルートサービスが失敗した原因を追跡できるようにデバッグ情報が含まれることもあります。status フィールドには次の値が含まれます。

• OK は、有効な result がレスポンスに含まれていることを示します。
• NOT_FOUND は、リクエストで指定した出発地、目的地、ウェイポイントのうち、少なくとも 1 つの場所がジオコーディングできなかったことを示します。
• ZERO_RESULTS は、出発地と目的地の間にルートが見つからなかったことを示します。
• MAX_WAYPOINTS_EXCEEDED は、リクエストに指定された waypoints が多すぎることを示します。waypoints の最大許容数は 23 に出発地と目的地を加えた数です（リクエストに API キーが含まれていない場合は、waypoints の最大許容数は 8 です。Google Maps API for Work のユーザーは、最大 23 のウェイポイントを指定したリクエストを送信できます）。
• INVALID_REQUEST は、指定したリクエストが無効であることを示します。このステータスの一般的な原因は無効なパラメータや無効なパラメータ値が含まれているためです。
• OVER_QUERY_LIMIT は、サービスが、許可された期間内にアプリケーションから受信したリクエストが多すぎることを示します。
• REQUEST_DENIED は、サービスがアプリケーションによるルートサービスの使用を拒否したことを示します。
• UNKNOWN_ERROR は、サーバーのエラーでルート リクエストが処理できなかったことを示します。再度リクエストすると、成功する可能性があります。

エラー メッセージ

ステータス コードが OK 以外の場合、ルート レスポンス オブジェクト内に error_message フィールドが付加されている場合があります。このフィールドには、返されたステータス コードの原因に関する詳細情報が含まれています。

注:このフィールドは必ずしも存在するわけではなく、その内容も随時変更される可能性があります。

ジオコーディングされたウェイポイント

すべてのウェイポイントのジオコーディングに関する詳細と、出発地と目的地は、（JSON）geocoded_waypoints 配列で検索できます。これらを使用すると、サービスが予期せぬルートを返したり、ルートが返されなかった理由を推測できます。

geocoded_waypoints 配列の要素はゼロベースの位置を基準に出発地、指定された順序のウェイポイント、目的地に対応しています。各要素には、対応するウェイポイントのジオコーディング処理に関する次の詳細が含まれます。

• geocoder_status は、ジオコーディングの処理結果を示すステータス コードです。このフィールドには次の値が含まれます。
  • OK: エラーが発生しなかったことを示します。住所の解析が成功し、少なくとも 1 件のジオコードが返されました。
  • ZERO_RESULTS: ジオコーディングは成功したものの結果が返されなかったことを示します。これは、ジオコーダに存在しない address が渡された場合に発生することがあります。

• partial_match は、元のリクエストに完全一致する住所は見つからなかったものの、部分一致する住所は見つかったことを示します。元のリクエストで住所の表記が間違っていたり、不完全である可能性があります。

  多くの場合、リクエストで渡された地域に番地が存在しないために部分一致が発生します。また、同じ地域内に複数の場所があるリクエストを行った場合も部分一致が返されます。たとえば、「21 Henr St, Bristol, UK」には、「Henry Street」と「Henrietta Street」の両方への部分一致が返されます。リクエストに表記が間違った住所コンポーネントが含まれている場合、ジオコーディング サービスが別の住所を提示することもある点に注意してください。この場合も、部分一致として結果が返されます。

• place_id は、Google の他の API で使用できる一意の識別子です。たとえば、Google Place Autocomplete レスポンスの place_id を使用してローカル ビジネスのルートを計算できます。詳しくは、プレイス ID の概要をご覧ください。
• types は、ルート計算に使用されるジオコーディングの結果の住所タイプを示します。次のタイプが返されます。
  • street_address は正確な番地を示します。
  • route は（US 101 などの）名前のあるルートを示します。
  • intersection は主要な交差点（主に 2 本の主要道路の交差点）を示します。
  • political は行政上のエンティティを示します。通常、このタイプは民政のポリゴンを示します。
  • country は国家を示し、一般的にはジオコーダから返される最上位のタイプです。
  • administrative_area_level_1 は国レベルの下の 1 次的な行政区画を示します。米国の場合、州がこの行政区画レベルに相当しますが、すべての国でこの行政区画レベルが存在するわけではありません。
  • administrative_area_level_2 は国レベルの下の 2 次的な行政区画を示します。米国の場合、郡がこの行政区画レベルに相当しますが、すべての国でこの行政区画レベルが存在するわけではありません。
  • administrative_area_level_3 は国レベルの下の 3 次的な行政区画を示します。このタイプは小規模な行政区域を示します。すべての国でこの行政区画レベルが存在するわけではありません。
  • administrative_area_level_4 は国レベルの下の 4 次的な行政区画を示します。このタイプは小規模な行政区域を示します。すべての国でこの行政区画レベルが存在するわけではありません。
  • administrative_area_level_5 は国レベルの下の 5 次的な行政区画を示します。このタイプは小規模な行政区域を示します。すべての国でこの行政区画レベルが存在するわけではありません。
  • colloquial_area はエンティティに対して一般に使用されている俗称を示します。
  • locality は市や地方自治体を示します。
  • ward は、日本の住所で複数の地区コンポーネントを簡単に区別するために使用する日本独自のタイプです。
  • sublocality は locality の下の 1 次的な下位地区を示します。一部の地域では、sublocality_level_1 から sublocality_level_5 までの追加タイプの 1 つを受け取ることがあります。各下位地区レベルは行政区画で、数が大きいほど区域は小さくなります。
  • neighborhood は名前のある地域を示します。
  • premise は名前のある場所を示します。通常は建物や共通の名前を持つ建物群です。
  • subpremise は名前のある場所の下にあるレベルの 1 次的な存在を示します。通常は共通の名前を持つ建物群の中にある 1 つの建物です。
  • postal_code は、国内で郵便物の宛先に使用される郵便番号を示します。
  • natural_feature は著名な地物を示します。
  • airport は空港を示します。
  • park は名前のある公園を示します。
  • point_of_interest は、名称のあるスポットを示します。通常、「名称のあるスポット」とは、その他のカテゴリには簡単に分類できない著名な地名で、たとえば「エンパイア ステート・ビル」や「自由の女神」などです。

  タイプリストが空の場合は、特定の住所コンポーネントに対して既知のタイプが存在しないことを意味します。たとえば、フランスのリュディが、これに相当します。

サービスが結果を返さない場合は、テキスト表記の緯度と経度の値として指定されたウェイポイントに対してこれらの詳細は表示されません。これは、このようなウェイポイントはルートが見つかった後にその代表の住所を取得するという逆のジオコーディングだからです。空の JSON オブジェクトで geocoded_waypoints 配列の対応する位置を埋めます。

ルート

Google Maps Directions API が結果を返す場合、結果は（JSON）routes 配列内に格納されます。サービスから返す結果がない（出発地や目的地が存在しないなど）場合でも、空の routes 配列が返されます（XML レスポンスは、ゼロ個以上の <route> 要素で構成されます）。

routes 配列の各要素には、指定された出発地と目的地から得られた結果が 1 件含まれます。このルートにはウェイポイントが指定されたかどうかに応じて、1 つ以上の legs が含まれます。また、ルートには経路情報の他に、著作権や警告に関する情報など、ユーザーへの表示が必要な内容も含まれています。

routes フィールド内の各ルートには次のフィールドが含まれます。

• summary には、ルートに関するテキスト表記の短い説明が含まれます。代替ルートに名前を付けたり、明確にするのに適しています。
• legs[] には、指定されたルート内の 2 地点のルート区間に関する情報を含む配列が含まれます。指定したウェイポイントや目的地ごとに、1 つの区間が存在します（ウェイポイントがないルートには、legs 配列内の区間が 1 つだけ含まれています）。各区間は一連の steps で構成されます（下記のルート区間をご覧ください）。
• waypoint_order には、計算されたルート上にあるウェイポイントの順番を示す配列が含まれます。リクエストが waypoints パラメータ内で optimize:true を渡した場合は、このウェイポイントは並べ替えられます。
• overview_polyline には、ルートを表すエンコードしたポリラインを持つ points オブジェクトが 1 つ含まれます。このポリラインは、結果のルートを近似した（平滑化した）経路です。
• bounds には、overview_polyline のビューポート境界ボックスが含まれます。
• copyrights には、このルートで表示が必要な著作権に関するテキストが含まれます。この情報は自身で処理して表示する必要があります。
• warnings[] には、これらのルートで表示が必要な警告文の配列が含まれています。これらの警告は自身で処理して表示する必要があります。
• fare:運賃がかかる場合は、そのルートの合計運賃（切符の合計金額）が含まれます。このプロパティは、交通機関のリクエストにおいて、すべての区間で運賃情報が取得できる場合にのみ返されます。次の情報が含まれます。
  • currency:ISO 4217 通貨コードは、運賃を表示する通貨を指定します。
  • value:上記で指定した通貨での合計運賃です。
  • text:リクエストした言語でフォーマットされた合計運賃です。

次に、ルート内の運賃情報の例を示します。

"routes" : [
   {
      "bounds" : {
         "northeast" : {
            "lat" : 37.8079996,
            "lng" : -122.4074334
         },
         "southwest" : {
            "lat" : 37.7881005,
            "lng" : -122.4203553
         }
      },
      "copyrights" : "Map data ©2015 Google",
      "fare" : {
         "currency" : "USD",
         "value" : 6
         "text" : "$6.00"
      },
      ...
   }]

区間

legs 配列の各要素は、計算されたルートの出発地から目的地までの行程の 1 つの区間を指定します。ウェイポイントがないルートは、1 つの「区間」で構成されますが、1 つ以上のウェイポイントがあるルートは、行程の特定の区間に対応する 1 つ以上の区間で構成されます。

legs フィールド内の各区間には次のフィールドが含まれます。

• steps[] には、行程の区間の各ステップに関する情報を示すステップの配列が含まれます（下記のルートのステップをご覧ください）。

• distance はこの区間がカバーする総距離を示し、フィールドには次の要素が含まれます。

  • value は距離をメートル単位で表します。
  • text は人が読める形式で距離を表現したもので、出発地で使用される単位（またはリクエストの units パラメータ内でオーバーライドされた単位）で表示されます（たとえば、出発地が米国内であればマイルやフィートが使用されます）。テキストで表示されている単位系に関係なく、distance.value フィールドの値は常にメートル表記になることに注意してください。

  距離が不明な場合は、これらのフィールドはないことがあります。

• duration はこの区間にかかる合計時間を示し、フィールドには次の要素が含まれます。

  • value は秒単位で表した所要時間です。
  • text は、人が読める表記を用いた所要時間です。

  時間が不明な場合は、これらのフィールドはないことがあります。

• duration_in_traffic は、この区間にかかる合計時間を示します。この値は、現在と過去の交通状況に基づいて交通機関を使用した場合にかかる時間を予測したものです。返される値が optimistic、pessimistic、best-guess 予測のリクエストに使用できるオプションについては、traffic_model リクエスト パラメータをご覧ください。交通状況を考慮した時間が返されるのは、次のすべてが true の場合のみです。

  • リクエストに departure_time パラメータが含まれている。
  • リクエストに有効な API キーが含まれているか、有効な Google Maps API for Work クライアント ID と署名が含まれている。
  • リクエストしたルートで交通状況を取得できる。
  • リクエストに立ち寄るウェイポイントが含まれていない。
  • リクエストが車のルートである（mode パラメータが driving に設定されている）。

  duration_in_traffic に含まれるフィールドは次のとおりです。

  • value は秒単位で表した所要時間です。
  • text は、人が読める表記を用いた所要時間です。
• arrival_time には、この区間における到着予定時刻が含まれます。このプロパティは、交通機関のルートに対してのみ返されます。結果は次の 3 つのプロパティを含む Time オブジェクトとして返されます。
  • value は、JavaScript の Date オブジェクトとして指定された時間です。
  • text は、文字列として指定された時刻です。この時刻は、交通機関の停止地点におけるタイムゾーンで表示されます。
  • time_zone には、この駅のタイムゾーンが含まれます。この値は IANA タイムゾーン データベースで定義されたタイムゾーンの名称で、「America/New_York」のような値です。
• departure_time には、Time オブジェクトとして指定された、この区間における出発予定時刻が含まれます。departure_time は、交通機関のルートに対してのみ使用できます。
• start_location には、この区間の始点の緯度と経度の座標が含まれます。Directions API は、出発地と目的地において最も近い交通機関オプション（通常は道路）を使用して地点間のルートを計算するため、たとえば、道路が出発地から離れている場合は、start_location が、指定されたこの区間の出発地とは異なる可能性があります。
• end_location には、指定されたこの区間の目的地の緯度と経度の座標が含まれます。Google Maps Directions API は、出発地と目的地において最も近い交通機関オプション（通常は道路）を使用して地点間のルートを計算するため、たとえば、道路が目的地から離れている場合は、end_location が、指定されたこの区間の目的地とは異なる可能性があります。
• start_address には、この区間の start_location を逆にジオコーディングする人が読める形式の住所（通常は住所）が含まれます。
• end_address には、この区間の end_location を逆にジオコーディングする人が読める形式の住所（通常は住所）が含まれます。

ステップ

steps 配列の各要素は計算されるルートの 1 つのステップを定義します。ステップはルートの最小単位で、行程内の特定の 1 つの指示を説明する 1 つのステップが含まれています。たとえば、「外堀通りを左折」などの指示です。なお、ステップには進路の説明だけでなく、現在のステップと次のステップとの関連性を表す距離や所要時間などの情報も含まれます。たとえば、「東名高速道路に入る」と表示されるステップには、現在のステップから次のステップまでは 3.2 キロ / 7 分であることを示す、距離「3.7 キロ」や所要時間「7 分」といった情報が含まれます。

Google Maps Directions API を使用して交通機関のルートを検索する際は、transit_details 配列の形式のルート詳細が追加でステップ配列に含まれます。ルートに複数の移動モードが含まれる場合は、内部 steps 配列にある徒歩または車のステップに詳細なルートが含まれます。たとえば、徒歩ステップには「明治通りと井の頭通りを進む」のように、出発地から目的地までのルートが含まれます。このステップは、内部 steps 配列の該当するルートに詳細な徒歩ルートを含めます。内容は「東に進む」、「右折して北大路通に入る」、「左折して大宮通に入る」などです。

steps フィールド内の各ステップには次のフィールドが含まれます。

• html_instructions には、このステップのフォーマットされた指示が含まれ、HTML テキスト文字列で示されます。
• distance には、このステップで次のステップまでにカバーされる距離が含まれます（上記のルート区間のこのフィールドの説明をご覧ください）。距離が不明な場合、このフィールドは定義されないことがあります。
• duration には、次のステップまでにこのステップの実行に必要な標準時間が含まれます（上記のルート区間の説明をご覧ください）。所要時間が不明な場合、このフィールドは定義されないことがあります。
• start_location には、このステップの始点の位置が lat フィールドと lng フィールドの 1 つのセットとして含まれます。
• end_location には、このステップの終点の位置が lat フィールドと lng フィールドの 1 つのセットとして含まれます。
• polyline には、ステップを表すエンコードしたポリラインを持つ points オブジェクトが 1 つ含まれます。このポリラインは、ステップを近似した（平滑化した）経路です。
• steps には、交通機関のルートにおける徒歩または車のステップの詳細なルートが含まれます。サブステップを使用できるのは、travel_mode が「交通機関」に設定されている場合のみです。内部 steps 配列は、steps と同じタイプの配列です。
• transit_details には、交通機関向けの情報が含まれます。このフィールドが返されるのは、travel_mode が「交通機関」に設定されている場合のみです。下記の交通機関の詳細をご覧ください。

交通機関の詳細

交通機関のルートは、他の移動モードには関係のない追加情報を返します。これらの追加プロパティは、transit_details オブジェクトによって公開され、steps[] 配列の要素のフィールドとして返されます。TransitDetails オブジェクトから、交通機関の停止地点、交通機関の路線、交通機関の運行事業者に関する追加情報にアクセスできます。

transit_details オブジェクトには次のフィールドが含まれます。

• arrival_stop と departure_stop には、ルートのこの部分の停止地点 / 駅や停留所に関する情報が含まれます。停止地点の詳細には次の内容が含まれます。
  • name は交通機関の駅や停留所の名称です（「ユニオン スクエア」など）。
  • location は lat と lng フィールドとして示される交通機関の駅や停留所の場所です。
• arrival_time と departure_time には、行程のこの区間の到着時刻または出発時刻が含まれます。次の 3 つのプロパティで指定されます。
  • text は、文字列として指定された時刻です。この時刻は、交通機関の停止地点におけるタイムゾーンで表示されます。
  • value は、Unix 時間または 1970 年 1 月 1 日深夜 0 時からの経過秒数（UTC）として指定される時刻です。
  • time_zone には、この駅のタイムゾーンが含まれます。この値は IANA タイムゾーン データベースで定義されたタイムゾーンの名称で、「America/New_York」のような値です。
• headsign は、出発する駅や停留所、車両に表示される路線の行先表示を指定します。多くの場合、この行先は終点に相当します。
• headway は、現時点で同じ停止地点から出発するまでの予測秒数を指定します。たとえば、headway 値が 600 の場合は、バスに乗れないと 10 分待つことになります。
• num_stops は、このステップに含まれる停止地点の数です。これには到着地点は含まれますが、出発地点は含まれません。たとえば、A 駅を出発して、B 駅と C 駅を通り、D 駅に到着するルートの場合、num_stops は 3 を返します。
• line には、このステップで使用される路線情報が含まれます。これには次のプロパティが含まれます。
  • name には、この交通機関の路線の正式名称が含まれます（「7 Avenue Express」など）。
  • short_name には、この交通機関の路線の略称が含まれます。これは通常、「M7」や「355」などの路線番号です。
  • color には、この交通機関の路線の表記に通常使用される色が含まれます。この色は、#FF0033 のような 16 進の文字列で指定されます。
  • agencies には、路線の運行事業者に関する情報を提供する TransitAgency オブジェクトの配列が含まれます。次のプロパティが含まれます。
    • name には交通機関の名称が含まれます。
    • url には交通機関の運行事業者の URL が含まれます。
    • phone には交通機関の運行事業者の電話番号が含まれます。

    このルート結果を提供する交通機関の運行事業者の名称や URL を表示する必要があります。

  • url には、交通機関の運行事業者によって提供されるこの路線の URL が含まれます。
  • icon には、この路線と関連付けられたアイコンの URL が含まれます。
  • text_color には、この路線の表記に通常使用されるテキストの色が含まれます。この色は、16 進の文字列で指定されます。
  • vehicle には、この路線で使用されている乗り物の種別が含まれます。これには次のプロパティが含まれます。
    • name には、この路線の乗り物の名称が含まれます（「地下鉄」など）。
    • type には、この路線で運行されている乗り物の種別が含まれます。サポートされている値の完全なリストについては、乗り物の種別の説明をご覧ください。
    • icon には、この乗り物の種別と関連付けられたアイコンの URL が含まれます。

乗り物の種別

vehicle.type プロパティは次のいずれかの値を返します。

sensor パラメータ

Google Maps API では、以前はユーザーの位置情報の検出にアプリケーションでセンサーを使用するかどうかを示すため sensor パラメータを含める必要がありましたが、このパラメータは必要なくなりました。