ルートサービス

概要

DirectionsService オブジェクトを使用すると、さまざまな交通手段を利用したルートが計算できます。このオブジェクトは Google Maps API のルートサービスと通信を行い、ルートサービスはルートリクエストを受信して計算結果を返します。こうして得られたルートの結果は、自身で処理したり、DirectionsRenderer オブジェクトを使ってレンダリングしたりできます。

ルートリクエストでは、クエリ文字列（「シカゴ、イリノイ」、「ダーウィン、NSW、オーストラリア」など）や LatLng 値、google.maps.Place オブジェクト使って出発地や目的地を指定します。

ルートサービスは一連のウェイポイントを使用して、複数の部分から成るルートを返すことができます。ルートはマップ上にポリラインとして描画され、<div> 要素内にある一連のテキスト（「ウィリアムズバーグ橋のランプを右折」など）も追加で表示されることがあります。

ルートリクエスト

ルートサービスにアクセスすると、Google Maps API は外部サーバーに対して呼び出しを行うので、処理が非同期になります。そのため、リクエストの完了時に実行されるコールバック メソッドを渡して、このコールバックメソッドで結果を処理する必要があります。なお、ルートサービスは複数の候補ルートを別々の routes[] 配列として返すこともあります。

Google Maps JavaScript API でルートを扱うには、タイプ DirectionsService のオブジェクトを作成して、DirectionsService.route() を呼び出します。そしてルートサービスへのリクエストを開始し、入力内容を含む DirectionsRequest オブジェクトリテラルと、レスポンスの受信時に実行するコールバックメソッドを渡します。

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

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

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

origin（必須）は、計算するルートの出発地を指定します。この値は String（「シカゴ、イリノイ」など）や LatLng 値、google.maps.Place オブジェクトとして指定します。google.maps.Place を使用している場合は、プレイス ID、クエリ文字列、LatLng の場所を指定することも可能です。プレイス ID は、Google Maps JavaScript API のジオコーディングやプレイス検索、プレイスオートコンプリートサービスによって取得できます。プレイスオートコンプリートのプレイス ID の使用例については、プレイスオートコンプリートとルートをご覧ください。
destination（必須）は、計算するルートの目的地を指定します。使用できるオプションは、上述の origin フィールドと同じです。
travelMode（必須）は、ルートを計算する際に使用する交通手段を指定します。使用可能な値については、後述の交通手段をご覧ください。
transitOptions（必須）は、travelMode が google.maps.TravelMode.TRANSIT の時だけ、リクエストに適用する値を指定します。使用可能な値については、後述の交通機関のオプションをご覧ください。
drivingOptions（任意） – travelMode が google.maps.TravelMode.DRIVING の時だけリクエストに適用される値を指定します。使用可能な値については、後述の運転オプションをご覧ください。
unitSystem（任意）は、結果の表示に使う単位系を指定します。使用可能な値については、後述の単位系をご覧ください。
waypoints[]（任意）は、DirectionsWaypoint の配列を指定します。ウェイポイントとは指定された場所を経由するようにルートを変更するもので、以下のフィールドを持つオブジェクトリテラルとして指定されます。
- location はジオコードするウェイポイントの場所を、LatLng、google.maps.Place オブジェクト、または String として指定します。
- stopover はウェイポイントがルート上の経由地であることを示すブール値で、ルートを二分割する機能があります。
（ウェイポイントの詳細については、後述のルート内でのウェイポイントの使用をご覧ください）。
optimizeWaypoints（任意）は、指定した waypoints を最適化して、最短ルートを返すよう指定します。この値が true なら、ルートサービスは並べ替えた waypoints を waypoint_order フィールドに返します（詳細については、後述のルート内でのウェイポイントの使用をご覧ください）。
provideRouteAlternatives（任意）は、true に設定された場合に、ルートサービスが複数の代替ルートをレスポンスに返すよう指定します。代替ルートの提供は、サーバーからの応答時間が長くなることがあるので、注意してください。
avoidHighways（任意）は、true に設定された場合、できる限り主要幹線道路を避けたルートを計算するよう指定します。
avoidTolls（任意）は、true に設定された場合、できる限り有料道路を避けたルートを計算するよう指定します。
region（任意）は、ccTLD（「トップレベルドメイン」）の 2 文字で指定される地域コードを指定します。（詳細については、後述の地域のバイアスをご覧ください）。

注：durationInTraffic フィールドは、既に廃止されました。このフィールドは、所要時間を計算する際に、現時点の交通状況を考慮するか否かを指定する方法として、Google Maps API for Work の利用者向けに推奨されていました。今後は、代わりに drivingOptions フィールドを使用してください。

以下は DirectionsRequest の例です。

{
  origin: "Chicago, IL",
  destination: "Los Angeles, CA",
  waypoints: [
    {
      location:"Joplin, MO",
      stopover:false
    },{
      location:"Oklahoma City, OK",
      stopover:true
    }],
  provideRouteAlternatives: false,
  travelMode: google.maps.TravelMode.DRIVING,
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: google.maps.TrafficModel.PESSIMISTIC
  }
  unitSystem: UnitSystem.IMPERIAL
}

交通手段

ルートを計算するときは、使用する交通手段を指定する必要があります。現在サポートされている交通手段は、次のとおりです。

google.maps.TravelMode.DRIVING（デフォルト）は、道路網を使う標準の運転ルートをリクエストします。
google.maps.TravelMode.BICYCLING は、自転車専用道路と優先道路を使う自転車ルートをリクエストします。
google.maps.TravelMode.TRANSIT は、公共交通機関を使うルートをリクエストします。
google.maps.TravelMode.WALKING は、歩行者専用道路と歩道を使う徒歩ルートをリクエストします。

各国でサポートされているルートについては、Google Maps の対象データをご覧ください。指定のルートタイプが利用できない地域でルートをリクエストした場合は、DirectionsStatus が ZERO_RESULTS で返されます。

徒歩ルートには、正確な歩行者専用道路が含まれるとは限らないので、徒歩ルートをリクエストすると DirectionsResult に警告が返されます。デフォルトの DirectionsRenderer を使用していない場合は、この警告を表示するようにしてください。

交通機関のオプション

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

ルートリクエストで利用できるオプションは、交通手段によって異なります。交通機関のルートをリクエストした場合、オプションの avoidHighways、avoidTolls、waypoints[]、optimizeWaypoints は無視されます。交通機関に固有のルートオプションを指定するには、TransitOptions オブジェクトリテラルを使います。

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

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

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  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 は、歩行距離が短いルートを計算するよう指定します。

以下は、交通機関を使った DirectionsRequest の例です。


{
  origin: "Hoboken NJ",
  destination: "Carroll Gardens, Brooklyn",
  travelMode: google.maps.TravelMode.TRANSIT,
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: [google.maps.TransitMode.BUS],
    routingPreference: google.maps.TransitRoutePreference.FEWER_TRANSFERS
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

運転オプション

運転ルートに固有のルートオプションを指定するには、DrivingOptions オブジェクトを使用します。DirectionsRequest に 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 で返すよう指定します。ただし、交通状況が非常に良い日は、この値よりも所要時間が短くなる可能性があります。

以下は、運転ルートの DirectionsRequest の例です。

{
  origin: "Chicago, IL",
  destination: "Los Angeles, CA",
  travelMode: google.maps.TravelMode.DRIVING,
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: "optimistic"
  }
}

単位系

デフォルトでは、出発地の国や地域の単位系を使用してルートの計算や表示を行います。（注: 出発地を住所ではなく、緯度と経度を用いた座標で指定した場合は、常にメートル法がデフォルトになります）。たとえば、「イリノイ州シカゴ」から「オンタリオ州トロント」へのルートはマイル単位で結果が表示され、この逆のルートはキロメートル単位で表示されます。この単位系をオーバーライドするには、次の UnitSystem 値のいずれかを使って、リクエスト内で明示的に単位系を設定します。

UnitSystem.METRIC はメートル法を使用するよう指定します。距離はキロメートルで表示されます。
UnitSystem.IMPERIAL はヤードポンド法を使用するよう指定します。距離はマイルで表示されます。

注: この単位系の設定は、ユーザーに表示されるテキストにのみ反映されます。ルートの結果にはユーザーに表示されない距離も含まれますが、それらの値は常にメートル単位で表されます。

ルートの地域バイアス

Google Maps API ルートサービスは、JavaScript ブートストラップをロードしたドメイン（地域や国）に応じた住所の結果を返します。（多くのユーザーは http://maps.google.com/ をロードしており、この場合は暗黙的に米国がドメインに設定されます）。サポートされている別のドメインからブートストラップをロードした場合は、そのドメインに対応した結果が得られます。例えば、同じ「サンフランシスコ」を検索しても、http://maps.google.com/（米国）をロードするアプリが返す結果と、http://maps.google.es/（スペイン）をロードするアプリが返す結果は異なります。

region パラメータを使うと、ルートサービスが特定の地域を優先して結果を返すようバイアスをかけることもできます。このパラメータには、IANA 言語の region サブタグとして指定される地域コードを使います。これらのタグはたいてい、「co.uk」が「uk」に対応するように、ccTLD（「トップレベルドメイン」）の 2 文字に直接マッピングされます。region タグが ISO-3166-1 コードをサポートする場合もありますが、これは ccTLD の値（「Great Britain」の「GB」など）とは異なることがあります。

各国でサポートされているルートについては、Google Maps の対象データをご覧ください。

ルートのレンダリング

DirectionsService へのルートリクエストを route() メソッドを使って開始する場合、サービスリクエストの完了時に実行されるコールバックを渡す必要があります。このコールバックは、レスポンスで DirectionsResult と DirectionsStatus コードを返します。

ルートクエリのステータス

DirectionsStatus で返される値は、以下のとおりです。

OK は、レスポンスに有効な DirectionsResult が含まれていることを示します。
NOT_FOUND は、リクエストで指定した出発地、目的地、ウェイポイントのうち、少なくとも 1 つの場所がジオコーディングできなかったことを示します。
ZERO_RESULTS は、出発地と目的地の間にルートが見つからなかったことを示します。
MAX_WAYPOINTS_EXCEEDED は、DirectionsRequest に指定された DirectionsWaypoint が多すぎることを示します。ウェイポイントの最大登録件数は、8 に出発地と到着地を加えた数です。Google Maps API for Work をご利用の場合は、23 個のウェイポイントと出発地、到着地を登録できます。ウェイポイントは交通機関のルートに対してはサポートされていません。
INVALID_REQUEST は、指定した DirectionsRequest が無効であることを示します。このエラーの一般的な原因としては、リクエストで出発地か目的地を指定していない、または交通機関を使うリクエストでウェイポイントを指定していることが考えられます。
OVER_QUERY_LIMIT は、許可された期間内にウェブページから送信されたリクエストが多すぎることを示します。
REQUEST_DENIED は、ルートサービスを利用できないウェブページであることを示します。
UNKNOWN_ERROR は、サーバーのエラーでルートリクエストが処理できなかったことを示します。再度リクエストすると、成功する可能性があります。

結果を処理する前に、これらの値を確認して、ルートクエリが有効な結果を返したことを確かめるようにしてください。

DirectionsResult の表示

DirectionsResult にはルートクエリの結果が含まれており、自身で処理することも、DirectionsRenderer オブジェクトに渡して、マップ上に自動で表示させることもできます。

DirectionsRenderer を使用して DirectionsResult を表示するには、以下の処理が必要です。

DirectionsRenderer オブジェクトを作成します。
レンダラで setMap() を呼び出して、渡されたマップにバインドします。
レンダラで setDirections() を呼び出して、前述の DirectionsResult に渡します。レンダラは MVCObject なので、プロパティの変更を自動で検出し、関連付けられたルートが変更されるとマップを更新します。

以下の例は、ルート 66 上にある 2 つの地点間のルートを計算します。出発地と到着地は、ドロップダウンリストで選択した "start" と "end" の値になります。DirectionsRenderer は、指定された 2 地点を結ぶポリラインを表示し、出発地と到着地、ウェイポイント（存在する場合）にマーカーを配置します。

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);
  directionsDisplay.setMap(map);
}

function calcRoute() {
  var start = document.getElementById("start").value;
  var end = document.getElementById("end").value;
  var request = {
    origin:start,
    destination:end,
    travelMode: google.maps.TravelMode.DRIVING
  };
  directionsService.route(request, function(result, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay.setDirections(result);
    }
  });
}

以下は HTML の本文です。

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

例を見る（directions-simple.html）

次の例は、カリフォルニア州サンフランシスコのハイトアシュベリーとオーシャンビーチ間の各移動手段によるルートを表示します。

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;
var haight = new google.maps.LatLng(37.7699298, -122.4469157);
var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);
  directionsDisplay.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById("mode").value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that Javascript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay.setDirections(response);
    }
  });
}

以下は HTML の本文です。

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

例を見る（directions-travel-modes.html）

DirectionsRenderer を使うと、ポリラインや関連付けられたマーカーを表示するだけでなく、一連の道順を説明したテキストも表示できます。そのためには、DirectionsRenderer で setPanel() を呼び出して、情報を表示する <div> を渡します。こうすると、適切な著作権情報と結果に関連する警告も必ず表示されます。

テキストによる経路説明は、ブラウザの言語設定か、language パラメータを使って API JavaScript をロードしたときに指定した言語で表示されます。（詳細については、ローカライズをご覧ください）。交通機関のルートにおける時刻は、該当する駅や停留所のタイムゾーンで表示されます。

次の例は、道順を表示する <div> パネルを 1 つ前の例に追加したものです。

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);
  directionsDisplay.setMap(map);
  directionsDisplay.setPanel(document.getElementById("directionsPanel"));
}

function calcRoute() {
  var start = document.getElementById("start").value;
  var end = document.getElementById("end").value;
  var request = {
    origin:start,
    destination:end,
    travelMode: google.maps.TravelMode.DRIVING
  };
  directionsService.route(request, function(response, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay.setDirections(response);
    }
  });
}

以下は HTML の本文です。

<div id="map" style="float:left;width:70%; height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height 100%"></div>

例を見る（directions-panel.html）

DirectionsResults オブジェクト

DirectionsService にルートリクエストを送ると、レスポンスとしてステータスコードと結果の DirectionsResult が取得できます。DirectionsResult は以下のフィールドを持つオブジェクトリテラルです。

geocoded_waypoints[] には DirectionsGeocodedWaypoint オブジェクトの配列が入っていて、各オブジェクトには出発地、目的地、ウェイポイントにおけるジオコーディングの詳細情報が含まれています。
routes[] には DirectionsRoute オブジェクトの配列が含まれます。各ルートは、DirectionsRequest で指定された出発地から目的地までの経路を示します。一般的には、1 件のリクエストに対しては 1 件のルートのみが返されます。ただし、provideRouteAlternatives フィールドが true に設定されていると、複数のルートが返されることもあります。

ジオコーディングされたウェイポイントのルート

DirectionsGeocodedWaypoint には出発地、目的地、ウェイポイントのジオコーディングの詳細情報が含まれます。

DirectionsGeocodedWaypoint は、以下のフィールドを持つオブジェクトリテラルです。

geocoder_status は、ジオコーディングの処理結果を示すステータスコードです。このフィールドには次の値が含まれます。
- OK: エラーが発生しなかったことを示します。住所の解析が成功し、少なくとも 1 件のジオコードが返されました。
- ZERO_RESULTS: ジオコーディングは成功したものの結果が返されなかったことを示します。これは、ジオコーダに存在しない address が渡された場合に発生することがあります。
partial_match は、元のリクエストに完全一致する住所は見つからなかったものの、部分一致する住所は見つかったことを示します。元のリクエストで住所の表記が間違っていたり、不完全である可能性があります。

多くの場合、リクエストで渡された地域に番地が存在しないために部分一致が発生します。また、同じ地域内に複数の場所があるリクエストを行った場合も部分一致が返されます。たとえば、「21 Henr St, Bristol, UK」には、「Henry Street」と「Henrietta Street」の両方への部分一致が返されます。リクエストに表記が間違った住所コンポーネントが含まれている場合、ジオコーディングサービスが別の住所を提示することもある点に注意してください。この場合も、部分一致として結果が返されます。
place_id は、他の Google API と一緒に使用できるプレイス固有の識別子です。たとえば、place_id と Google Places API ライブラリを一緒に使うと、電話番号や営業時間、ユーザーの口コミなどのローカルビジネスの詳細情報を取得できます。詳しくは、プレイス ID の概要をご覧ください。
types[] は、返された結果のタイプを示す配列です。この配列には、結果として返された地物のタイプを表す 0 個以上のタグのセットが含まれています。たとえば「シカゴ」をジオコーディングすると、「シカゴ」が都市であること示す「locality」に加え、行政上のエンティティであることを示す「political」が返されます。

ルート案内

従来の DirectionsTrip オブジェクトは、DirectionsRoute に名称が変わりました。ルートは、旅程に含まれる 1 区間を表すだけでなく、出発から到着までの全体的な行程を表すようになったことに注意してください。

DirectionsRoute には、指定の出発地と目的地から得られた結果が 1 件含まれています。ウェイポイントが指定されている場合は、このルートは 1 つ以上の（タイプ DirectionsLeg の）区間から構成されます。また、ルートには経路情報の他に、著作権や警告に関する情報など、ユーザーへの表示が必要な内容も含まれています。

DirectionsRoute は、以下のフィールドを持つオブジェクトリテラルです。

legs[] は、DirectionsLeg オブジェクトの配列です。各オブジェクトには、指定されたルート上の 2 地点を結ぶ区間の情報が含まれています。指定したウェイポイントや目的地ごとに、1 つの区間が存在します（ウェイポイントが 1 つもないルートには、DirectionsLeg が 1 つだけ含まれます）。各区間は一連の DirectionStep から成ります。
waypoint_order には、計算されたルート上にあるウェイポイントの順番を示す配列が含まれます。DirectionsRequest に optimizeWaypoints: true を渡した場合、この配列には変更された順序が格納されることがあります。
overview_path には、結果のルートを近似した（平滑化した）経路を表す LatLng の配列が含まれます。
overview_polyline には、ルートを表すエンコードしたポリラインを持つ points オブジェクトが 1 つ含まれます。このポリラインは、結果のルートを近似した（平滑化した）経路です。
bounds には、指定したルート上にあるポリラインの境界を示す LatLngBounds が含まれます。
copyrights には、このルートで表示が必要な著作権に関するテキストが含まれます。
指定された DirectionsRenderer オブジェクトを使わない場合は、この情報を自身で処理して表示する必要があります。
warnings[] には、これらのルートで表示が必要な警告文の配列が含まれています。指定された DirectionsRenderer オブジェクトを使わない場合は、これらの警告を自身で処理して表示する必要があります。
fare には、このルートの合計運賃（乗車券の合計金額）が含まれています。このプロパティは、交通機関のリクエストにおいて、すべての区間で運賃情報が取得できる場合にのみ返されます。次の情報が含まれます。
- currency:ISO 4217 通貨コードは、運賃を表示する通貨を指定します。
- value:上記で指定した通貨での合計運賃です。

ルート区間

従来の DirectionsRoute オブジェクトは、DirectionsLeg に名称が変わりました。

DirectionsLeg は、ルートを計算する出発地から目的地までの行程における 1 つの移動区間を定義します。ウェイポイントがないルートは、1 つの「区間」で構成されますが、1 つ以上のウェイポイントがあるルートは、行程の特定の区間に対応する 1 つ以上の区間で構成されます。

DirectionsLeg は、以下のフィールドを持つオブジェクトリテラルです。

steps[] には、移動区間の各ステップ情報を示す DirectionsStep オブジェクトの配列が含まれます。
distance は、この区間の総距離を以下の形式の Distance オブジェクトで表します。
- value は距離をメートル単位で表します。
- text は距離を文字列で表現したもので、デフォルトでは出発地で使用されている単位系を使って表示されます。（例えば、米国内の出発地であればマイル表記になります）。この単位系をオーバーライドするには、元のクエリ内で UnitSystem を明示的に指定します。使用する単位系によらず、distance.value フィールドの値は常にメートル表記になるので注意してください。
距離が不明な場合、これらのフィールドは定義されないことがあります。
duration は、この区間の移動に要する合計時間を以下の形式の Duration オブジェクトとして表します。
- value は秒単位で表した所要時間です。
- text には所要時間を表す文字列が含まれます。
所要時間が不明な場合、これらのフィールドは定義されないことがあります。
duration_in_traffic は、現在の交通状況を考慮して計算した、この区間の合計所要時間です。duration_in_traffic は、Google Maps API for Work にのみ対応しているフィールドです。この値が返されるのは、交通状況が取得できて、mode が driving に設定されおり、さらに departureTime がリクエストの drivingOptions フィールドの一部として含まれている場合のみです。duration_in_traffic に含まれるフィールドは次のとおりです。
- value は秒単位で表した所要時間です。
- text は、人が読める表記を用いた所要時間です。
arrival_time には、この区間における到着予定時刻が含まれます。このプロパティは、交通機関のルートに対してのみ返されます。結果は次の 3 つのプロパティを含む Time オブジェクトとして返されます。
- value は、JavaScript の Date オブジェクトとして指定された時間です。
- text は、文字列として指定された時刻です。この時刻は、交通機関の停止地点におけるタイムゾーンで表示されます。
- time_zone には、この駅のタイムゾーンが含まれます。この値は IANA タイムゾーンデータベースで定義されたタイムゾーンの名称で、「America/New_York」のような値です。
departure_time には、Time オブジェクトとして指定された、この区間における出発予定時刻が含まれます。departure_time は、交通機関のルートに対してのみ使用できます。
start_location には、この区間の始点の LatLng が含まれます。ディレクションウェブサービスは、出発地と目的地に最も近い交通手段（たいていは道路）を使って、地点間のルートを計算します。そのため、始点の近くに道路がない場合などは、start_location と指定された区間の始点が一致しないことがあります。
end_location には、この区間の終点の LatLng が含まれます。DirectionsService は、出発地と目的地に最も近い交通手段（たいていは道路）を使って、地点間のルートを計算します。そのため、終点の近くに道路がない場合などは、end_location と指定された区間の終点が一致しないことがあります。
start_address には、人間が読める形式で表現された区間の始点の住所（通常は番地）が含まれます。
end_address には、人間が読める形式で表現された区間の終点の住所（通常は番地）が含まれます。

ルートのステップ

DirectionsStep はルートを構成する最小単位で、移動経路について詳細に説明した 1 つのステップが含まれています。たとえば、「外堀通りを左折」などの指示です。なお、ステップには進路の説明だけでなく、現在のステップと次のステップとの関連性を表す距離や所要時間などの情報も含まれます。たとえば、「東名高速道路に入る」と表示されるステップには、現在のステップから次のステップまでは 3.2 キロ / 7 分であることを示す、距離「3.7 キロ」や所要時間「7 分」といった情報が含まれます。

ディレクションサービスを使って交通機関のルートを検索すると、transit オブジェクトの形式の交通機関の詳細情報が追加でステップ配列に含まれます。異なる複数の交通機関を使用するルートの場合、steps[] 配列には徒歩ステップや運転スッテプに関する詳細な指示内容が格納されます。たとえば、徒歩ステップには「明治通りと井の頭通りを進む」のように、出発地から目的地までのルートが含まれます。このステップは、内部 steps 配列の該当するルートに詳細な徒歩ルートを含めます。内容は「東に進む」、「右折して北大路通に入る」、「左折して大宮通に入る」などです。

DirectionsStep は、以下のフィールドを持つオブジェクトリテラルです。

instructions には、このステップの説明がテキスト文字列として格納されています。
distance には、このステップに入ってから次のステップに移るまでの距離が Distance オブジェクトとして含まれます（上述の DirectionsLeg の説明をご覧ください）。距離が不明な場合、このフィールドは定義されないことがあります。
duration には、このステップに入ってから次のステップに移るまでの推定所要時間が、Duration オブジェクトとして含まれます（上述の DirectionsLeg の説明をご覧ください）。所要時間が不明な場合、このフィールドは定義されないことがあります。
start_location には、このステップの始点を表す LatLng をジオコードしたものが含まれます。
end_location には、このステップの終点を表す LatLng をジオコードしたものが含まれます。
polyline には、ステップを表すエンコードしたポリラインを持つ points オブジェクトが 1 つ含まれます。このポリラインは、ステップを近似した（平滑化した）経路です。
steps[] は DirectionsStep オブジェクトリテラルで、交通機関のルートにおける徒歩ステップまたは運転ステップの詳細な説明が含まれます。サブステップは、交通機関のルートに対してのみ有効です。
travel_mode には、このステップで使用する TravelMode が含まれます。交通機関のルートには、徒歩経路の説明と交通機関のルートの両方が含まれることがあります。
path には、ステップの進路を表す LatLngs 配列が含まれます。
transit には、出発時刻や到着時刻、路線名などの交通機関の詳細情報が含まれます。

交通機関の詳細情報

交通機関のルートは、他の移動モードには関係のない追加情報を返します。これらの追加のプロパティは、TransitDetails オブジェクトによって表示され、DirectionsStep のプロパティとして返されます。TransitDetails オブジェクトからは、後述の TransitStop、TransitLine、TransitAgency、VehicleType オブジェクトの追加情報にアクセスできます。

交通機関の詳細

TransitDetails オブジェクトは以下のプロパティを表示します。

arrival_stop には、以下のプロパティによって到着地点の駅や停留所を表す TransitStop オブジェクトが含まれます。
- name は交通機関の駅や停留所の名称です（「ユニオンスクエア」など）。
- location は LatLng で表される交通機関の駅や停留所の場所です。
departure_stop には、出発地点の駅や停留所を表す TransitStop オブジェクトが含まれます。
arrival_time には、以下の 3 つのプロパティを持つ Time オブジェクトとして指定された到着時刻が含まれます。
- value は、JavaScript の Date オブジェクトとして指定された時間です。
- text は、文字列として指定された時刻です。この時刻は、交通機関の停止地点におけるタイムゾーンで表示されます。
- time_zone には、この駅のタイムゾーンが含まれます。この値は IANA タイムゾーンデータベースで定義されたタイムゾーンの名称で、「America/New_York」のような値です。
departure_time には、Time オブジェクトとして指定された出発時刻が含まれます。
headsign は、出発する駅や停留所、車両に表示される路線の行先表示を指定します。多くの場合、この行先は終点に相当します。
headway は（利用可能な場合）、駅や停留所における現時点の運転間隔を秒単位で指定します。たとえば、headway 値が 600 の場合は、バスに乗れないと 10 分待つことになります。
line には、このステップで使用される路線情報を持つ TransitLine オブジェクトが含まれます。TransitLine は、路線名やその事業者、そして TransitLine の参考資料に記載されている他のプロパティを提供します。
num_stops は、ステップに含まれる駅や停留所の数です。この数には到着地点の駅や停留所は含まれますが、出発地点の駅や停留所は含まれません。たとえば、A 駅を出発して、B 駅と C 駅を通り、D 駅に到着するルートの場合、num_stops は 3 を返します。

交通機関の路線

TransitLine オブジェクトは以下のプロパティを公開します。

name には、この交通機関の路線の正式名称が含まれます「7 Avenue Express」、「14th St Crosstown」などです。
short_name には、この交通機関の路線の略称が含まれます。これは通常、「2」や「M14」などです。
agencies には、タイプ TransitAgency の配列が含まれます。各 TransitAgency オブジェクトには、路線の運営事業者の情報を持つ次のプロパティがあります。
- name には交通機関の名称が含まれます。
- url には交通機関の運行事業者の URL が含まれます。
- phone には交通機関の運行事業者の電話番号が含まれます。
DirectionsRenderer オブジェクトを使わずに手動で交通機関のルートをレンダリングする場合は、この経路情報を提供する交通機関の名称と URL を表示する必要があります。
url には、交通機関が提供する路線の URL が含まれます。
icon には、この路線と関連付けられたアイコンの URL が含まれます。多くの都市では、交通機関のタイプ別の共通アイコンを使用していますが、ニューヨーク市地下鉄など一部の路線では、その路線専用のアイコンを使っています。
color には、この交通機関の表記に一般的に使用される色が含まれます。この色は、#FF0033 のような 16 進の文字列で指定されます。
text_color には、この路線の表記に通常使用されるテキストの色が含まれます。この色は、16 進の文字列で指定されます。
vehicle には、以下のプロパティを持つ Vehicle オブジェクトが含まれます。
- name には、この路線の乗り物の名称が含まれます（「地下鉄」など）。
- type には、その路線で使われている乗り物のタイプが含まれます。サポートされている値の完全なリストについては、乗り物の種別の説明をご覧ください。
- icon には、この乗り物のタイプに一般的に関連付けられたアイコンの URL が含まれます。
- local_ icon には、特定の地域において、この乗り物のタイプに関連付けられたアイコンの URL が含まれます。

乗り物の種別

VehicleType オブジェクトは以下のプロパティを公開します。

値	定義
`VehicleType.RAIL`	鉄道。
`VehicleType.METRO_RAIL`	ライトレールトランジット。
`VehicleType.SUBWAY`	地下を走るライトレール。
`VehicleType.TRAM`	地上を走るライトレール。
`VehicleType.MONORAIL`	モノレール。
`VehicleType.HEAVY_RAIL`	ヘビーレール。
`VehicleType.COMMUTER_TRAIN`	通勤列車。
`VehicleType.HIGH_SPEED_TRAIN`	高速列車。
`VehicleType.BUS`	バス。
`VehicleType.INTERCITY_BUS`	長距離バス。
`VehicleType.TROLLEYBUS`	トロリーバス。
`VehicleType.SHARE_TAXI`	乗合タクシーは、ルート上のどこでも乗客が乗り降りできるバスの一種です。
`VehicleType.FERRY`	フェリー。
`VehicleType.CABLE_CAR`	ケーブルが引かれている場所を走る乗り物で、主に地上を走行します。ケーブルに吊り下げられた状態で走るケーブルカーは、タイプ `VehicleType.GONDOLA_LIFT` に入ります。
`VehicleType.GONDOLA_LIFT`	空中ケーブルカー。
`VehicleType.FUNICULAR`	険しい斜面をケーブルで引っ張る乗り物。ケーブルカーは一般的に 2 両編成で、車両は互いに重量のバランスを取ります。
`VehicleType.OTHER`	その他の乗り物については、すべてこの種別が返されます。

DirectionsResults の調査

DirectionsResults コンポーネント（DirectionsRoute、DirectionsLeg、DirectionsStep、TransitDetails）はルートレスポンスの解析時に調査、使用されることがあります。

重要:DirectionsRenderer オブジェクトを使わずに手動で交通機関のルートをレンダリングする場合は、この経路情報を提供する交通機関の名称と URL を表示する必要があります。

以下の例は、ニューヨークの観光名所までの徒歩ルートを描画します。ステップごとにルートの DirectionsStep を調査してマーカーを追加し、ステップの説明テキストと情報を InfoWindow に追加します。

ここでは徒歩ルートを計算するので、独立した <div> パネルにユーザーへの警告メッセージも表示します。

var map;
var directionsDisplay;
var directionsService;
var stepDisplay;
var markerArray = [];

function initialize() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsDisplay = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById("start").value;
  var end = document.getElementById("end").value;
  var request = {
      origin: start,
      destination: end,
      travelMode: google.maps.TravelMode.WALKING
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsDisplay.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

以下は HTML の本文です。

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

例を見る（directions-complex.html）

ルート内でのウェイポイントの使用

ルートリクエストの説明でも触れましたが、ルートサービスを使用して徒歩や自転車、車でのルートを計算する際は、ウェイポイント（タイプ DirectionsWaypoint）を指定することもできます。ウェイポイントは交通機関のルートに対しては利用できません。ウェイポイントを使用すると、ウェイポイントとして追加した地点を通るルートを取得できます。

ウェイポイントの最大登録件数は、8 に出発地と到着地を加えた数です。Google Maps API for Work をご利用の場合は、23 個のウェイポイントと出発地、到着地を登録できます。ウェイポイントは交通機関のルートに対してはサポートされていません。

waypoint は次のフィールドから構成されます。

location（必須）は、ウェイポイントの住所を指定します。
stopover（任意）は、このウェイポイントが実際にルートの立ち寄り地点か（true）、その場所を通るよう推奨しているだけか（false）を指定します。このフィールドのデフォルト値は true です。

ルートサービスはデフォルトで、指定したウェイポイントを、指定した順番で通るルートを計算します。任意で、optimizeWaypoints: true を DirectionsRequest 内に渡すと、ルートサービス側はウェイポイントを効率的な順番に並べ替えて、指定したルートを最適化します（この最適化では、巡回セールスマン問題が応用されています）。ルートサービスでルートを最適化するには、すべてのウェイポイントが立ち寄り地点である必要があります。

ルートサービスでウェイポイントの順番を最適化するよう指定した場合、並び変えた順番は DirectionsResult オブジェクト内の waypoint_order フィールドに返されます。

次の例では、始点や終点、ウェイポイントを変えて、米国を横断するさまざまなルートを計算できます（複数のウェイポイントを選択するには、リスト内でアイテムを選択するときに Ctrl キーを押しながらクリックします）。routes.start_address と routes.end_address を調べて、各ルートの始点と終点のテキストを取得していることに注意してください。

function initMap() {
  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer;
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 6,
    center: {lat: 41.85, lng: -87.65}
  });
  directionsDisplay.setMap(map);

  document.getElementById('submit').addEventListener('click', function() {
    calculateAndDisplayRoute(directionsService, directionsDisplay);
  });
}

function calculateAndDisplayRoute(directionsService, directionsDisplay) {
  var waypts = [];
  var checkboxArray = document.getElementById('waypoints');
  for (var i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true
      });
    }
  }

  directionsService.route({
    origin: document.getElementById('start').value,
    destination: document.getElementById('end').value,
    waypoints: waypts,
    optimizeWaypoints: true,
    travelMode: google.maps.TravelMode.DRIVING
  }, function(response, status) {
    if (status === google.maps.DirectionsStatus.OK) {
      directionsDisplay.setDirections(response);
      var route = response.routes[0];
      var summaryPanel = document.getElementById('directions-panel');
      summaryPanel.innerHTML = '';
      // For each route, display summary information.
      for (var i = 0; i < route.legs.length; i++) {
        var routeSegment = i + 1;
        summaryPanel.innerHTML += '<b>Route Segment: ' + routeSegment +
            '</b><br>';
        summaryPanel.innerHTML += route.legs[i].start_address + ' to ';
        summaryPanel.innerHTML += route.legs[i].end_address + '<br>';
        summaryPanel.innerHTML += route.legs[i].distance.text + '<br><br>';
      }
    } else {
      window.alert('Directions request failed due to ' + status);
    }
  });
}

例を見る（directions-waypoints.html）

ドラッグ可能なルート

DirectionsRenderer で動的に表示した自転車、徒歩、運転ルートがドラッグ可能な場合、ユーザーは結果としてマップ上に表示された経路をクリック＆ドラッグすることで、ルートの選択や変更ができます。レンダラの表示でルートをドラッグできるように指定するには、draggable プロパティを true に設定します。なお、交通機関のルートはドラッグできません。

ドラッグ可能なルートの場合、ユーザーはレンダリングされた経路の任意の地点（またはウェイポイント）を選択して、そのコンポーネントを新しい位置に動かすことができます。その際 DirectionsRenderer は動的に更新されて変更された経路を表示します。ユーザーがドロップすると、暫定的なウェイポイント（白い小さなマーカー）がマップに追加されます。経路のセグメントを選択して動かすと、そのルートの該当区間が変更され、ウェイポイントマーカー（始点と終点を含む）を選択して動かすと、そのウェイポイントを通るルートの区間が変更されます。

ドラッグ可能なルートの変更や表示はクライアント側で処理します。表示中のルートをユーザーが更新したことを検知するには、DirectionsRenderer への directions_changed イベントを監視して処理します。

以下のコードは、シドニーを出発してニューサウスウェールズの内陸部を通るルートを表示します。ここでは、directions_changed イベントを監視して、移動区間の総距離を更新しています。

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -24.345, lng: 134.46}  // Australia.
  });

  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer({
    draggable: true,
    map: map,
    panel: document.getElementById('right-panel')
  });

  directionsDisplay.addListener('directions_changed', function() {
    computeTotalDistance(directionsDisplay.getDirections());
  });

  displayRoute('Perth, WA', 'Sydney, NSW', directionsService,
      directionsDisplay);
}

function displayRoute(origin, destination, service, display) {
  service.route({
    origin: origin,
    destination: destination,
    waypoints: [{location: 'Cocklebiddy, WA'}, {location: 'Broken Hill, NSW'}],
    travelMode: google.maps.TravelMode.DRIVING,
    avoidTolls: true
  }, function(response, status) {
    if (status === google.maps.DirectionsStatus.OK) {
      display.setDirections(response);
    } else {
      alert('Could not display directions due to: ' + status);
    }
  });
}

function computeTotalDistance(result) {
  var total = 0;
  var myroute = result.routes[0];
  for (var i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }
  total = total / 1000;
  document.getElementById('total').innerHTML = total + ' km';
}

例を見る（directions-draggable.html）

ルートサービス

概要

ルート リクエスト

交通手段

交通機関のオプション

運転オプション

単位系

ルートの地域バイアス

ルートのレンダリング

ルートクエリのステータス

DirectionsResult の表示

DirectionsResults オブジェクト

ジオコーディングされたウェイポイントのルート

ルート案内

ルート区間

ルートのステップ

交通機関の詳細情報

交通機関の詳細

交通機関の路線

乗り物の種別

DirectionsResults の調査

ルート内でのウェイポイントの使用

ドラッグ可能なルート

フィードバックを送信...

ルートリクエスト