距離行列サービス

注: サーバー側のライブラリ

概要

Google の距離行列サービスを使うと、指定した移動手段で複数の出発地と目的地の間を移動する場合について、その移動距離と所要時間を計算できます。

このサービスは詳細なルート情報は返しません。ポリラインやテキスト形式の経路説明などのルート情報を取得するには、出発地と目的地を 1 つずつ経路サービスに渡してください。

ご利用にあたって

Maps JavaScript API で距離行列サービスを使用するにはまず、Maps JavaScript API を設定した同じプロジェクトで Distance Matrix API が有効になっていることを Google Cloud Console で確認します。

有効な API のリストを表示するには:

Google Cloud コンソールに移動します。
[プロジェクトを選択] ボタンをクリックし、Maps JavaScript API を設定した同じプロジェクトを選択して、[開く] をクリックします。
[ダッシュボード] の API のリストから、Distance Matrix API を探します。
リストに API が表示されていれば、準備は完了です。API がリストに表示されていない場合は、次の手順で有効にします。
1. ページの上部で、[API を有効にする] を選択して [ライブラリ] タブを表示します。または、左側のサイドメニューで [ライブラリ] を選択します。
2. Distance Matrix API を検索し、結果のリストから選択します。
3. [有効にする] を選択します。このプロセスを完了すると、[ダッシュボード] の API のリストに Distance Matrix API が表示されます。

料金とポリシー

料金

2018 年 7 月 16 日に、マップ、ルート、プレイスに対して従量課金制の新しい料金プランが適用されました。JavaScript 距離行列サービスの新しい料金と使用量上限については、Distance Matrix API の使用量と請求額をご覧ください。

注: 距離行列サービスに送信される各クエリは、使用可能な要素の数によって制限されます。要素数は、出発地の数 × 目的地の数で定義されます。

ポリシー

距離行列サービスは、Distance Matrix API を対象とするポリシーに従って使用する必要があります。

距離行列リクエスト

距離行列サービスにアクセスすると、Google Maps API は外部サーバーに対して呼び出しを行うので、処理が非同期になります。したがって結果を処理するためには、コールバックメソッドを渡してリクエストの完了時に実行する必要があります。

コード内で距離行列サービスにアクセスするには、google.maps.DistanceMatrixService オブジェクトを使います。DistanceMatrixService.getDistanceMatrix() メソッドは距離行列サービスへのリクエストを開始します。このメソッドには出発地、目的地、移動手段を含む DistanceMatrixRequest オブジェクトリテラルと、レスポンスの受信時に実行するコールバックメソッドを渡します。

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

サンプルを表示

DistanceMatrixRequest には次のフィールドがあります。

origins（必須）: 1 つ以上の住所文字列、google.maps.LatLng オブジェクト、または Place オブジェクトを含む配列。距離や時間の計算に使用されます。
destinations（必須）: 1 つ以上の住所文字列、google.maps.LatLng オブジェクト、または Place オブジェクトを含む配列。距離や時間の計算に使用されます。
travelMode（省略可）: ルートを計算する際に使用する移動モード。詳しくは、移動手段のセクションをご覧ください。
transitOptions（省略可）: travelMode が TRANSIT であるリクエストだけに適用されるオプション。使用可能な値については、交通機関のオプションのセクションをご覧ください。
drivingOptions（省略可）: travelMode が DRIVING であるリクエストだけに適用される値を指定します。使用可能な値については、運転オプションのセクションをご覧ください。
unitSystem（省略可）: 距離の表示に使用する単位系を示します。次の値を使用できます。
- google.maps.UnitSystem.METRIC（デフォルト）
- google.maps.UnitSystem.IMPERIAL
avoidHighways（省略可）: true の場合、できる限り高速道路を避けて、出発地から目的地までのルートを計算します。
avoidTolls（省略可）: true の場合、できる限り有料道路を避けて、出発地から目的地までのルートを計算します。

注: durationInTraffic フィールドは非推奨になりました。このフィールドは、所要時間を計算する際に、現時点の交通状況を考慮するか否かを指定する方法として、Google Maps Platform プレミアムプランの利用者向けに推奨されていました。今後は、代わりに drivingOptions フィールドを使用してください。

移動手段

所要時間と距離を計算する際は、使用する移動手段を指定できます。現在サポートされている移動手段は、次のとおりです。

BICYCLING は、自転車専用道路と優先道路を使う自転車ルートをリクエストします（現時点では米国と、カナダの一部の都市でのみ利用可能です）。
DRIVING（デフォルト）は、道路網を使用した標準の運転ルートを示します。
TRANSIT は、公共交通機関を使用する経路をリクエストします。このオプションを指定できるのは、リクエストに API キーが含まれている場合のみです。このタイプのリクエストに使用できるオプションについては、交通機関のオプションのセクションをご覧ください。
WALKING は、歩行者専用道路と歩道を通る徒歩経路をリクエストします（利用可能な場合）。

交通機関のオプション

交通機関サービスは現在、「試験運用」中です。試験運用中は、API の乱用を防ぐためにレート制限がかかります。この API を公平にご利用いただくために、最終的には 1 回の地図の読み込みで発行できるクエリ総数に上限を設定します。

距離行列で利用できるオプションは、移動手段ごとに異なります。なお、交通機関のリクエストでは、オプションの avoidHighways と avoidTolls は無視されます。交通機関固有のルートオプションは、TransitOptions オブジェクトリテラルで指定できます。

交通機関のルートでは時間の制約があり、現在時刻より後のルートだけが返されます。

TransitOptions オブジェクトリテラルには次のフィールドがあります。

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

以下はフィールドの説明です。

arrivalTime（省略可）: 希望する到着時刻を Date オブジェクトとして指定します。到着時刻が指定されている場合、出発時刻は無視されます。
departureTime（省略可）: 希望する出発時刻を Date オブジェクトとして指定します。arrivalTime が指定されている場合、departureTime は無視されます。departureTime と arrivalTime の両方に値が指定されていない場合は、デフォルト値として現在時刻が使用されます。
modes（省略可）は、1 つ以上の TransitMode オブジェクトリテラルを含む配列です。このフィールドを使用できるのは、リクエストに API キーが含まれている場合のみです。各 TransitMode は、希望する移動手段を指定するフィールドで、使用できる値は以下のとおりです。
- BUS は、バスを使ったルートを計算するよう指定します。
- RAIL は、電車、市街電車、路面電車、地下鉄を使ったルートを計算するよう指定します。
- SUBWAY は、地下鉄を使ったルートを計算するよう指定します。
- TRAIN は、電車を使ったルートを計算するよう指定します。
- TRAM は、市街電車と路面電車を使ったルートを計算するよう指定します。
routingPreference（省略可）には、公共交通機関を使ったルートを検索する際の条件を指定します。このオプションを使うと、API がデフォルトで選択した最適ルートを受け取る代わりに、返されるオプションにバイアスをかけることができます。このフィールドを指定できるのは、リクエストに API キーが含まれている場合のみです。使用できる値は以下のとおりです。
- FEWER_TRANSFERS は、乗り換え回数に制限を付けてルートを計算するよう指定します。
- LESS_WALKING は、歩行距離に制限を付けてルートを計算するよう指定します。

運転オプション

drivingOptions オブジェクトを使用して出発時刻を指定し、予想される交通状況に基づいて目的地への最適ルートを計算します。また、推定所要時間を長め、短め、または過去と現在の交通状況に基づく最適な推定値のいずれにするかも指定できます。

drivingOptions オブジェクトには次のフィールドがあります。

{
  departureTime: Date,
  trafficModel: TrafficModel
}

以下はフィールドの説明です。

departureTime（drivingOptions オブジェクトリテラルを有効にするために必須）は、希望する出発時刻を Date オブジェクトとして指定します。この値は現在時刻以降に設定する必要があり、過去の時刻は指定できません（API はすべての日時を UTC 時間に変換して、タイムゾーンにかかわらず一貫した処理を行います）。リクエストに departureTime が含まれていると、API はその時点での交通状況を考慮した最適ルートを返します。また、レスポンスには推定所要時間（duration_in_traffic）が含まれます。出発時刻を指定しない場合（リクエストに drivingOptions が含まれていない場合）は、交通状況を考慮しない状態で概ね適切と考えられるルートが返されます。
注: 出発時刻が指定されていない場合、ルートと所要時間は、道路網と平均的な交通状況（時間的な要素を考慮に入れない）に基づいて選択されます。道路網における状況の変化、平均的な交通状況の最新情報、サービスの分散性などにより、リクエストの結果が時間の経過とともに変化する可能性があります。また、結果は、ほぼ同等のルートでも、時刻やリクエストの頻度によって異なる場合があります。
trafficModel（省略可）は、所要時間を計算する上での仮定条件を指定します。この設定に応じて、レスポンスで duration_in_traffic フィールドに返される値が変わります。この値は、過去の平均データに基づく予測所要時間となります。デフォルトでは best_guess に設定されます。使用できる値は以下のとおりです。
- bestguess（デフォルト）は、過去と現在の交通状況のデータを基に見積もった最適な移動時間を、duration_in_traffic で返すよう指定します。departureTime が現在時刻に近いほど、現在の交通状況が重視されます。
- pessimistic は、普段の実際の移動時間よりも大きい値を duration_in_traffic で返すよう指定します。ただし、交通状況が極端に悪い日は、この値よりも長い時間を要する可能性があります。
- optimistic は、普段の実際の移動時間よりも小さい値を duration_in_traffic で返すよう指定します。ただし、交通状況が非常に良い日は、この値よりも短時間で到着する可能性があります。

以下は、出発時刻と所要時間モデルを含む運転ルートの DistanceMatrixRequest の例です。

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

距離行列のレスポンス

距離行列サービスへの呼び出しに成功すると、DistanceMatrixResponse オブジェクトと DistanceMatrixStatus オブジェクトが返されます。これらのオブジェクトは、リクエストで指定したコールバック関数に渡されます。

DistanceMatrixResponse オブジェクトは、ルートの計算に成功した出発地と目的地の各ペアについて、移動距離と所要時間の情報を含んでいます。

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

距離行列の結果

レスポンスでサポートされているフィールドは以下のとおりです。

originAddresses は、距離行列リクエストの origins フィールドで渡した場所を含む配列です。住所はジオコーダによってフォーマットされたものが返されます。
destinationAddresses は、距離行列リクエストの destinations フィールドで渡した場所を含む配列です。住所はジオコーダによってフォーマットされたものが返されます。
rows は DistanceMatrixResponseRow オブジェクトの配列で、各行が 1 つの出発地に対応しています。
elements は rows の子要素で、その行の出発地と各目的地のペアに対応しています。これには、出発地と目的地のペアごとのステータス、所要時間、距離、運賃の情報が含まれます。
各 element には次のフィールドがあります。
- status: 可能性のあるステータスコードのリストについては、ステータスコードをご覧ください。
- duration: このルートの移動にかかる時間です。秒単位（value フィールド）と text で表現されます。テキストの値は、リクエストで指定された unitSystem に従って（設定されてない場合はメート法で）フォーマットされます。
- duration_in_traffic: 現在の交通状況を考慮した場合に、このルートの移動にかかる時間です。秒単位（value フィールド）と text で表現されます。テキストの値は、リクエストで指定された unitSystem に従って（設定されてない場合はメート法で）フォーマットされます。duration_in_traffic は、Google Maps Platform プレミアムプランをご利用のお客様にのみ対応しているフィールドです。この値が返されるのは、交通状況が取得でき、mode が driving に設定されおり、さらに departureTime がリクエストの distanceMatrixOptions フィールドの一部として含まれている場合のみです。
- distance: このルートの総距離です。メートル単位（value）の text として表されます。テキストの値は、リクエストで指定された unitSystem に従って（設定されてない場合はメート法で）フォーマットされます。
- fare: このルートの合計運賃（切符の合計金額）が含まれます。このプロパティは交通機関のリクエストにのみ対応しており、運賃情報が取得できる交通機関の運行事業者の場合のみ返されます。次の情報が含まれます。
  - currency: ISO 4217 通貨コードは、運賃を表示する通貨を指定します。
  - value: 上記で指定した通貨での合計運賃です。

ステータスコード

距離行列レスポンスには、要素ごとのステータスに加え、レスポンス全体のステータスコードも含まれています。

レスポンスのステータスコード

DistanceMatrixResponse に適用される以下のステータスコードは DistanceMatrixStatus オブジェクトで渡されます。

OK: リクエストが有効であることを示します。なお、出発地から目的地までのルートがまったく見つからなかった場合も、このステータスが返されます。要素レベルのステータス情報については、要素のステータスコードを参照してください。
INVALID_REQUEST: 指定したリクエストが無効であることを示します。これは通常、必須フィールドが指定されていない場合に返されます。上記のサポートされるフィールドの一覧をご覧ください。
MAX_ELEMENTS_EXCEEDED: 出発地と目的地を掛け合わせた数がクエリあたりの上限を超えていることを示します。
MAX_DIMENSIONS_EXCEEDED: リクエストにおいて、25 か所を超える出発地、あるいは 25 か所を超える目的地が指定されていることを示します。
OVER_QUERY_LIMIT: 許可された期間内にアプリケーションが送信したリクエスト数が多すぎることを示します。この場合は、しばらく経ってから再度リクエストすると成功します。
REQUEST_DENIED: 距離行列サービスの使用がウェブページによって拒否されたことを示します。
UNKNOWN_ERROR: サーバーエラーが原因で距離行列リクエストが処理できなかったことを示します。再度リクエストすると、成功する可能性があります。

要素のステータスコード

以下のステータスコードは、特定の DistanceMatrixElement オブジェクトに適用されます。

NOT_FOUND: ペアになった出発地と目的地の少なくとも一方をジオコーディングできなかったことを示します。
OK: 有効な結果がレスポンスに含まれています。
ZERO_RESULTS: 出発地と目的地の間にルートが見つからなかったことを示します。

結果の解析

DistanceMatrixResponse オブジェクトには、リクエストで渡した出発地ごとに 1 つの row が含まれています。各行には、出発地と指定された目的地の各ペアの element フィールドが含まれています。

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}