以上で完了です。

開発を始めるには、デベロッパー ドキュメント をご覧下さい。

Google Maps Distance Matrix API をアクティベートする

まず初めに Google Developers Console で次の作業を行います。

  1. プロジェクトを作成または選択する
  2. Google Maps Distance Matrix API をアクティベートする
  3. 適切なキーを作成する
続ける

デベロッパー ガイド

Google Maps Distance Matrix API は、出発地と目的地のマトリックスに対して移動距離と移動時間を提供するサービスです。

このサービスは、クライアント側の Google Maps JavaScript API の一部として利用可能です。または、Java Client、Python Client、Go Client および Node.js Client for Google Maps Services を使用してサーバー側で使用されます。注: サービスの使い方によらず、適用される 1 日あたりの使用制限は同じです。1 日あたりの要素は、クライアント側とサーバー側の合計クエリ回数で計算されます。

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

はじめに

Google Maps Distance Matrix API は、出発地と目的地の間の推奨ルートに基づいて情報を返します。この情報は Google Maps API で計算され、各ペアの durationdistance の値を含む行で構成されます。

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

Distance Matrix API を使用した開発を始める前に、認証要件(API キーが必要です)と API の使用制限について確認してください。

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

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

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

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

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

注: URL は、すべてのウェブサービスで対応できるように適切にエンコーディングされた有効な文字である必要があります。また、8192 文字以内という制限があります。URL を構成する際は、この制限に注意してください。別のブラウザ、プロキシ、サーバーでも同様に別の URL 文字制限がある可能性があります。

HTTPS と HTTP のどちらを使用するか

セキュリティは重要です。特に機密性の高いユーザーデータ(ユーザーの位置情報など)を含むアプリケーションでは、できる限りリクエストに HTTPS を使用することをお勧めします。HTTPS 暗号化を使用すると、アプリケーションをより強固に保護できるようになり、スヌーピングや改ざんに対する耐性が高まります。

HTTPS を使用できない場合、HTTP を介して Google Maps Distance Matrix API にアクセスする際は、次の URL を使用してください。

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

リクエスト パラメータ

パラメータには、必須パラメータと省略可能なパラメータがあります。URL の標準と同様に、パラメータはすべてアンパサンド(&)文字を使用して区切ります。

必須パラメータ

  • origins: 移動距離と移動時間を計算する際の出発地です。住所、緯度と経度の座標、プレイス ID のいずれかの形式で、パイプ文字(|)で区切って 1 つ以上の地点を指定できます。
    • 住所を渡す場合、サービスは文字列をジオコーディングして緯度と経度の座標に変換し、距離を計算します。この座標は、Google Maps Geocoding API で返された座標とは異なる場合があります(建物の中心ではなく建物の入り口など)。
      origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON
    • 緯度と経度の座標を渡すと、座標をそのまま使用して距離を計算します。緯度と経度の値の間にはスペースを入れないようにしてください。
      origins=41.43206,-81.38992|-33.86748,151.20699
    • プレイス ID を指定する場合は、place_id: 接頭辞を付ける必要があります。プレイス ID は、リクエストに API キーまたは Google Maps APIs Premium Plan クライアント ID が含まれている場合にのみ指定できます。Google Maps Geocoding API と Google Places API によってプレイス ID を取得できます(プレイス オートコンプリートなど)。プレイス オートコンプリートのプレイス ID の使用例については、プレイス オートコンプリートとルートをご覧ください。プレイス ID の詳細については、プレイス ID の概要をご覧ください。
      origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
    • または、エンコードしたポリラインのアルゴリズムを使用して、一連のエンコードした座標を指定することもできます。エンコードしたポリラインを使用すると URL が大幅に短くなるため、これは特に、多数のウェイポイントが存在する場合に便利です。
      • エンコードしたポリラインには、接頭辞の enc: と、後ろに付けるコロン(:)が必要です。例: waypoints=enc:gfo}EtohhU:
      • パイプ文字(|)で区切って、エンコードしたポリラインを複数指定することもできます。例: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
  • destinations: 移動距離と移動時間を計算する際に目的地として使う 1 つ以上の場所です。destinations パラメータのオプションは、上記の origins パラメータと同じです。
  • key: アプリケーションの API キーです。このキーを使ってアプリケーションを識別し、割り当て量を管理します。詳細については、キーの取得をご覧ください。

    注: Google Maps APIs Premium Plan ユーザーは、Distance Matrix リクエストで、API キー、または有効なクライアント ID とデジタル署名を使用できます。詳細については、Premium Plan ユーザーの認証パラメータをご確認ください。

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

https://maps.googleapis.com/maps/api/distancematrix/json?units=imperial&origins=40.6655101,-73.89188969999998&destinations=40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626%7C40.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?units=imperial&origins=40.6655101,-73.89188969999998&destinations=enc:_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV:&key=YOUR_API_KEY

省略可能なパラメータ

  • mode(デフォルトは driving): 距離を計算する際に使用する移動モードを指定します。有効な値と他のリクエストの詳細は、このドキュメントの交通手段セクションに記載しています。
  • language: 結果を返すときの言語を示します。
    • サポートされる言語のリストをご覧ください。サポートされる言語は頻繁に更新されるため、このリストがすべてのサポート言語を網羅しているとは限りません。
    • language が指定されていない場合、API は、Accept-Language ヘッダーで指定された優先言語か、リクエストの送信元ドメインの言語の使用を試みます。
    • API では、できるだけユーザーとローカルの両言語で判読可能な番地を返します。そのために、API はローカル言語で番地を返し、優先言語も考慮して、必要に応じてユーザーが理解できるスクリプトに書き直します。それ以外の住所はすべて、優先言語で返されます。住所コンポーネントはすべて、最初のコンポーネントで選択した言語と同じ言語で返されます。
    • 優先言語で名前を表示できない場合、API は最も近い言語を使用します。
    • 優先言語は、API が返す結果や、結果が返される順序に多少影響します。「~通り」を表す略語や特定の言語だけで有効な同義語など、ジオコーダによる略語の解釈は言語によって異なります。たとえば、utcatér は、ハンガリー語では「通り」を表す同義語です。
  • 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 APIs Premium Plan クライアント ID と署名が含まれている場合にのみ使用できます。departure_time は現在時刻か、それ以降の時刻に設定する必要があります。過去の時刻は指定できません。

      注: mode=driving の場合、departure_time を指定する距離マトリックス リクエストには、リクエスト 1 回あたりの要素数が最大で 100 個までという制限があります。要素数は、origins の数と destinations の数を乗算した値になります。

  • traffic_model(デフォルトは best_guess)- 所要時間を計算する際に使用する仮定を指定します。この設定に応じて、レスポンスで duration_in_traffic フィールドに返される値が変わります。この値は、過去の平均データに基づく予測所要時間となります。traffic_model パラメータは、交通手段が driving で、リクエストに departure_time が含まれていて、リクエストに API キーまたは Google Maps APIs Premium Plan クライアント ID が含まれる場合にのみ指定できます。このパラメータに使用できる値は次のとおりです。
    • best_guess(デフォルト)は、過去と現在の交通状況のデータを基に見積もった最適な移動時間を、duration_in_traffic で返すよう指定します。departure_time が現在時刻に近いほど、現在の交通状況は重要になります。
    • pessimistic は、普段の実際の移動時間よりも大きい値を duration_in_traffic で返すよう指定します。ただし、交通状況が極端に悪い日は、この値よりも長い時間を要する可能性があります。
    • optimistic は、普段の実際の移動時間よりも小さい値を duration_in_traffic で返すよう指定します。ただし、交通状況が非常に良い日は、この値よりも短時間で到着する可能性があります。
  • transit_mode: 1 つ以上の希望する交通機関モードを指定します。このパラメータは、modetransit のリクエストにのみ指定できます。パラメータは次の引数をサポートします。
    • bus は、バスを使ったルートを計算するよう指定します。
    • subway は、地下鉄を使ったルートを計算するよう指定します。
    • train は、列車を使ったルートを計算するよう指定します。
    • tram は、市街電車やライトレールを使ったルートを計算するよう指定します。
    • rail は、列車や市街電車、ライトレール、地下鉄を使ったルートを計算するよう指定します。これは、transit_mode=train|tram|subway と同等です。
  • transit_routing_preference - 交通機関のリクエストの優先度を指定します。このパラメータを使うと、API がデフォルトで選択した最適なルートを受け取る代わりに、返されるオプションにバイアスをかけることができます。このパラメータは、modetransit のリクエストにのみ指定できます。パラメータは次の引数をサポートします。
    • less_walking は、歩行距離に制限を付けてルートを計算するよう指定します。
    • fewer_transfers は、乗り換え回数に制限を付けてルートを計算するよう指定します。

交通手段

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

  • driving(デフォルト)は、道路網を使用した距離計算を示します。
  • walking は、歩行者専用道路と歩道を通る徒歩の距離計算をリクエストします(可能な場合)。
  • bicycling は、自転車専用道路と優先道路を自転車で走る場合の距離計算をリクエストします(可能な場合)。
  • transit は、公共交通機関を使用した距離計算をリクエストします(可能な場合)。この値は、リクエストに API キーまたは Google Maps APIs Premium Plan クライアント ID が含まれている場合にのみ指定できます。このモードを transit に設定する場合は、必要に応じて departure_time または arrival_time のいずれかを指定できます。いずれの時刻も指定されていない場合、デフォルト値は departure_time(now)になります(つまり、出発時刻が現在時刻にデフォルト設定されます)。また、必要に応じて transit_modetransit_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 の配列が含まれ、これにはそれぞれ statusdurationdistance の要素が含まれます。

ステータス コード

レスポンス オブジェクト内の 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 APIs Premium Plan クライアント 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
Google Maps Distance Matrix API
ご不明な点がありましたら、Google のサポートページをご覧ください。