以上で完了です。

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

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

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

  1. プロジェクトを作成または選択する
  2. Google Maps JavaScript API と関連サービスをアクティベートする
  3. 適切なキーを作成する
続ける

距離マトリックス サービス

概要

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

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

はじめに

Google Maps JavaScript API で距離マトリックス サービスを使用するには、まず Google API Console で Google Maps JavaScript API をセットアップしたプロジェクトで、Google Maps Distance Matrix API が有効になっていることを確認します。

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

  1. Google API Console に移動します。
  2. [Select a project] ボタンをクリックし、Google Maps JavaScript API を設定している同じプロジェクトを選択して、[Open] をクリックします。
  3. [Dashboard] の API リストで、Google Maps Distance Matrix API を探します。
  4. リストに API が表示されていれば、準備は完了です。API がリストに表示されていない場合は、次の手順で有効にします。
    1. ページの上部にある [ENABLE API] を選択し、[Library] タブを表示します。または、左側のメニューで [Library] を選択します。
    2. Google Maps Distance Matrix API を検索し、結果のリストからこの API を選択します。
    3. [ENABLE] を選択します。このプロセスを完了すると、[Dashboard] の API リストに Google Maps Distance Matrix API が表示されます。

使用制限とポリシー

割り当て

距離マトリック スサービスには、以下の使用制限が適用されます。

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

標準プランで距離マトリックス サービスを使用する

  • 1 日あたり 2,500 個の要素が無料。これはクライアント側とサーバー側のクエリ回数の合計です。1 日あたりの割り当てを増やすには、 課金を有効化します。追加要素 1,000 個ごとに $0.50 USD が課金され、要素の上限は 1 日あたり 100,000 個です。
  • 1 回のリクエストで指定できる出発地は 25 か所、目的地は 25 か所までです。
  • 1 回のリクエストで最大 100 個の要素を使用できます。
  • 1 秒あたり最大 100 個の要素を使用できます。これはクライアント側とサーバー側のクエリ回数の合計です。

プレミアム プランで距離マトリックス サービスを使用する

  • 24 時間ごとの要素が 100,000 個の 1 日あたりの無料の共有割り当て。追加リクエストは、年間購入した Maps APIs Credits のカウント対象です。。
  • 1 回のリクエストで指定できる出発地は 25 か所、目的地は 25 か所までです。
  • 1 回のリクエストで最大 625 個の要素を使用できます。注: mode=driving の場合、オプションのパラメータ departure_time を使用するリクエストには、リクエスト 1 回あたりの要素数が最大で 100 個までという制限があります。
  • クライアント側では、各プロジェクトで 1 秒あたり 無制限 の要素を使用できます。サーバー側の API は 1 秒あたり 1,000 個の要素に制限されていることに注意してください。

同じプロジェクトを共有しているユーザー数に関係なく、ユーザー セッションごとにレート制限が適用されます。

このセッションごとのレート制限により、バッチ リクエストのクライアント側サービスは使用できません。バッチ リクエストには Google Maps Distance Matrix API ウェブサービスを使用してください。

ポリシー

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

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

距離マトリックス サービスにアクセスすると、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: '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.
}

例を見る(distance-matrix.html)

DistanceMatrixRequest に含まれるフィールドは次のとおりです。

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

交通手段

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

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

交通機関のオプション

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

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

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

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

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

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

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

運転オプション

運転ルートに固有のルート オプションを指定するには、DrivingOptions オブジェクトを使用します。DistanceMatrixRequestdrivingOptions フィールドを含めたい場合は、API をロードする際に Google Maps APIs Premium Plan クライアント ID を指定してください。

DrivingOptions オブジェクトに含まれるフィールドは、以下のとおりです。

{
  departureTime: Date,
  trafficModel: TrafficModel
}

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

  • departureTimedrivingOptions オブジェクト リテラルの有効化に必要)は、出発希望時刻を Date オブジェクトとして指定します。この値は現在時刻以降に設定する必要があり、過去の時刻は指定できません。(API は全ての日時を UTC 時間に変換して、タイムゾーンによらず一貫した処理を行います。)Google Maps APIs Premium Plan をご利用の場合は、リクエストに 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 で返すよう指定します。ただし、交通状況が非常に良い日は、この値よりも短時間で到着する可能性があります。

以下は、出発時刻と trafficModel を含む運転ルートの 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 フィールドで渡した場所を含む配列です。住所はジオコーダによってフォーマットされたものが返されます。
  • rowsDistanceMatrixResponseRow オブジェクトの配列で、各行が 1 つの出発地に対応しています。
  • elementsrows の子要素で、その行の出発地と各目的地のペアに対応しています。これには、出発地と目的地のペアごとのステータス、所要時間、距離、運賃の情報が含まれます。
  • element に含まれるフィールドは次のとおりです。
    • status:有効なステータス コードのリストについては、ステータス コードをご覧ください。
    • duration:このルートの所要時間です。秒単位(value フィールド)の text として表されます。テキストの値は、リクエストで指定された unitSystem に従って(設定されてない場合はメート法で)フォーマットされます。
    • duration_in_traffic:現在の交通状況を考慮した場合に、このルートの移動にかかる時間です。秒単位(value フィールド)と text で表現されます。テキストの値は、リクエストで指定された unitSystem に従って(設定されてない場合はメート法で)フォーマットされます。duration_in_traffic は、Google Maps APIs Premium Plan にのみ対応しているフィールドです。この値が返されるのは、交通状況が取得でき、modedriving に設定されおり、さらに 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 == '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 Maps JavaScript API
Google Maps JavaScript API
ご不明な点がありましたら、Google のサポートページをご覧ください。