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 つ以上の場所。宛先パラメータのオプションは、出発地パラメータと同じです。

• origins

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

  • プレイス 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 を指定する Distance Matrix リクエストは、リクエストあたり最大 100 個の要素に制限されます。出発地の数に目的地の数を掛けた値が要素の数になります。

• language

  結果を返す言語。

  • サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
  • 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'

この例では、プラスコードを使用して目的地座標を指定しています。

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'

交通情報

次のすべてがあてはまる場合に交通情報が使用されます（Distance Matrix のレスポンスで 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: 修飾子は、次の制限でのみ使用できます。

• 移動手段の 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: 修飾子は、次の制限でのみ使用できます。

• 移動手段の 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 は、アプリケーションによる距離行列サービスの使用がサービスによって拒否されたことを示します。
• UNKNOWN_ERROR は、サーバーエラーが原因で距離行列リクエストを処理できなかったことを示します。再度リクエストすると、成功する可能性があります。

DistanceMatrixRow

DistanceMatrixElement

運賃

ルートの合計運賃。

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

DistanceMatrixElementStatus

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

TextValueObject

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