Google Maps Distance Matrix API

このサービスは、Google Maps JavaScript API の一部として、または Java および Python クライアントライブラリでも使用することができます。

はじめに

Google Maps Distance Matrix API は、出発地と目的地のマトリックスに対して移動距離と移動時間を提供するサービスです。情報は、出発地と目的地の間の推奨ルートに基づいて返されます。Google Maps API で計算され、各ペアの duration と distance の値を含む行で構成されます。

このサービスは詳細なルート情報は返しません。ルート情報は、希望する 1 つの出発地と 1 つの目的地を Google Maps Directions API に渡すことで取得できます。

キーの取得使用制限

対象読者

このドキュメントは、Google Maps API を使用して複数の地点間の移動距離と移動時間を計算するデベロッパーを対象としています。また、API の使用の概要や使用可能なパラメータに関するリファレンスマテリアルを示しています。

距離マトリックスリクエスト

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

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

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

output の値は次のいずれかです。

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

Google Maps Distance Matrix API の URL は約 2,000 文字（URL のエンコード後）に制限されます。一部の Google Maps Distance Matrix API サービスの URL には多数の地点が含まれている可能性があるため、URL の作成時にはこの制限に注意してください。別のブラウザ、プロキシ、サーバーでも同様に別の URL 文字制限がある可能性があります。

リクエストパラメータ

パラメータには、必須パラメータと省略可能なパラメータがあります。URL の標準に従い、すべてのパラメータはアンパサンド（&）文字で区切ります。

必須パラメータ

origins: 距離と時間の計算の始点となる 1 つ以上の住所やテキスト表記の緯度と経度の値。パイプ（|）文字で区切ります。住所を文字列として渡す場合、サービスは文字列をジオコーディングして緯度と経度の座標に変換し、距離を計算します。座標を渡す場合、緯度と経度の値の間にはスペースを入れないようにしてください。
```
origins=Bobcaygeon+ON|41.43206,-81.38992
```
destinations: 距離と時間の計算の終点となる 1 つ以上の住所やテキスト表記の緯度と経度の値。パイプ（|）文字で区切ります。住所を文字列として渡す場合、サービスは文字列をジオコーディングして緯度と経度の座標に変換し、距離を計算します。座標を渡す場合、緯度と経度の値の間にはスペースを入れないようにしてください。
```
destinations=Darling+Harbour+NSW+Australia|24+Sussex+Drive+Ottawa+ON|Capitola+CA
```
key: アプリケーションの API キーです。このキーを使ってアプリケーションを識別し、割り当て量を管理します。詳細については、キーの取得をご覧ください。

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

省略可能なパラメータ

mode（デフォルトは driving）: 距離を計算する際に使用する移動モードを指定します。有効な値と他のリクエストの詳細は、このドキュメントの交通手段セクションに記載しています。
language: 結果を返すときの言語を示します。サポートされるドメイン言語のリストをご覧ください。サポートされる言語は頻繁に更新されるため、このリストがすべてのサポート言語を網羅しているとは限りません。
avoid: ルートに制限を付加します。有効な値は、このドキュメントの制限セクションに記載しています。指定できる制限は 1 つのみです。
units: 距離をテキストとして表示する際に使用する単位系を指定します。詳細については、このドキュメントの単位系セクションをご覧ください。
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 パラメータは、交通手段が driving で、リクエストに 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 つ以上の希望する交通機関モードを指定します。このパラメータは、mode が transit のリクエストにのみ指定できます。パラメータは次の引数をサポートします。
- bus は、バスを使ったルートを計算するよう指定します。
- subway は、地下鉄を使ったルートを計算するよう指定します。
- train は、列車を使ったルートを計算するよう指定します。
- tram は、市街電車やライトレールを使ったルートを計算するよう指定します。
- rail は、列車や市街電車、ライトレール、地下鉄を使ったルートを計算するよう指定します。これは、transit_mode=train|tram|subway と同等です。
transit_routing_preference - 交通機関のリクエストの優先度を指定します。このパラメータを使うと、API がデフォルトで選択した最適なルートを受け取る代わりに、返されるオプションにバイアスをかけることができます。このパラメータは、mode が transit のリクエストにのみ指定できます。パラメータは次の引数をサポートします。
- less_walking は、歩行距離に制限を付けてルートを計算するよう指定します。
- fewer_transfers は、乗り換え回数に制限を付けてルートを計算するよう指定します。

* 注: departure_time パラメータを含むリクエストは要素が 100 に制限されます。

交通手段

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

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

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

制限

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

avoid=tolls
avoid=highways
avoid=ferries
avoid=indoor

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

単位系

距離マトリックスの結果では、distance フィールド内に text が表示され、計算したルートの距離が示されます。使用する単位系は次のとおり指定できます。

units=metric（デフォルト）は、距離をキロメートルやメートルの単位で返します。
units=imperial は、距離をマイルやフィートの単位で返します。

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

距離マトリックスのレスポンス

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

次に HTTP リクエストの 2 つの例を示します。カナダのブリティッシュコロンビア州バンクーバーからとアメリカのワシントン州シアトルから、アメリカのカリフォルニア州サンフランシスコとカナダのブリティッシュコロンビア州ビクトリアまでの距離と時間をリクエストします。

このリクエストは、JSON output フラグを使用した例です。

https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Victoria+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

このリクエストは、XML output フラグを使用した例です。

https://maps.googleapis.com/maps/api/distancematrix/xml?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Vancouver+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

このリクエストは、4 つの要素（2 つの出発地 × 2 つの目的地）を返します。

バンクーバーからサンフランシスコ	バンクーバーからビクトリア
シアトルからサンフランシスコ	シアトルからビクトリア

結果は行で返されます。各行には、それぞれの目的地とペアになった 1 つの出発地が含まれます。

お試しください。ここをクリックすると、ブラウザにサンプルリクエストを送信します（ファイルを開くアプリケーションを選択するよう求めるメッセージが表示された場合、ブラウザか任意のテキストエディタかを選択できます）。

次のタブをクリックすると、JSON と XML のレスポンスの例が表示されます。

JSON

{
  "status": "OK",
  "origin_addresses": [ "Vancouver, BC, Canada", "Seattle, État de Washington, États-Unis" ],
  "destination_addresses": [ "San Francisco, Californie, États-Unis", "Victoria, BC, Canada" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 340110,
        "text": "3 jours 22 heures"
      },
      "distance": {
        "value": 1734542,
        "text": "1 735 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 24487,
        "text": "6 heures 48 minutes"
      },
      "distance": {
        "value": 129324,
        "text": "129 km"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 288834,
        "text": "3 jours 8 heures"
      },
      "distance": {
        "value": 1489604,
        "text": "1 490 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 14388,
        "text": "4 heures 0 minutes"
      },
      "distance": {
        "value": 135822,
        "text": "136 km"
      }
    } ]
  } ]
}

これらの結果から値を抽出する場合は、通常、結果を解析する必要があります。JSON の解析は比較的簡単です。お勧めの設計パターンについては、JSON の処理をご覧ください。

XML

<?xml version="1.0" encoding="UTF-8"?>
<DistanceMatrixResponse>
 <status>OK</status>
 <origin_address>Vancouver, BC, Canada</origin_address>
 <origin_address>Seattle, État de Washington, États-Unis</origin_address>
 <destination_address>San Francisco, Californie, États-Unis</destination_address>
 <destination_address>Victoria, BC, Canada</destination_address>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>340110</value>
    <text>3 jours 22 heures</text>
   </duration>
   <distance>
    <value>1734542</value>
    <text>1 735 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>24487</value>
    <text>6 heures 48 minutes</text>
   </duration>
   <distance>
    <value>129324</value>
    <text>129 km</text>
   </distance>
  </element>
 </row>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>288834</value>
    <text>3 jours 8 heures</text>
   </duration>
   <distance>
    <value>1489604</value>
    <text>1 490 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>14388</value>
    <text>4 heures 0 minutes</text>
   </duration>
   <distance>
    <value>135822</value>
    <text>136 km</text>
   </distance>
  </element>
 </row>
</DistanceMatrixResponse>

別の理由からサービスで xml を使用する必要がない限り、Google では、優先出力フラグとして json を使用することをお勧めしています。XML ツリーの処理では、適切なノードと要素を参照するように、ある程度の配慮が求められます。出力処理のお勧めの設計パターンについては、XPath による XML の処理をご覧ください。

このドキュメントではこれ以降 JSON 構文を使用します。

距離マトリックスレスポンスの要素

距離マトリックスレスポンスには次のルート要素が含まれます。

status にはリクエストについてのメタデータが含まれます。下記のステータスコードをご覧ください。
origin_addresses には、元のリクエストの API で返された住所の配列が含まれます。これらはジオコーダでフォーマットされ、リクエストで渡された language パラメータに基づいてローカライズされます。
destination_addresses には、元のリクエストの API で返された住所の配列が含まれます。origin_addresses と同様に、これらは適切にローカライズされます。
rows には elements の配列が含まれ、これにはそれぞれ status、duration、distance の要素が含まれます。

ステータスコード

レスポンスオブジェクト内の status フィールドには、リクエストのステータスが含まれます。また、役に立つデバッグ情報が含まれることもあります。Distance Matrix API では、通常、リクエストに関する情報を含むトップレベルのステータスフィールドと、特定の出発地と目的地のペアに関する情報を含む各要素フィールドのステータスフィールドを返します。

トップレベルのステータスコード

OK は、有効な result がレスポンスに含まれていることを示します。
INVALID_REQUEST は、指定したリクエストが無効であることを示します。
MAX_ELEMENTS_EXCEEDED は、出発地と目的地の結果がクエリあたりの制限を超えることを示します。
OVER_QUERY_LIMIT は、サービスが、許可された期間内にアプリケーションから受信したリクエストが多すぎることを示します。
REQUEST_DENIED は、サービスがアプリケーションによる距離マトリックスサービスの使用を拒否したことを示します。
UNKNOWN_ERROR は、サーバーエラーで距離マトリックスリクエストが処理できなかったことを示します。再度リクエストすると、成功する可能性があります。

要素レベルのステータスコード

OK は、有効な result がレスポンスに含まれていることを示します。
NOT_FOUND は、このペアの出発地や目的地がジオコーディングできなかったことを示します。
ZERO_RESULTS は、出発地と目的地の間にルートが見つからなかったことを示します。

エラーメッセージ

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

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

行

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

行は、リクエストの origin パラメータの値に応じて順序付けされます。各行は origin に対応し、その行内の各 element は origin と destination の値のペアに対応します。

各 row の配列には 1 つ以上の element エントリが含まれ、これには出発地と目的地の 1 つのペアに関する情報が含まれます。

要素

出発地と目的地の各ペアに関する情報は element エントリで返されます。element に含まれるフィールドは次のとおりです。

status:有効なステータスコードのリストについては、ステータスコードをご覧ください。
duration:このルートの所要時間です。秒単位（value フィールド）の text として表されます。テキスト表記はクエリの language パラメータに応じてローカライズされます。
duration_in_traffic:このルートの所要時間です。現在と過去の交通状況に基づきます。返される値が optimistic、pessimistic、best-guess 予測のリクエストに使用できるオプションについては、traffic_model リクエストパラメータをご覧ください。時間は秒単位（value フィールド）で、text として表されます。テキスト表記はクエリの language パラメータに応じてローカライズされます。交通状況を考慮した時間が返されるのは、次のすべてが true の場合のみです。
- リクエストに departure_time パラメータが含まれている。
- リクエストに有効な API キーが含まれているか、有効な Google Maps API for Work クライアント ID と署名が含まれている。
- リクエストしたルートで交通状況を取得できる。
- mode パラメータが driving に設定されている。
distance:このルートの総距離です。メートル単位（value）の text として表されます。テキスト値は元のリクエストまたは出発地の地域の unit パラメータで指定された単位系を使用します。
fare:運賃がかかる場合は、そのルートの合計運賃（切符の合計金額）が含まれます。このプロパティは交通機関のリクエストにのみ対応しており、運賃情報が取得できる交通機関の運行事業者の場合のみ返されます。次の情報が含まれます。
- currency:ISO 4217 通貨コードは、運賃を表示する通貨を指定します。
- value:上記で指定した通貨での合計運賃です。
- text:リクエストした言語でフォーマットされた合計運賃です。

次に、運賃情報を含む element の例を示します。

{
  "status": "OK",
  "duration": {
    "value": 340110,
    "text": "3 jours 22 heures"
  },
  "distance": {
    "value": 1734542,
    "text": "1 735 km"
  }
  "fare" : {
    "currency" : "USD",
    "value" : 6,
    "text" : "$6.00"
  },
}

`sensor` パラメータ

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

Google Maps Distance Matrix API

はじめに

対象読者

距離マトリックス リクエスト

リクエスト パラメータ

交通手段

制限

単位系

距離マトリックスのレスポンス

距離マトリックス レスポンスの要素

ステータス コード

トップレベルのステータス コード

要素レベルのステータス コード

エラー メッセージ

行

要素

sensor パラメータ

フィードバックを送信...