概要
Google の距離マトリックス サービスを使うと、指定した交通手段で複数の出発地と目的地の間を移動する場合について、その移動距離と所要時間を計算できます。
このサービスは詳細なルート情報は返しません。ポリラインやテキスト形式の経路説明などのルート情報を取得するには、出発地と目的地を 1 つずつルート サービスに渡します。
使用制限と要件
割り当て
距離マトリック スサービスには、以下の使用制限が適用されます。
- 1 回のリクエストで指定できる出発地は 25 か所、到着地は 25 か所までです。
- 1 回のリクエストで使用できる要素は 100 個（出発地 x 目的地）までです。
リクエストにもレート制限があり、特定の期間内にリクエストされた要素数が多すぎると、OVER_QUERY_LIMIT レスポンス コードが返されます。
Google マップの表示
距離マトリックス サービスは、Google マップに情報を表示する場合にのみ使用できます。例えば、指定した走行時間内に移動できる出発地と目的地のペアを特定する場合は、それらの情報をリクエストしてマップ上に表示しなければなりません。Google マップを表示しないアプリケーションで、このサービスを使用することは禁止されています。
距離マトリックス リクエスト
距離マトリックス サービスにアクセスすると、Google Maps API は外部サーバーに対して呼び出しを行うので、処理が非同期になります。そのため、リクエストの完了時に実行される callback メソッドを渡して、結果を処理する必要があります。
コード内で距離マトリックス サービスにアクセスするには、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: google.maps.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オブジェクトの両方、またはいずれか一方を含む配列です。destinations（必須） – 距離や時間の計算に使う 1 つ以上の住所文字列とgoogle.maps.LatLngオブジェクトの両方、またはいずれか一方を含む配列です。travelMode（任意） – ルートの計算に使う交通手段です。詳細については交通手段のセクションをご覧ください。transitOptions（任意） –travelModeがgoogle.maps.TravelMode.TRANSITの時だけリクエストに適用されるオプションです。使用可能な値については、交通機関のオプションのセクションをご覧ください。drivingOptions（任意） –travelModeがgoogle.maps.TravelMode.DRIVINGの時だけリクエストに適用される値を指定します。使用可能な値については、運転オプションのセクションをご覧ください。unitSystem（任意） – 距離の表示に使う単位系で、次の値が利用できます。google.maps.UnitSystem.METRIC（デフォルト）google.maps.UnitSystem.IMPERIAL
avoidHighways（任意） –trueの場合、できる限り高速道路を避けて、出発地から目的地までのルートを計算します。avoidTolls（任意） –trueの場合、できる限り有料道路を避けて、出発地から目的地までのルートを計算します。
交通手段
所要時間や距離を計算する際は、使用する交通機関を指定できます。現在サポートされている交通手段は、次のとおりです。
google.maps.TravelMode.BICYCLINGは、自転車専用道路と優先道路を使う自転車ルートをリクエストします（現時点では米国と、カナダの一部の都市でのみ利用可能です）。google.maps.TravelMode.DRIVING（デフォルト）は、道路網を使う標準の運転ルートをリクエストします。google.maps.TravelMode.TRANSITは、公共交通機関を使うルートをリクエストします。このオプションを指定できるのは、リクエストに API キーが含まれている場合のみです。このタイプのリクエストに使用できるオプションについては、交通機関のオプションのセクションをご覧ください。google.maps.TravelMode.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は希望する交通機関を指定するフィールドで、使用できる値は以下のとおりです。google.maps.TransitMode.BUSは、バスを使うルートを計算するよう指定します。google.maps.TransitMode.RAILは、列車や市街電車、ライトレール、地下鉄を使うルートを計算するよう指定します。google.maps.TransitMode.SUBWAYは、地下鉄を使うルートを計算するよう指定します。google.maps.TransitMode.TRAINは、列車を使うルートを計算するよう指定します。google.maps.TransitMode.TRAMは、市街電車やライトレールを使うルートを計算するよう指定します。
routingPreference（任意）は、公共交通機関を使うルートを検索する際の条件を指定します。このオプションを使うと、API がデフォルトで選択した最適なルートの代わりに、オプションにバイアスをかけて検索したルートを取得できます。なお、このフィールドを使用できるのは、リクエストに API キーが含まれている場合のみです。使用できる値は以下のとおりです。google.maps.TransitRoutePreference.FEWER_TRANSFERSは、乗り換え回数が少ないルートを計算するよう指定します。google.maps.TransitRoutePreference.LESS_WALKINGは、歩行距離が短いルートを計算するよう指定します。
運転オプション
運転ルートに固有のルート オプションを指定するには、DrivingOptions オブジェクトを使用します。DistanceMatrixRequest に drivingOptions フィールドを含めたい場合は、API をロードする際に Google Maps API for Work クライアント ID を指定してください。
DrivingOptions オブジェクトに含まれるフィールドは、以下のとおりです。
{
departureTime: Date,
trafficModel: TrafficModel
}
以下はフィールドの説明です。
departureTime（drivingOptionsオブジェクト リテラルの有効化に必要）は、出発希望時刻をDateオブジェクトとして指定します。この値は現在時刻以降に設定する必要があり、過去の時刻は指定できません。（API は全ての日時を UTC 時間に変換して、タイムゾーンによらず一貫した処理を行います。）Google Maps API for Work をご利用の場合は、リクエストにdepartureTimeが含まれていると、API はその時点での交通状況を考慮した最適なルートを返します。また、レスポンスには推定所要時間（duration_in_traffic）が含まれます。出発時刻を指定しない場合（リクエストにdrivingOptionsが含まれていない場合）は、交通状況を考慮しない状態で概ね適切と考えられるルートが返されます。trafficModel（任意）は、所要時間を計算する上での仮定条件を指定します。この設定に応じて、レスポンスでduration_in_trafficフィールドに返される値が変わります。この値は、過去の平均データに基づく予測所要時間となります。デフォルト値はbest_guessで、使用できる値は以下のとおりです。google.maps.TrafficModel.BEST_GUESS（デフォルト）または文字列値best_guessは、過去と現在の交通状況のデータを基に見積もった最適な所要時間を、duration_in_trafficで返すよう指定します。departureTimeが現在時刻に近いほど、現在の交通状況が重視されます。google.maps.TrafficModel.PESSIMISTICまたは文字列値pessimisticは、平均的な所要時間よりも大きな値をduration_in_trafficで返すよう指定します。ただし、交通状況が極端に悪い日は、この値よりも所要時間が長くなる可能性があります。google.maps.TrafficModel.OPTIMISTICまたは文字列値optimisticは、平均的な所要時間よりも小さい値をduration_in_trafficで返すよう指定します。ただし、交通状況が非常に良い日は、この値よりも所要時間が短くなる可能性があります。
以下は、出発時刻と trafficModel を含む運転ルートの DistanceMatrixRequest の例です。
{
origins: [{lat: 55.93, lng: -3.118}, "Greenwich, England"],
destinations: ["Stockholm, Sweden", {lat: 50.087, lng: 14.421}],
travelMode: google.maps.TravelMode.DRIVING,
drivingOptions: {
departureTime: new Date(Date.now() + N), // for the time N milliseconds from now.
trafficModel: "optimistic"
}
}
距離マトリックスのレスポンス
距離マトリックス サービスへの呼び出しに成功すると、DistanceMatrixResponse オブジェクトと DistanceMatrixStatus オブジェクトが返されます。これらのオブジェクトは、リクエストで指定したコールバック関数に渡されます。
DistanceMatrixResponse オブジェクトは、ルートの計算に成功した出発地と目的地の各ペアについて、移動距離と所要時間の情報を保持しています。
{
"origin_addresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
"destination_addresses": [ "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 API for Work にのみ対応しているフィールドです。この値が返されるのは、交通状況が取得でき、modeがdrivingに設定されおり、さらにdepartureTimeがリクエストのdistanceMatrixOptionsフィールドの一部として含まれている場合のみです。distance:このルートの総距離です。メートル単位（value）のtextとして表されます。テキストメッセージ（を送信する）テキストの値は、リクエストで指定されたunitSystemに従って（設定されてない場合はメート法で）フォーマットされます。fare:このルートの合計運賃（切符の合計金額）が含まれます。このプロパティは交通機関のリクエストにのみ対応しており、運賃情報が取得できる交通機関の運行事業者の場合のみ返されます。次の情報が含まれます。currency:ISO 4217 通貨コードは、運賃を表示する通貨を指定します。value:上記で指定した通貨での合計運賃です。
ステータス コード
距離マトリックスのレスポンスには、要素ごとのステータスと、レスポンス全体のステータス コードが含まれています。
レスポンスのステータス コード
DistanceMatrixResponse に適用される以下のステータス コードは DistanceMatrixStatus オブジェクトで渡されます。
OK- リクエストが有効であることを示します。なお、出発地から目的地までのルートがまったく見つからなかった場合も、このステータスが返されます。要素レベルのステータス情報については、要素のステータス コードの説明をご覧ください。INVALID_REQUEST- 指定したリクエストが無効であることを示します。これは通常、必須フィールドが指定されていない場合に返されます。上述のサポートされるタイプのリストの説明をご覧ください。MAX_ELEMENTS_EXCEEDED- 出発地と目的地から得られた結果が、1 回のクエリあたりの制限を超過していることを示します。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 == google.maps.DistanceMatrixStatus.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];
}
}
}
}
ご不明な点がありましたら、Google の