Distance Matrix API（従来版）のリクエストとレスポンス

はじめに

Distance Matrix API（従来版）リクエストの形式は次のとおりです。

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

ここで、outputFormat には次のいずれかの値を指定できます。

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

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

必須パラメータ

• リンク先

  移動距離と移動時間を計算する際の終了地点として使用する 1 つ以上の場所。destinations パラメータのオプションは、origins パラメータと同じです。

• origins

  移動距離と所要時間を計算するための出発地。プレイス ID、住所、緯度/経度座標の形式で、1 つ以上の場所をパイプ文字（|）で区切って指定できます。

  • プレイス ID: プレイス ID を指定する場合は、先頭に place_id: を付ける必要があります。
  • 住所: 住所を渡すと、サービスは文字列をジオコーディングし、緯度/経度の座標に変換して距離を計算します。この座標は、Geocoding API から返される座標（建物の中心など）とは異なる場合があります（建物の入り口など）。
    注: 住所や緯度/経度座標ではなく、プレイス ID を使用することをおすすめします。座標を使用すると、ポイントは常にその座標に最も近い道路にスナップされます。その道路は、目的地へのアクセス ポイントではない場合や、目的地に迅速かつ安全に到達できる道路ではない場合もあります。住所を使用すると、建物の入口ではなく、建物の中心までの距離が提供されます。
  • 座標: 緯度と経度の座標を渡すと、最も近い道路にスナップされます。プレイス ID を渡すことをおすすめします。座標を渡す場合は、緯度と経度の値の間にスペースがないことを確認してください。
  • Plus Code は、グローバル コードまたは複合コードの形式にする必要があります。plus code を次のような形式にします（プラス記号は %2B に URL エスケープされ、スペースは %20 に URL エスケープされます）。
    • グローバル コードは、4 文字の市外局番と 6 文字以上のローカルコードです（849VCWC8+R9 は 849VCWC8%2BR9 にエンコードされます）。
    • 複合コードは、明示的な場所を含む 6 文字以上のローカルコードです（CWC8+R9 Mountain View, CA, USA は CWC8%2BR9%20Mountain%20View%20CA%20USA にエンコードされます）。
  • エンコード化ポリライン: エンコード化ポリライン アルゴリズムを使用して、エンコードされた座標セットを指定することもできます。エンコードされたポリラインを使用すると URL が大幅に短くなるため、出発地が多数ある場合に特に便利です。
    • エンコードされたポリラインの先頭には enc: を付け、その後にコロン : を付ける必要があります。例: origins=enc:gfo}EtohhU:
    • 複数のエンコードされたポリラインをパイプ文字 | で区切って指定することもできます。次に例を示します。

      origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
      

オプション パラメータ

• arrival_time

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

• 避ける

  特定の制限に従って距離が計算される場合があります。 制限は、avoid パラメータと、そのパラメータの引数（回避する制限を示す）を使用して指定します。次の制限がサポートされています。

  • 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 要素に制限されます。要素の数は、出発地の数に目的地の数を掛けた値です。

• 言語

  結果を返す言語。

  • サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
  • 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 は、乗り換え回数に制限を付けてルートを計算するよう指定します。

• ユニット

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

  注: この単位系設定は、距離フィールド内に表示されるテキストにのみ影響します。距離フィールドには、常にメートルで表現された値も含まれます。

リクエストの例

この例では、緯度/経度座標を使用して目的地の座標を指定しています。

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

この例では、Plus Codes を使用して目的地の座標を指定しています。

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

次の例は、エンコードされたポリラインを使用した同じリクエストを示しています。

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

交通情報

次のすべてがあてはまる場合に交通情報が使用されます（距離行列のレスポンスで duration_in_traffic フィールドを取得するには、これらの条件を満たす必要があります）。

• travel mode パラメータが driving、または指定されていない（デフォルトの移動手段は driving）。
• リクエストに有効な departure_time パラメータが含まれている。departure_time には、現在時刻または将来の時刻を設定できます。過去の時刻は指定できません。

必要に応じて、リクエストに traffic_model パラメータを含めて、交通状況を考慮した所要時間を計算する際に使用する前提条件を指定できます。

次の URL は、マサチューセッツ州ボストンまたはマサチューセッツ州チャールズタウンと、マサチューセッツ州レキシントンおよびマサチューセッツ州コンコードの間の運転距離に関する Distance Matrix リクエストを開始します。リクエストには出発時刻が含まれており、距離行列のレスポンスで duration_in_traffic フィールドを返すためのすべての要件を満たしています。

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins
   
  
 

位置情報の修飾子

場所の修飾子を使用して、ドライバーが特定の場所にどのように接近するかを指定できます。side_of_road 修飾子を使用して、道路のどちら側を使用するかを指定したり、進行方向を指定して正しい進行方向を示したりできます。

計算されたルートが道路の特定の側を通るように指定する

場所を指定するときに、side_of_road: 接頭辞を使用して、ウェイポイントが偏っている道路のどちら側を通るルートを計算するようにリクエストできます。たとえば、次のリクエストでは、ウェイポイントが偏っている道路の側に車両が到着するように、長いルートの距離が返されます。

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

エンコードされたポリラインで side_of_road: を使用すると、修飾子はポリラインに沿ったすべての場所に適用されます。たとえば、このリクエストの 2 つの宛先はどちらもパラメータを使用します。

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

side_of_road: 修飾子は、次の制限付きでのみ使用できます。

• travel mode パラメータが driving、または指定されていない（デフォルトの移動手段は driving）。

計算されたルートに特定の方向を指定する

場所を指定するときに、計算されたルートが特定の方向でその場所を通過するようにリクエストできます。この見出しは、接頭辞 heading=X: で指定されます。ここで、X は 0 以上 360 未満の整数値です。方位 0 は北、90 は東を示し、時計回りに続きます。たとえば、次のリクエストでは、計算されたルートは出発地から東に向かい、U ターンします。

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

heading=X: 修飾子は、次の制限付きでのみ使用できます。

• travel mode パラメータが driving、bicycling、または指定されていない（デフォルトの移動手段は driving）。
• side_of_road 修飾子が同じロケーションに指定されていない。
• 位置は緯度と経度の値で指定します。heading は、住所、プレイス ID、エンコードされたポリラインでは使用できません。

距離行列のリクエストとレスポンス

次の HTTP リクエストの例では、カナダのバンクーバーと米国のシアトルから、米国のサンフランシスコとカナダのビクトリアまでの距離と所要時間をリクエストしています。

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

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

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

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km
   
  
 

DistanceMatrixResponse

DistanceMatrixStatus

サービスから返されるステータス コード。

• OK は、レスポンスに有効な結果が含まれていることを示します。
• INVALID_REQUEST は、指定されたリクエストが無効であることを示します。
• MAX_ELEMENTS_EXCEEDED は、出発地と目的地を掛け合わせた数がクエリあたりの上限を超えていることを示します。
• MAX_DIMENSIONS_EXCEEDED は、出発地または目的地の数がクエリあたりの上限を超えていることを示します。
• OVER_DAILY_LIMIT は次のいずれかを示します。
  • API キーがないか、無効です。
  • アカウントで課金が有効になっていない。
  • ご自身で設定した使用量の上限を超えている
  • 設定したお支払い方法が無効になっている（クレジット カードの期限切れなど）
• OVER_QUERY_LIMIT は、許可された期間内にアプリケーションから受信したリクエストが多すぎることを示します。
• REQUEST_DENIED は、アプリケーションによる Distance Matrix サービスの使用が拒否されたことを示します。
• UNKNOWN_ERROR は、サーバーエラーが原因で距離行列リクエストを処理できなかったことを示します。再度リクエストすると、成功する可能性があります。

DistanceMatrixRow

DistanceMatrixElement

運賃

ルートの合計運賃。

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}

DistanceMatrixElementStatus

• OK は、レスポンスに有効な結果が含まれていることを示します。
• NOT_FOUND は、このペアの出発地または目的地をジオコーディングできなかったことを示します。
• ZERO_RESULTS は、出発地と目的地の間にルートが見つからなかったことを示します。
• MAX_ROUTE_LENGTH_EXCEEDED は、リクエストされたルートが長すぎるため処理できないことを示します。

TextValueObject

数値とその書式設定されたテキスト表現を含むオブジェクト。