Maps API V3 サービス

ジオコーディング

ジオコーディングとは、住所を地理的な座標に変換する処理のことで、あなたはマーカーの配置や地図の表示に利用することができます。
(例えば"東京都千代田区永田町1-7-1"は、緯度:35.6758907, 経度:139.7448603となります)

Google Maps API にはユーザーが入力した動的な住所をジオコーディングするためのクラスが用意されています。もしそうではなく、静的なジオコーディングを行ないたい場合(ユーザーの入力ではなく、既に分かっている住所を変換したいとき)は、HTTP Geocoding Service ドキュメントを読んでください。 (注:HTTPサービスを使いたいときは、事前に APIキーの申請が必要です。)

ジオコーディングリクエスト

ジオコーディングサービスへのアクセスは非同期なため、Google Maps APIからは外部サーバーを呼び出すようにします。リクエストの実行時にコールバックを渡さなければなりません。このコールバックで結果を処理します。(注:ジオコーダーは1つまたは複数の結果を返します。)

コードからGoogle Maps API ジオコーディングサービスには、 google.maps.Geocoder オブジェクトを使ってアクセスします。 Geocoder.geocode() メソッドは、GeocodeRequest オブジェクト定数に含まれる入力項目を初期化し、ジオコーディングサービスにリクエストを行ないます。レスポンスを受け取ったらコールバックを実行します。

GeocodeRequest オブジェクト定数には次のような項目が含まれます。

{
 address
: string,
 latLng
: LatLng,
 bounds
: LatLngBounds,
 language
: string,
 country
: string,
}

それぞれの意味は次の通りです。

  • address (必須) ? あなたがジオコーディングしたい住所*
  • latLng (必須*) ? 経度緯度から付近の住所を取得(リバースジオコーディング)したい場合の緯度経度
  • bounds (オプション) ? ジオコーディングの範囲を限定したい範囲 ( ビューポートのバイアス を参照)
  • language (オプション) ? 取得したい結果の言語 (例:ja)
  • region (オプション) ? 国識別コード。(例:JP)(国識別コードによるバイアス を参照.)

* Note:  address または latLng のどちらかのみを指定してください。 (もしlatLngが渡されたときは、ジオコーダーはリバースジオコーディングを行ないます。 Reverse Geocoding を参照)


ジオコーディングレスポンス

ジオコーディングサービスには、ジオコーディングの結果を処理するためのコールバックが必要です。コールバックには results と status コードの順で2つのパラメータが渡されます。ジオコーダーからは1つまたはそれ以上の結果が GeocodeResults オブジェクト定数の配列として渡されます。

ジオコーディング結果

GeocodeResults オブジェクト定数は次のような形式のJSONオブジェクトです。

results[]: {
 types
[]: google.maps.GeocoderLocationType,
 formatted_address
: String,
 address_components
[]: {
   short_name
: String,
   long_name
: String,
   types
[]: String
 
},
 geometry
: {
   location
: LatLng,
   location_type
: String
   viewport
: LatLngBounds,
   bounds
: LatLngBounds
 
}
}

これらの項目は次の通りです。

  • types[] は検索結果のタイプを表しています。この配列には、1つまたは複数のタグが含まれます。例えば、"横浜市" のジオコーディング結果は "locality" と"political"を返します。これは "横浜市"は街で、"political"は政治的に定義された地理的地方であることを表しています。
      <例>
        日本 → "country", "political"
        東京 → "administrative_area_level_1", "political"     東京都渋谷区 → "locality", "political"  東京都渋谷区桜丘町26-1 → "sublocality", "political"

  • formatted_address は人間が読むことができる住所です。"郵便住所"と同じですが、国ごとによって違います (グレート・ブリテンのようないくつかの国では、正しい住所を再配布するためには料金を支払わなければならない制約があるためです) 。この住所は1つまたは複数の住所要素が含まれて生成されます。例えば"東京都渋谷区桜丘町26-1"は "日本東京都渋谷区桜丘町26-1"になります。"26"は"sublocality", "桜丘町"も"sublocality", "渋谷区"は "locality", "東京都"は"administrative_area_level_1", "日本"は"country"です。

  • address_component[] は上記の住所要素が分割されて含まれています。

  • geometry には次のような情報が含まれています。

    • location には緯度経度の値が含まれます。(注:このlocationは書式化された文字列ではなく、 LatLng オブジェクトを返します。)
    • location_type にはその場所に関する追加的なデータが保存されています。現在は次の値がサポートされています。

      • google.maps.GeocoderLocationType.ROOFTOP には正確なジオコード結果が含まれています。
      • google.maps.GeocoderLocationType.RANGE_INTERPOLATED は正確な2点間の交わる地点によって補間された結果(通常はストリート名が使用されます)が含まれます。 補間された結果はrooftopジオコーダーがストリート名を利用できないときに生成されて返されます。
      • google.maps.GeocoderLocationType.GEOMETRIC_CENTER はポリゴン(例えばストリート)やポリゴン(region)の地理的な中心位置の結果であることを示しています。
      • google.maps.GeocoderLocationType.APPROXIMATE はおよその結果であることを示しています。
    • viewport は結果を表示するための推奨されるビューポートが含まれます。
    • bounds (オプション的に返されます) は結果を全体的に含むことができる LatLngBounds を返します。このboundsは推奨されるviewportと一致するものではないかもしれません。(例えば、サンフランシスコは Farallon islands を含みますが、viewportには含まれません。)

住所要素のタイプ

types[] 配列は住所タイプを示す結果を返します。これらのタイプは address_components[] 配列を含むことがあり、各住所要素のタイプを示しています。住所はジオコーダー内部の複数のタグを持つかもしれません。例えば、多くの都市では political と locality タグを持ちます。

HTTP ジオコーダーは以下の値を返します。

  • street_address は正確なストリート名を示します。
  • route は名づけられた道路であることを示します(例えば日本国道246号線)。
  • intersection は有名な交差点(通常は2つの有名な道路)であることを示します。
  • political は政治的に定義された地理的地方であることを示します。通常はこのタイプはいくつかの民生のポリゴンが用いられます。
  • country は国際的な政治的に定義された地域で、通常はジオコーダによって返されるタイプで最も高いものです。
  • administrative_area_level_1 は国レベルの中で、一番大きい民生的な地域です。イギリスの例では、Englandになります。日本の場合では、都道府県を指します。
  • administrative_area_level_2 は国レベルで2番目に大きい民生的な地域です。イギリスの例では、Greater Londonになります。
  • administrative_area_level_3 は国レベルで3番目に大きい民生的な地域です。このタイプはマイナーな民生的地域であることを示します。イギリスの例では、Westminsterになります。
  • colloquial_area は一般的に使われる別の名称を示しています。例えば日本では東京23区です。
  • locality は県・州の議会にて正式に自治体として認められた政治的な地域であることを示しています。
  • sublocality はlocality の中で一番大きい民生的な地域であることを示しています。
  • neighborhood は地域的な区域であることを示しています。(例:プリトヴィツェ湖群国立公園)
  • premise は名づけられた場所を示します。一般的には、有名なビル名や集合団地の名前などです。
  • subpremise はpremiseの中で一番大きい名づけられた場所であることを示します。一般的には集合団地の中での1つの建物の名前などです。
  • postal_codeは各国で郵便を行なうときに用いられる郵便番号であることを示しています。
  • natural_feature は有名な地勢であることを示しています。(例:富士山)
  • airport は空港であることを示しています。
  • park は名づけられた公園であることを示しています。

上記以外にも追加的な住所要素が返されることがあります。

  • post_box は特定のPostal Boxの番号を示しています。Postal Boxは日本だと私書箱にあたります。
  • street_number は正確なストリート番号を示しています。
  • floor は建物の階層(1F,2Fなど)を表しています。
  • room は建物の部屋番号を表しています。

ステータスコード

status コードは次の値のうち1つを返します。

  • google.maps.GeocoderStatus.OK はジオコーディングが正常に行なわれたことを示しています。
  • google.maps.GeocoderStatus.ZERO_RESULTS はジオコーディングが正常に行なわれたが、結果がゼロだったことを示しています。
  • google.maps.GeocoderStatus.OVER_QUERY_LIMIT は使用制限回数の上限を超えたことを示しています。
  • google.maps.GeocoderStatus.REQUEST_DENIED は、リクエストが何らかの理由により許可されなかったことを示しています。
  • google.maps.GeocoderStatus.INVALID_REQUEST は一般的に、クエリ (address or latLng)が不足していることを示しています。

次の例では、住所を緯度経度に変換してマーカーを配置しています。

  var geocoder;
 
var map;
 
function initialize() {
    geocoder
= new google.maps.Geocoder();
   
var latlng = new google.maps.LatLng(-34.397, 150.644);
   
var myOptions = {
      zoom
: 8,
      center
: latlng,
      mapTypeId
: google.maps.MapTypeId.ROADMAP
   
}
    map
= new google.maps.Map(document.getElementById("map_canvas"), myOptions);
 
}

 
function codeAddress() {
   
var address = document.getElementById("address").value;
   
if (geocoder) {
      geocoder
.geocode( { 'address': address}, function(results, status) {
       
if (status == google.maps.GeocoderStatus.OK) {
          map
.setCenter(results[0].geometry.location);
         
var marker = new google.maps.Marker({
              map
: map,
              position
: results[0].geometry.location
         
});
       
} else {
          alert
("Geocode was not successful for the following reason: " + status);
       
}
     
});
   
}
 
}

<body onload="initialize()">
 
<div id="map_canvas" style="width: 320px; height: 480px;"></div>
 
<div>
   
<input id="address" type="textbox" value="Sydney, NSW">
   
<input type="button" value="Encode" onclick="codeAddress()">
 
</div>
</
body>

View example (geocoding-simple.html)

逆ジオコーディング (Address Lookup)

ジオコーディングは人間が読むことができる住所を地図上の位置に変換することを言います。その逆に地図上の位置から人間が読むことができる住所や地名に変換することを逆ジオコーディングといいます。

Geocoder は動的な逆ジオコーディングをサポートしています。addressの代わりにコンマで区切られた緯度/経度のペアをlatLngパラメータに設定します。

以下の例は緯度/経度を逆ジオコーディングして、地図の中心位置にセットします。そして情報ウィンドウに書式化された住所を表示します。

  var geocoder;
 
var map;
 
var infowindow = new google.maps.InfoWindow();
 
var marker;
 
function initialize() {
    geocoder
= new google.maps.Geocoder();
   
var latlng = new google.maps.LatLng(40.730885,-73.997383);
   
var myOptions = {
      zoom
: 8,
      center
: latlng,
      mapTypeId
: google.maps.MapTypeId.ROADMAP
   
}
    map
= new google.maps.Map(document.getElementById("map_canvas"), myOptions);
 
}

 
function codeLatLng() {
   
var input = document.getElementById("latlng").value;
   
var latlngStr = input.split(",",2);
   
var lat = latlngStr[0];
   
var lng = latlngStr[1];
   
var latlng = new google.maps.LatLng(lat, lng);
   
if (geocoder) {
      geocoder
.geocode({'latLng': latlng}, function(results, status) {
       
if (status == google.maps.GeocoderStatus.OK) {
         
if (results[1]) {
            map
.setZoom(11);
            marker
= new google.maps.Marker({
                position
: latlng,
                map
: map
           
});
            infowindow
.setContent(results[1].formatted_address);
            infowindow
.open(map, marker);
         
}
       
} else {
          alert
("Geocoder failed due to: " + status);
       
}
     
});
   
}
 
}

codeLatLng()の 『if (results[1]) {』に注目してください。逆ジオコーディングサーバーは1つめの結果(results[0])よりも、2つ目の結果に少ない情報を返します。逆ジオコーディングサーバーは大抵の場合、複数の結果を返します。郵便番号のみならず、その他の地理的な場所の名前も返します。

逆ジオコーダは政治的に定義された地理的地方(国, 地方, 街や地域), ストリートアドレス,そして郵便番号とマッチさせます。

先のクエリに対する住所の全てのリストは、以下のようになります。

results[0].formatted_address: "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
results
[1].formatted_address: "Williamsburg, NY, USA",
results
[2].formatted_address: "New York 11211, USA",
results
[3].formatted_address: "Kings, New York, USA",
results
[4].formatted_address: "Brooklyn, New York, USA",
results
[5].formatted_address: "New York, New York, USA",
results
[6].formatted_address: "New York, USA",
results
[7].formatted_address: "United States"

住所は小さい範囲でマッチしたもの順で返されます。通常、もっとも正確な住所はresult[0]になるでしょう。サーバーはもっとも小さくマッチした住所から異なるタイプの住所を返します(地域、町、都市、州など)。もし一般的な住所を取得したいときは、 results[].types を調べてください。

注: 逆ジオコーディングは科学的技術に基づいていません。ジオコーダは許容範囲内にもっとも近い住所があるか探すように試みます。

View example (geocoding-reverse.html)

ビューポートによるバイアス

ジオコーディングサービスに対してビューポートを渡すことで検索結果を「より好ましい結果」にすることができます。 GeocodeRequest の bounds パラメータに検索したいビューポートの範囲をセットします。

例えば、"Winnetka"のジオコーディング結果はシカゴ近郊になります。

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  }
}

しかしbounds パラメータにSan Fernando Valley of Los Angelesの範囲を定義すると、結果は "Winnetka" 近郊の位置になります。

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  }
}    

国識別コードによるバイアス

Google Maps API ジオコーディングサービスはリクエストが送信されたドメイン(国)に影響された結果を返します。例えば検索が"San Francisco"のとき、 もしリクエストが米国内からと、スペインからとでは結果がことなります。

これは region パラメータを使って、ジオコーディングサービスに特定の国だけの結果を返すように設定することもできます。このパラメータには ccTLD (国別コードトップレベルドメイン) の引数を指定します。大抵のccTLDコードはISO 3166-1 と同じですが、いくつかのコードは異なります。例えばグレートブリテンのccTLDは"uk"(.co.uk)ですが、ISO 3166-1 コードは "GB."です。

ジオコーディングのリクエストはGoogle Maps アプリケーションのドメインごとに設定することができます。

例えば、 "Toldeo"のこのジオコーディング結果はデフォルトドメインとしてアメリカにセットされています。

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }]
} 

region フィールドに 'es' (スペイン)をセットした場合はスペインの都市が返されます。

{
  "types":["locality","political"],
  "formatted_address":"Toledo, Espana",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"Espana",
    "short_name":"ES",
    "types":["country","political"]
  }]
}

ディレクション

DirectionsService オブジェクトを使うと、ディレクション(道案内)サービスを利用することができます。このオブジェクトはGoogle Maps API ディレクションサービスと通信し、リクエストを要求したり、計算された結果を受け取ることができます。その結果はあなた自身で描画する、またはDirectionsRenderer オブジェクトで直接地図に描画することができます。

ディレクションは起点や終着地点にテキスト(例:"Chicago, IL" or "Darwin, NSW, Australia")やLatLng の値を指定することができます。ディレクションサービスは複数のウェイポイントを使った複数のパートを返すことができます。ディレクションは地図上にルートの描画や <div> 要素の中に追加的な説明(例: "Turn right onto the Williamsburg Bridge ramp")を表示します。

ディレクションリクエスト

ディレクションサービスは非同期なので、Google Maps APIから外部サーバーを呼び出す必要があります。そのために、リクエストの実行時にコールバックを渡さなければなりません。このコールバックで結果を処理します。(注:ディレクションサービスは1つまたは複数の利用可能な旅程を  trips[]の配列で返します。)

V3でディレクションサービスを使うには、DirectionsService オブジェクトを作成し、DirectionsService.route() をコールして、DirectionsRequest オブジェクト定数によって条件とデータを処理するコールバックを、入力パラメータとして渡し、ディレクションサービスへリクエストします。

DirectionsRequest オブジェクト定数には以下のフィールドがあります。

{
  origin
: LatLng | String,
  destination
: LatLng | String,
  travelMode
: DirectionsTravelMode,
  unitSystem
: DirectionsUnitSystem,
  waypoints
[]: DirectionsWaypoint,
  provideTripAlternatives
: Boolean,
  region
: String
}

これらフィールドの説明は以下の通りです。

  • origin (必須) ディレクションの開始地点を指定します。 String (例: "Chicago, IL") または LatLng の値を指定できます。
  • destination (必須) ディレクションの終着地点を指定します。 String (例: "Chicago, IL") または LatLng の値を指定できます。
  • travelMode (必須) 移動方法について指定します。(値の指定は Travel Modes を参照)
  • unitSystem (オプション) は結果を表示する単位系について指定します。(値の指定は Unit Systems を参照)

  • waypoints[] (オプション) はDirectionsWaypointの配列を指定します。 ウェイポイントは、通過する地点を指定することでルートを部分的に修正を加えます。ウェイポイントは以下のフィールドを持つオブジェクト定数です。

    • location は LatLng または (ジオコーディングできる)String の形式で地点を指定します。
    • stopover はルートを中断するとき、trueにします。trueにすると、ルートは2つに分割されます。

    (その他のウェイポイントに関する情報は、 Using Waypoints in Trips を参照。)

  • provideTripAlternatives (オプション)  true を指定すると、ディレクションサービスはさらに別のルートを検索します。(注:この機能を利用すると、サーバーの応答時間は増加します)
  • region (オプション) 国識別コードを ccTLD ("top-level domain") の2文字を使って指定します。(詳しくは Region Biasing を参照)

DirectionsRequest のサンプルは次の通りです。

{
  origin
: "Chicago, IL",
  destination
: "Los Angeles, CA",
  waypoints
: [
   
{
      location
:"Joplin, MO",
      stopover
:false
   
},{
      location
:"Oklahoma City, OK",
      stopover
:true
   
}],
  provideTripAlternatives
: false,
  travelMode
: DirectionsTravelMode.DRIVING,
  unitSystem
: DirectionsUnitSystem.IMPERIAL
}

トラベルモード

ディレクションを計算するとき、移動の手段を指定する必要があります。現在は以下のトラベルモードの値を指定することができます。

  • DirectionsTravelMode.DRIVING 道路網を使った標準的なドライブを指定します。
  • DirectionsTravelMode.WALKING 緑道や歩道を使った、徒歩によるディレクションをリクエストします。(可能な限り)

注: 徒歩によるディレクションは、ときどき分かりやすい緑道を含むことができないことがあり、ディレクションは DirectionsResult の中に注意メッセージを含んで返すので、デフォルトのDirectionsRendererを使わないときは、あなたは必ずそれを表示しなければなりません。

単位系

デフォルトでは、ディレクションは基点の国の単位系を使用して表示します。例えば "Chicago, IL" から"Toronto, ONT"はマイルを使用して表示されます。逆のルートのときはキロメートルで表示されます。これをDirectionsUnitSystem の値を使って明確に指定することができます。

  • DirectionsUnitSystem.METRIC メートル法を使用します。距離はキロメートルで表示されます。
  • DirectionsUnitSystem.IMPERIAL 英単位系を使用します。距離はマイルで表示されます。

注: この単位系はユーザに表示するテキストにのみ影響します。ディレクションの結果にも含まれるdistanceの値は常に"マイル"です。

地域の指定によるバイアス

Google Maps APIディレクションサービスは、リクエストが送信されたドメイン(国)に影響された住所の結果を返します。例えばディレクションのクエリが "San Francisco" のとき、もし送信が米国内とスペインでは結果が異なります。

これは region パラメータを使って、ジオコーディングサービスに特定の国だけの結果を返すように設定することもできます。このパラメータには ccTLD (国別コードトップレベルドメイン) の引数を指定します。大抵のccTLDコードはISO 3166-1 と同じですが、いくつかのコードは異なります。例えばグレートブリテンのccTLDは"uk"(.co.uk)ですが、ISO 3166-1 コードは "GB."です。

Google Maps coverage spreadsheet を見ると、サービスがサポートされている国が分かります。


ディレクションの描画

ディレクションサービスの初期化には DirectionsService のroute() メソッドにサービスへのリクエスト結果を処理するコールバックを指定しなければなりません。コールバックには DirectionsResult と DirectionsStatus コードがレスポンスとして渡されます。

ディレクションクエリのステータス

DirectionsStatus は以下の値を返します。

  • OK   DirectionsResultには正常な結果が含まれています。
  • NOT_FOUND  少なくともリクエストに基点、終着地点、またはウェイポイントにジオコーディングできなかったポイントがあった。
  • ZERO_RESULTS  基点と終着地点の間にルートが見つからなかった.
  • MAX_WAYPOINTS_EXCEEDED   DirectionsRequest にDirectionsWaypointが与えられすぎた。最大のウェイポイント数は23 + 基点と終着地点です。
  • INVALID_REQUEST  DirectionsRequest が正しくない。
  • OVER_QUERY_LIMIT 許可されている一定期間にウェブページからのリクエストが多すぎる。
  • REQUEST_DENIED  リクエストが送信されたウェブページはディレクションサービスの利用が許可されていない.
  • UNKNOWN_ERROR  ディレクションサービスのサーバーで処理の途中にエラーが発生した。もう一度実行してみてください。

事前のリクエストが完全に処理されてから次のクエリをリクエストするようにしてください。

DirectionsResultによるディレクションの表示

DirectionsResult はディレクションクエリの結果を含んでいます。それをあなた自身で処理することもできますし、または DirectionsRenderer オブジェクトに渡すことで地図上に自動的に結果を表示することもできます。

TDirectionsResult を DirectionsRenderer で表示するには、次のような手順で行ないます。

  1. DirectionsRenderer オブジェクトを作成します。
  2. setMap() をコールし、レンダラを地図にバインドします。
  3. setDirections() をコールし、DirectionsResult を渡します。レンダラは MVCObjectなので関連づいたディレクションの結果が更新されても自動で判断して描画されます。

次のサンプルはルート66上の2点の道案内を計算します。基点と終着点はドロップダウンリストの "start" と"end" の値によって与えられます。DirectionsRenderer は示された2点間をポリラインで描画し、基点と終着点、ウェイポイントにマーカーを配置します。

var directionDisplay;
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 myOptions = {
    zoom
:7,
    mapTypeId
: google.maps.MapTypeId.ROADMAP,
    center
: chicago
 
}
  map
= new google.maps.Map(document.getElementById("map_canvas"), myOptions);
  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.DirectionsTravelMode.DRIVING
 
};
  directionsService
.route(request, function(result, status) {
   
if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay
.setDirections(result);
   
}
 
});
}

<div>
<b>Start: </b>
<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>
<b>End: </b>
<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>

View example (directions-simple.html)

DirectionsRenderer はポリラインと関連のあるマーカーを表示するだけでなく、ディレクションのステップをテキスト形式として表示することができます。DirectionsRenderernの setPanel() をコールして情報を表示させたい <div> 要素を渡してください。実行するとコピーライトの情報と結果に関する注意が表示されます。 

テキスト形式の道案内はブラウザ推奨の言語、またはAPIのロード時にlanguageパラメータを使って指定された言語に設定されます(さらに詳しくはLocalizationを参照。)

次のサンプルは上記のディレクションを <div> パネルに表示します。

var directionDisplay;
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 myOptions = {
    zoom
:7,
    mapTypeId
: google.maps.MapTypeId.ROADMAP,
    center
: chicago
 
}
  map
= new google.maps.Map(document.getElementById("map_canvas"), myOptions);
  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.DirectionsTravelMode.DRIVING
 
};
  directionsService
.route(request, function(response, status) {
   
if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay
.setDirections(response);
   
}
 
});
}

// select UI elements omitted
<div><div id="map_canvas" style="float:left;width:70%; height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height 100%"></div>  

View example (directions-panel.html)

Directions Results オブジェクト

DirectionsServiceサービスにリクエストを送ると、 ステータスコードと DirectionsResultオブジェクトを受け取ります。DirectionsResult はオブジェクト定数で、次のフィールドだけがあります。

  • trips[] は DirectionsTrip オブジェクトの配列です。 DirectionsRequestで与えたれた基点と終着点のそれぞれのルートのルートを取得することができます。通常は1つの道順だけが返されますが、リクエストの provideTripAlternatives フィールドに trueが設定されていると複数の結果が返ります。

DirectionsTripsについて

DirectionsTrip はa single result from the specified origin and destination. This trip may consist of one or more routes (of type DirectionsRoute) depending on whether any waypoints were specified. As well, the trip also contains copyright and warning information which must be displayed to the user in addition to the routing information.

The DirectionsTrip is an object literal with the following fields:

  • routes[] contains an array of DirectionsRoute objects, each of which contains information about a route from two locations within the given trip. A separate route will be present for each waypoint or destination specified. (A trip with no waypoints will contain exactly one DirectionsRoute.) Each route consists of a series of DirectionSteps.
  • copyrights contains the copyrights text to be displayed for this trip. If you do not use the provided DirectionsRenderer object, you must handle and display this information yourself.
  • warnings[] contains an array of warnings to be displayed when showing these directions. If you do not use the provided DirectionsRenderer object, you must handle and display these warnings yourself.

Directions Routes

DirectionsRoute defines a single leg of a journey from the origin to the destination in the calculated route. For trips that contain no waypoints, the trip will consist of a single "route," but for trips that define one or more waypoints, the trip will consist of one or more routes, corresponding to the specific leg of the journey.

The DirectionsRoute is an object literal with the following fields:

  • steps[] contains an array of DirectionsStep objects denoting information about each separate step of the route.
  • distance indicates the total distance covered by this route, as a DirectionsDistance object of the following form:

    • value indicates the distance in meters
    • text contains a string representation of the distance, which by default is displayed in units as used at the origin. (For example, miles will be used for any origin within the United States.) You may override this unit system by specifically setting a DirectionsUnitSystem in the original query. Note that regardless of what unit system you use, the distance.value field always contains a value expressed in meters.

    These fields may be undefined if the distance is unknown.

  • duration indicates the total duration of this route, as a DirectionsDuration object of the following form:

    • value indicates the duration in seconds.
    • text contains a string representation of the duration.

    These fields may be undefined if the duration is unknown.

  • start_geocode contains a GeocoderResponse denoting the precise geocode of the given origin. Because the DirectionsService calculates directions between locations by using the nearest transportation option (usually a road) at the start and end points, start_geocode indicates the actual geocoded origin, which may be different than the first step if, for example, the road is not near the origin.
  • end_geocode contains a GeocoderResponse denoting the precise geocode of the given destination. Because the DirectionsService calculates directions between locations by using the nearest transportation option (usually a road) at the start and end points, end_geocode indicates the actual geocoded destination, which may be different than the last step if, for example, the road is not near the destination.

Directions Steps

DirectionsStep is the most atomic unit of a direction's trip, containing a single step describing a specific, single instruction on the journey. E.g. "Turn left at W. 4th St." The step not only describes the instruction but also contains distance and duration information relating to how this step relates to the following step. For example, a step denoted as "Merge onto I-80 West" may contain a duration of "37 miles" and "40 minutes," indicating that the next step is 37 miles/40 minutes from this step.

The DirectionsStep is an object literal with the following fields:

  • instructions contains instructions for this step within a text string.
  • distance contains the distance covered by this step until the next step, as a DirectionsDistance object. (See the description in DirectionsRoute above.) This field may be undefined if the distance is unknown.
  • duration contains the typical time required to perform the step, until the next step, as a DirectionsDuration object. (See the description inDirectionsRoute above.) This field may be undefined if the duration is unknown.
  • start_point contains the LatLng of the starting point of this step.
  • end_point contains the LatLng of the ending point of this step.

Inspecting DirectionsResults

The DirectionsResults components ? DirectionsTripDirectionsRoute and DirectionsStep ? may be inspected and used when parsing any directions response.

The following example plots walking directions to certain tourist attractions in New York City. We inspect the route's DirectionsStep to add markers for each step, and attach information to an InfoWindow with instructional text for that step.

Note: since we are calculating walking directions, we also display any warnings to the user in a separate <div> panel.

var map;
var directionDisplay;
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 myOptions = {
    zoom
: 13,
    mapTypeId
: google.maps.MapTypeId.ROADMAP,
    center
: manhattan
 
}
  map
= new google.maps.Map(document.getElementById("map_canvas"), myOptions);
   
 
// 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.DirectionsTravelMode.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.trips[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.trips[0].routes[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);
 
});
}

<div>
<b>Start: </b>
<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>
<b>End: </
b>
<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>

View example (directions-complex.html)

Using Waypoints in Trips

As noted within the DirectionsRequest, you may also specify waypoints (of type DirectionsWaypoint) when calculating trips using the Directions service. Waypoints allow you to calculate trips through additional locations, in which case the returned trip passes through the given waypoints in their provided order.

The following example calculates cross-country trips across the United States using a variety of start points, end points, and waypoints. (To select multiple waypoints, press Ctrl-Click when selecting items within the list.) Note that we inspect the routes.start_geocode.formatted_address androutes.end_geocode.formatted_address to provide us with the text for each route's start and end point.

var directionDisplay;
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 myOptions = {
    zoom
: 6,
    mapTypeId
: google.maps.MapTypeId.ROADMAP,
    center
: chicago
 
}
  map
= new google.maps.Map(document.getElementById("map_canvas"), myOptions);
  directionsDisplay
.setMap(map);
}
 
function calcRoute() {
 
var start = document.getElementById("start").value;
 
var end = document.getElementById("end").value;
 
var waypts = [];
 
var checkboxArray = document.getElementById("waypoints");
 
for (var i = 0; i < checkboxArray.length; i++) {
   
if (checkboxArray.options[i].selected == true) {
      waypts
.push({location:checkboxArray[i].value});
   
}
 
}

 
var request = {
      origin
: start,
      destination
: end,
      waypoints
: waypts,
      travelMode
: google.maps.DirectionsTravelMode.DRIVING
 
};
  directionsService
.route(request, function(response, status) {
   
if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay
.setDirections(response);
     
var trip = response.trips[0];
     
var summaryPanel = document.getElementById("directions_panel");
      summaryPanel
.innerHTML = "";
     
// For each route, display summary information.
     
for (var i = 0; i < trip.routes.length; i++) {
       
var tripSegment = i+1;
        summaryPanel
.innerHTML += "<b>Trip Segment: " + tripSegment + "</b><br />";
        summaryPanel
.innerHTML += trip.routes[i].start_geocode.formatted_address + " to ";
        summaryPanel
.innerHTML += trip.routes[i].end_geocode.formatted_address + "<br />";
        summaryPanel
.innerHTML += trip.routes[i].distance.text + "<br /><br />";
     
}
   
}
 
});
}

View example (directions-waypoints.html)