サービス

サービスの概要

Google Maps API は新しい機能の追加によって定期的に拡張されています。多くの場合、こうした機能は、maps.google.com で最初にリリースされます。このセクションでは、これらのサービスについて説明します。注: 「サービス」の定義は難しいため、このセクションはやや包括的な内容となっています。基本的に、このセクションには、他の場所に掲載できなかった簡潔な事項がまとめられています。

XML とデータ解析

Google Maps API は、最新バージョンの Internet Explorer、Firefox、Safari で動作するブラウザに依存しない XmlHttpRequest() オブジェクトを作成するためのファクトリ メソッドをエクスポートします。すべての XmlHttpRequest と同様に、取得されたファイルはローカル ドメイン上にある必要があります。次の例では、myfile.txt という名前のファイルをダウンロードし、その内容を JavaScript alert() で表示します。

var request = GXmlHttp.create();
request.open("GET", "myfile.txt", true);
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    alert(request.responseText);
  }
}
request.send(null);

また、API は、XmlHttpRequest() readyState のチェックを不要にする一般的な HTTP GET リクエスト用の、より単純な GDownloadUrl() メソッドもエクスポートします。上記の例は、GDownloadUrl() を使用して次のように書き換えることができます。

GDownloadUrl("myfile.txt", function(data, responseCode) {
  alert(data);
});

静的メソッド GXml.parse() で XML ドキュメントを解析できます。このメソッドは、XML の文字列を唯一の引数として受け取ります。このメソッドは、最新のブラウザのほとんどと互換性がありますが、ブラウザが XML 解析をネイティブにサポートしていない場合は例外が発生します。

次の例では、GDownloadUrl メソッドを使用して、緯度と経度の座標のリストを含む静的な XML ファイル ("data.xml") をダウンロードします。ダウンロードが完了したら、GXml を使用して XML を解析し、XML ドキュメント内の各地点にマーカーを作成します。

var map = new GMap2(document.getElementById("map_canvas"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

// Download the data in data.xml and load it on the map. The format we
// expect is:
// <markers>
//   <marker lat="37.441" lng="-122.141"/>
//   <marker lat="37.322" lng="-121.213"/>
// </markers>
GDownloadUrl("data.xml", function(data, responseCode) {
  var xml = GXml.parse(data);
  var markers = xml.documentElement.getElementsByTagName("marker");
  for (var i = 0; i < markers.length; i++) {
    var point = new GLatLng(parseFloat(markers[i].getAttribute("lat")),
                            parseFloat(markers[i].getAttribute("lng")));
    map.addOverlay(new GMarker(point));
  }
});

例を表示 (xhr-requests.html)。この例では、外部 XML データ ファイル data.xml を使用しています。

詳細については、「GXmlHttp」と「GXml」のクラス リファレンスを参照してください。

ジオコーディング

ジオコーディングとは、住所 (「1600 Amphitheatre Parkway, Mountain View, CA」など) を地理座標 (緯度 37.423021、経度 -122.083739 など) に変換する処理のことです。地理座標を使用して、マーカーを配置したり地図の位置決めを行うことができます。Google Maps API は、直接 HTTP リクエストを経由するか、GClientGeocoder オブジェクトを使用して、アクセスできるジオコーディング サービスを備えています。

ジオコーディングは時間とリソースを消費するタスクです。住所はできるだけ事前に (HTTP ジオコーダまたはその他のジオコーディング サービスを使用して) ジオコードし、ジオコード キャッシュ を使用して結果を格納しておいてください。

ジオコーディング オブジェクト

Google Maps API ジオコーディング サービスには、GClientGeocoder オブジェクト経由でアクセスできます。GClientGeocoder.getLatLng() を使用して、文字列の住所を GLatLng に変換します。このメソッドでは、変換する文字列の住所と、住所取得時に実行するコールバック関数をパラメータと見なします。ジオコーディングでは、リクエストを Google のサーバーに送信する必要があり、少し時間がかかるため、コールバック関数が必要となります。

次の例では、住所をジオコードし、その地点にマーカーを追加し、この住所を表示する情報ウィンドウを開きます。コールバックは、関数リテラルとして渡されている点にご注意ください。

var map = new GMap2(document.getElementById("map_canvas"));
var geocoder = new GClientGeocoder();

function showAddress(address) {
  geocoder.getLatLng(
    address,
    function(point) {
      if (!point) {
        alert(address + " not found");
      } else {
        map.setCenter(point, 13);
        var marker = new GMarker(point);
        map.addOverlay(marker);
        marker.openInfoWindowHtml(address);
      }
    }
  );
}

例を表示 (geocoding-simple.html)

GClientGeocoder.setViewport() メソッドを通じて、指定されたビューポート内 (タイプ GLatLngBounds の境界ボックスとして表現) の結果を優先するように、Maps API ジオコーダを変更することもできます。GClientGeocoder.setBaseCountryCode() メソッドを使用すると、特定のドメイン (国) に合わせた結果を返すことができます。ジオコーディング リクエストは、Google マップのメイン アプリケーションでジオコーディングが提供されている、すべてのドメインに対して送信できます。たとえば、「トレド」を検索した場合、国コード「es」で指定されたスペインのドメイン (http://maps.google.es) 内では、米国内のデフォルトのドメイン (http://maps.google.com) とは異なった結果が返されます。

構造化された住所を抽出

住所に関する構造化された情報にアクセスするために、GClientGeocoder には次の情報で構成される JSON オブジェクトを返す getLocations() メソッドも用意されています。

• Status
• • request -- リクエストの種類。この場合は常に geocode です。
  • code -- ジオコード リクエストが成功したかどうかを示す応答コード (HTTP ステータス コードと類似)。「full list of status codes」を参照してください。
• Placemark -- ジオコーダで複数の一致対象が見つかった場合は、複数の位置マークが返されることがあります。
• • address -- 適切な形式で表記された住所。
  • AddressDetails -- 住所の表記形式の国際標準である xAL (eXtensible Address Language) に基づいて表記された住所。
  • • Accuracy -- 指定された住所をジオコードした際の精度を示す属性。「list of possible values」を参照してください。
  • Point -- 3D 空間における地点。
  • • coordinates -- 住所の経度、緯度、高度。この場合、高度は常に 0 に設定されます。

ここでは、ジオコーダから返された Google 本社の住所の JSON オブジェクトを示します。

{
  "name": "1600 Amphitheatre Parkway, Mountain View, CA, USA",
  "Status": {
    "code": 200,
    "request": "geocode"
  },
  "Placemark": [
    {
      "address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "AddressDetails": {
        "Country": {
          "CountryNameCode": "US",
          "AdministrativeArea": {
            "AdministrativeAreaName": "CA",
            "SubAdministrativeArea": {
              "SubAdministrativeAreaName": "Santa Clara",
              "Locality": {
                "LocalityName": "Mountain View",
                "Thoroughfare": {
                  "ThoroughfareName": "1600 Amphitheatre Pkwy"
                },
                "PostalCode": {
                  "PostalCodeNumber": "94043"
                }
              }
            }
          }
        },
        "Accuracy": 8
      },
      "Point": {
        "coordinates": [-122.083739, 37.423021, 0]
      }
    }
  ]
}

この例では、getLocations() メソッドを使用して住所をジオコードし、適切な形式で表記された住所と 2 文字の国コードを JSON から抽出して、情報ウィンドウに表示します。

var map;
var geocoder;

function addAddressToMap(response) {
  map.clearOverlays();
  if (!response || response.Status.code != 200) {
    alert("\"" + address + "\" not found");
  } else {
    place = response.Placemark[0];
    point = new GLatLng(place.Point.coordinates[1],
                        place.Point.coordinates[0]);
    marker = new GMarker(point);
    map.addOverlay(marker);
    marker.openInfoWindowHtml(place.address + '<br>' + 
      '<b>Country code:</b> ' + place.AddressDetails.Country.CountryNameCode);
  }
}

例を表示 (geocoding-extraction)

逆ジオコーディング

「ジオコーディング」という語は、一般的に人が読み取れる住所の地図上のポイントへの変換を表します。ポイントを人が読み取れる住所に変換するプロセスを「逆ジオコーディング」と呼びます。

GClientGeocoder.getLocations() メソッドは、標準ジオコーディングと逆ジオコーディングの両方をサポートします。このメソッドを String アドレスの代わりに GLatLng オブジェクトに渡す場合、ジオコーダは逆検索を実行し、最も近いアドレス可能な場所の構造化 JSON オブジェクトを返します。入力した GLatLng がアドレス可能な場所に正確に一致しない場合、最も近いアドレス可能な場所は、クエリの元の緯度値と経度値からはある程度離れていることがあります。

注: 逆ジオコーディングは科学的に正確ではありません。ジオコーダは、一定の許容範囲内で最も近いアドレス可能な場所を探そうとします。一致するものがない場合、ジオコーダは通常、G_GEO_UNKNOWN_ADDRESS (602) ステータス コードを返します。

var map;
var geocoder;
var address;

function initialize() {
  map = new GMap2(document.getElementById("map_canvas"));
  map.setCenter(new GLatLng(40.730885,-73.997383), 15);
  map.addControl(new GLargeMapControl);
  GEvent.addListener(map, "click", getAddress);
  geocoder = new GClientGeocoder();
}

function getAddress(overlay, latlng) {
  if (latlng != null) {
    address = latlng;
    geocoder.getLocations(latlng, showAddress);
  }
}

function showAddress(response) {
  map.clearOverlays();
  if (!response || response.Status.code != 200) {
    alert("Status Code:" + response.Status.code);
  } else {
    place = response.Placemark[0];
    point = new GLatLng(place.Point.coordinates[1],place.Point.coordinates[0]);
    marker = new GMarker(point);
    map.addOverlay(marker);
    marker.openInfoWindowHtml(
        '<b>orig latlng:</b>' + response.name + '<br/>' + 
        '<b>latlng:</b>' + place.Point.coordinates[0] + "," + place.Point.coordinates[1] + '<br>' +
        '<b>Status Code:</b>' + response.Status.code + '<br>' +
        '<b>Status Request:</b>' + response.Status.request + '<br>' +
        '<b>Address:</b>' + place.address + '<br>' +
        '<b>Accuracy:</b>' + place.AddressDetails.Accuracy + '<br>' +
        '<b>Country code:</b> ' + place.AddressDetails.Country.CountryNameCode);
  }
}

例を表示 (geocoding-reverse.html)

ジオコーディングのキャッシュ

GClientGeocoder には、デフォルトでクライアント側キャッシュが組み込まれています。キャッシュにはジオコーダの応答が格納され、住所が再びジオコードされた場合に応答にかかる時間を短縮できます。GClientGeocoder オブジェクトの setCache() メソッドに null を渡すことで、キャッシュをオフにできます。ただし、パフォーマンスの向上のため、キャッシュはオンのままにすることをお勧めします。GClientGeocoder で使用されているキャッシュを変更するには、setCache() を呼び出して新しいキャッシュを渡します。現在のキャッシュの内容を空にするには、ジオコーダに対して、または直接キャッシュに対して reset() メソッドを呼び出します。

デベロッパーは、独自のクライアント側キャッシュを構築することをお勧めします。次の例では、ジオコーディング API の対象となっている国の 6 つの首都について、ジオコーダによる事前に計算された応答を含むキャッシュを構築します。まず、ジオコードの応答の配列を構築します。次に、標準の GeocodeCache を拡張したカスタム キャッシュを作成します。キャッシュを定義したら、setCache() メソッドを呼び出します。キャッシュに格納されるオブジェクトは厳しくチェックされないため、その他の情報 (人口など) の情報もキャッシュに格納できます。

// Builds an array of geocode responses for the 6 capitals
var city = [
  {
    name: "Washington, DC",
    Status: {
      code: 200,
      request: "geocode"
    },
    Placemark: [
      {
        address: "Washington, DC, USA",
        population: "0.563M",
        AddressDetails: {
          Country: {
            CountryNameCode: "US",
            AdministrativeArea: {
              AdministrativeAreaName: "DC",
              Locality: {
                LocalityName: "Washington"
              }
            }
          },
          Accuracy: 4          
        },
        Point: {
          coordinates: [-77.036667, 38.895000, 0]
        }
      }
    ]
  },
  ... // etc., and so on for other cities
];

  var map;
  var geocoder;

  // CapitalCitiesCache is a custom cache that extends the standard GeocodeCache.
  // We call apply(this) to invoke the parent's class constructor.
  function CapitalCitiesCache() {
    GGeocodeCache.apply(this);
  }

  // Assigns an instance of the parent class as a prototype of the
  // child class, to make sure that all methods defined on the parent
  // class can be directly invoked on the child class.
  CapitalCitiesCache.prototype = new GGeocodeCache();

  // Override the reset method to populate the empty cache with
  // information from our array of geocode responses for capitals.
  CapitalCitiesCache.prototype.reset = function() {
    GGeocodeCache.prototype.reset.call(this);
    for (var i in city) {
      this.put(city[i].name, city[i]);
    }
  }

  map = new GMap2(document.getElementById("map_canvas"));
  map.setCenter(new GLatLng(37.441944, -122.141944), 6);

  // Here we set the cache to use the UsCitiesCache custom cache.
  geocoder = new GClientGeocoder();
  geocoder.setCache(new CapitalCitiesCache());

例を表示 (geocoding-cache.html)

HTTP リクエスト経由のジオコーディング

サーバー側のスクリプトを直接使用して、Maps API ジオコーダにもアクセスできます。このメソッドは、クライアント側のジオコーダを使用しているときにはお勧めしません。ただし、デバッグ目的または JavaScript GClientGeocoder オブジェクトが利用できない場合には有効です。

Maps API ジオコーダにアクセスするには、http://maps.google.com/maps/geo? に次のパラメータを持つ URI でリクエストを送信します。

• q（必須） - ジオコーディングする住所。
• key（必須） - API キー。
• sensor（必須） - ジオコーディング リクエストが、場所センサーでデバイスから取得したものかどうかを示します。この値は、true か false のいずれかです。
• output（必須） - 生成される出力の形式。xml、kml、csv、json（デフォルト）を指定できます。
• ll（省略可） - ビューポートの中心の {緯度,経度} は、カンマ区切りの文字列（例、「ll=40.479581,-117.773438」）で表されます。spn パラメータもジオコーダに渡される場合のみ、このパラメータには意味があります。
• spn（省略可） - ビューポートの「範囲」は、{緯度,経度} というカンマ区切りの文字列（例、「spn=11.1873,22.5」）で表されます。ll パラメータもジオコーダに渡される場合のみ、このパラメータには意味があります。
• gl（省略可） - ccTLD（「トップレベル ドメイン」）の 2 文字の値として指定される国コード。

注: gl と spn,ll のビューポート パラメータは、完全には制限されず、ジオコーダからの結果に対してのみ、影響を与えます。

この例では、Google 本社の地理座標をリクエストします。

http://maps.google.com/maps/geo?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA&output=xml&sensor=true_or_false&key=abcdefg

変数 true_or_false として、この例で sensor パラメータを残し、この値を true か false に明示的に設定する必要があることを強調します。

出力に json を指定した場合、応答は JSON オブジェクト形式になります。xml または kml を指定した場合、応答は KML 形式で返されます。XML 出力と KML 出力は、MIME の種類を除いて同じです。

たとえば、ジオコーダで「1600 amphitheatre mountain view ca」に対して返される応答は次のようになります。

<kml xmlns="http://earth.google.com/kml/2.0">
  <Response>
    <name>1600 amphitheatre mountain view ca</name>
    <Status>
      <code>200</code>
      <request>geocode</request>
    </Status>
    <Placemark>
      <address> 
        1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA
      </address>
      <AddressDetails Accuracy="8">
        <Country>
          <CountryNameCode>US</CountryNameCode>
 	  <AdministrativeArea>
            <AdministrativeAreaName>CA</AdministrativeAreaName>
           <SubAdministrativeArea>
             <SubAdministrativeAreaName>Santa Clara</SubAdministrativeAreaName>
             <Locality>
               <LocalityName>Mountain View</LocalityName>
    	       <Thoroughfare>
                 <ThoroughfareName>1600 Amphitheatre Pkwy</ThoroughfareName>
               </Thoroughfare>
               <PostalCode>
                 <PostalCodeNumber>94043</PostalCodeNumber>
               </PostalCode>
             </Locality>
           </SubAdministrativeArea>
         </AdministrativeArea>
       </Country>
     </AddressDetails>
     <Point>
       <coordinates>-122.083739,37.423021,0</coordinates>
     </Point>
   </Placemark>
  </Response>
</kml>

複数の結果や整った形式などの特別な機能は不要で、解析しやすい短い応答を希望する場合は、csv 出力もできます。csv 形式で返される応答は、カンマで区切られた 4 つの数字で構成されます。

1. HTTP ステータス コード
2. 精度（「GGeoAddressAccuracy」を参照）
3. 緯度
4. 経度

次の例では、精度が上がっていく順番で、「State St, Troy, NY」、「2nd st & State St, Troy, NY」、「7 State St, Troy, NY」という 3 つのアドレスの応答を示しています。

200,6,42.730070,-73.690570
200,7,42.730210,-73.691800
200,8,42.730287,-73.692511

ストリートビュー オブジェクトの使い方

Street View Panorama オブジェクトを使用するには、クライアントのブラウザが Flash プラグインに対応している必要があります。

Google ストリートビューでは、Google マップのカバー エリア全範囲にわたって指定された道路から、360 度のパノラマ表示ができます。サンプルのストリートビュー画像を以下に示します。

Google ストリートビューでは、ほとんどのブラウザが対応している Flash® プラグインを使用して、これらの対話型の画像を表示します。Google Maps API は、Google マップ ストリートビューで使用される画像を入手して操作するためのストリートビュー サービスを実現します。

GStreetviewPanorama オブジェクト

ストリートビュー画像は、GStreetviewPanorama オブジェクトを使用することでサポートされます。このオブジェクトがストリートビュー Flash® ビューアへの API インターフェースとなります。ストリートビューを Maps API アプリケーションに組み込むには、次の簡単な手順に従う必要があります。

1. コンテナ（通常は <div> 要素）を作成して、ストリートビュー Flash® ビューアを保持します。
2. GStreetviewPanorama オブジェクトを作成して、コンテナ内に配置します。
3. 特定の場所を参照して、最初の「Point of View」（POV）を表示するように、ストリートビューのオブジェクトを初期化します。
4. 603 エラー値を確認してサポートされていないブラウザに対処します。

GStreetviewPanorama オブジェクトは、コンストラクタ内のコンテナ要素を要求します。また、このオブジェクトの GStreetviewPanoramaOptions パラメータを使用することでその場所を設定することもできます（省略可）。構築後にオブジェクトに setLocationAndPOV() を呼び出して、その場所と POV を変更できます。

コンテナと、場所および POV の設定の詳細は、以下に説明します。

ストリートビューのコンテナ

ストリートビュー Flash ビューアでは、コンテンツ（ほとんどは <div> 要素）を表示する親 DOM ノードが必要です。パノラマ画像を適切に表示するために、200×200 ピクセル以上をお勧めします。また、大きなビューアを使用すると、Flash ビューアがメモリを消費しすぎる原因となり、ブラウザのパフォーマンスに悪影響を与える可能性があるため、お勧めしません。

GStreetviewPanorama コンストラクタは、ストリートビュー Flash ビューアを表示する初期コンテナ要素を特定するために container パラメータを要求します。GStreetviewPanorama オブジェクトを hide() にして、一時的にその表示を無効にすることも、show() にしてビューアの表示を再び有効にすることもできます。

ストリートビュー Flash ビューアのコンテナを変更する場合は、コンテナに setContainer() メソッドを送信し、コンテナに添付する新しい要素を渡してください。コンテナのサイズを変更する場合、GStreetviewPanorama メソッドを checkResize() オブジェクトに送信して、新しい寸法に合うように強制的にサイズを変更させることができます。

DOM からストリートビュー Flash ビューアを完全に削除して、そのメモリを解放するには、オブジェクトに remove() メソッドを渡します。DOM からコンテナ要素を削除する場合はこのメソッドを呼び出す必要があります。そうしないと、クライアントのブラウザでメモリ リークが発生してしまいます。

ストリートビューの場所

ストリートビューの画像は、場所（GLatLng 対応）と特定の方向（GPov）の両方で構成されます。これらにより、画像表示のビューが決定されます。これらのパラメータは両方とも、ストリートビューのオブジェクトの構築時に、オプションの GStreetviewPanoramaOptions パラメータを使用して指定できます。

ストリートビューが現在サポートされている市町村のリストは、 Google マップ ヘルプ センターでご覧ください。場所がストリートビューのデータをサポートしているかどうかは、次の 3 通りの基本的な方法で判断できます。

• 確認済みストリートビューの場所の GLatLng を保存できます。
• GStreetviewOverlay タイル オーバーレイを調べて、道路ネットワークを視覚的に調べることができます。ストリートビューに対応している道路は、オーバーレイ上で青色にハイライト表示されます。次に、クリック イベントまたはジオコーディング ロジックを使用してサポートされている場所を GStreetviewPanorama オブジェクトに渡します。（「ストリートビュー オーバーレイ」を参照してください）。
• GStreetviewClient オブジェクトを使用して、GLatLng を渡した指定のストリートビュー オブジェクトに対するクエリを実行できます。GStreetviewClient オブジェクトは、パノラマ データを検索する多数のクエリをサポートしています。（「ストリートビュー クライアントのクエリ」を参照してください）。

後者の 2 つのメソッドは、不正確なのでご注意ください。ストリートビュー サービスは、これらのメソッドを使用する場合、正確な緯度と経度を要求せず（またそれらを一般的には取得せず）、指定された GLatLng の「近く」のパノラマ データの存在を検索します。

次のサンプルでは、GStreetviewPanoramaOptions を使用して、ストリートビューで使用する最初の緯度と経度を指定します。POV は、デフォルトの、北方向へのビューを示す空白のままです。

var fenwayPark = new GLatLng(42.345573,-71.098326);
panoramaOptions = { latlng:fenwayPark };
var myPano = new GStreetviewPanorama(document.getElementById("pano"), panoramaOptions);

例を表示 (streetview-simple.html)

ストリートビューのエラー処理

ストリートビューは Flash® プラグインを必要とするため、コードについては、ユーザーのブラウザ内でプラグインが使用できるかどうかを確認する必要があります。これは、error オブジェクト上の GStreetviewPanorama イベントに対してイベント リスナを登録することによって、アプリケーション内で実行できます。error イベントは、評価できる エラー コードを渡します。

以下のサンプル コードは、Flash プラグインのサポートについてのクイック チェックを実行し、Flash がサポートされていない場合は警告のダイアログ ボックスを表示します。

var fenwayPark = new GLatLng(42.345573,-71.098326);
panoramaOptions = { latlng:fenwayPark };
myPano = new GStreetviewPanorama(document.getElementById("pano"), panoramaOptions);
GEvent.addListener(myPano, "error", handleNoFlash);
    
function handleNoFlash(errorCode) {
  if (errorCode == 603) {
    alert("Error: Flash doesn't appear to be supported by your browser");
    return;
  }
}  

ストリートビューの Points of View（POV）

ストリートビューの場所では、画像に対するカメラの中心位置が定義されますが、カメラとその画像との同調性は定義されません。そのため、GPov オブジェクト リテラルでは、次の 3 つのプロパティを定義します。

• yaw は、カメラの中心回りの回転角を、真北からの相対的な角度で定義します。ヨー角は、時計回りに測定されます (90 度が真東)。
• pitch は、カメラの初期デフォルト ピッチから「上」または「下」の角度の差を定義します。これはしばしば (必ずというわけではない) 水平平面となることがあります(たとえば、丘の上で撮影された画像は、水平ではないデフォルトのピッチを示す場合があります)。ピッチ角は、上を向くときは (-90 度真上で、デフォルト ピッチに対して直角) 負の値、および下を向くときは (+90 度真下で、デフォルト ピッチに対して直角) 正の値で測定されます。
• zoom は、このビューのズーム レベルを定義します (「視野」を効率的に制限)。最大のズーム アウト値は 0 です。ストリートビューの場所ごとに、ズーム レベルが高くなることもあれば低くなることもあります。

デフォルトでは、これらの値はすべて 0 で、最大の視野で真北の水平平面ビューが定義されます。

パノラマ ビューの設定

前述のとおり、GPov パラメータを使用して、パノラマ オブジェクト用の場所と GStreetviewPanoramaOptions の両方を、構築時に設定できます。

fenwayPark = new GLatLng(42.345573,-71.098326);
myPOV = {yaw:370.64659986187695,pitch:-20};
svOpts = {latlng:fenwayPark, pov:myPOV};
var myPano = new GStreetviewPanorama(document.getElementById("pano"), svOpts);

また、setLocationAndPOV() オブジェクトを構築した後、GStreetviewPanorama メソッドを使用して場所と POV の両方を設定することもできます。次の例では、GStreetviewPanorama オブジェクトを作成して、その場所と POV を特定の値に設定します。

var myPano = new GStreetviewPanorama(document.getElementById("pano"));
fenwayPark = new GLatLng(42.345573,-71.098326);
myPOV = {yaw:370.64659986187695,pitch:-20};
myPano.setLocationAndPOV(fenwayPark, myPOV);

例を表示 (streetview-object.html)

ストリートビュー オーバーレイの使い方

道路がストリートビューに対応しているかどうかを確認する最も簡単な方法は、GStreetviewOverlay オブジェクトを使用することです。このタイプのオーバーレイを作成し、地図に追加するだけで、ストリートビューのデータを含む道路は、地図上に青い輪郭線を使用してハイライト表示されます。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
svOverlay = new GStreetviewOverlay();
map.addOverlay(svOverlay);

例を表示 (streetview-layer.html)

地理的な領域がストリートビューをサポートしていることがわかったら、GStreetviewPanorama オブジェクトを挿入することで、有効なストリートビューの道路上でのクリックに対応したロジックを追加できます。

var myPano = new GStreetviewPanorama(document.getElementById("pano"));
var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(42.345573,-71.098326), 14);
svOverlay = new GStreetviewOverlay();
map.addOverlay(svOverlay);
GEvent.addListener(map,"click", function(overlay,latlng) {
  myPano.setLocationAndPOV(latlng);
});

例を表示 (streetview-click.html)

特定の場所がストリートビューをサポートしていることを確認したら、その場所情報と POV を保存して、それらをオブジェクト自体に配置できます。

ストリートビュー クライアントのクエリ

GStreetviewOverlay の視覚的な検査によって道路がストリートビューをサポートしているかどうかを決定することは、実際には不可能なことも多く、ユーザーの視野に頼るため確実ではありません。そのため、API には、ストリートビューのデータをプログラムでリクエストして取得するサービスが用意されています。このサービスは、GStreetviewClient オブジェクトを使用することで実行されます。

ストリートビュー検索の実行

GStreetviewClient オブジェクトは、Google のストリートビュー サービスを使用してパノラマ データの検索を実行します。この検索は非同期であるため、このクラスのメソッドはデータの受信時に実行するコールバック関数を要求します。値が返されない場合、指定されたコールバックはすべて null を渡すため、コールバック関数内で確認する必要があります。

GStreetviewClient メソッド getNearestPanoramaLatLng() は、指定された場所 (自身が GLatLng として渡された) 付近のパノラマ画像の GLatLng を取得します。

getNearestPanorama() と getPanoramaById() の両方が、代わりに GStreetviewData オブジェクトを取得します。これは特定のパノラマ オブジェクトに関するメタデータを保存します。そのデータについては、以下のセクションで説明します。

クライアント応答の処理

GStreetviewData オブジェクトの構造は、location、copyright (表示される特定の画像に関する情報を含む)、および links (隣接するパノラマ オブジェクトに関する情報を示す) の 3 つのプロパティで構成されます。これらのプロパティの構造について以下に説明します。

# The location property uses the GStreetviewLocation object literal
location: {
  latlng: GLatLng, 
  pov: { 
    yaw: String, 
    pitch: String, 
    zoom: String
  }, 
  description: String, 
  panoId: String
}

copyright: String

# The links property uses the GStreetviewLink object literal
links[]: {
  yaw: String, 
  description: String, 
  panoId: String
}

(GStreetviewLocation および GStreetviewLink オブジェクト リテラルの詳細な説明は、Maps API リファレンスに示します)。

注: GStreetviewData.location プロパティと window.location プロパティを、混同しないようにしてください。このオブジェクトの location プロパティからデータを抽出する場合は、ストリートビューのサーバーから実際に応答を受信していることを確認してください（下記参照）。そうでない場合、location プロパティで window.location がデフォルトとなり、予期しない動作が発生することになります。

GStreetviewClient オブジェクトに対するリクエストが正常終了すると、指定されたコールバック関数に GLatLng と GStreetviewData オブジェクトのいずれかが渡されます。ただし、ストリートビューのデータの取得は非同期であるため、クライアント オブジェクトでこれらのデータ オブジェクトを取得できないことがあります。これらが存在しているということを前提にコードを作成しないようにしてください。代わりに、応答が保証されている code 値を常に確認するようにしてください。以下のコード スニペットは、この概念を説明したものです。

panoClient = new GStreetviewClient();
panoClient.getPanoramaById(panoData.location.panoId, processReturnedData);
    
function processReturnedData(panoData) {
  if (panoData.code != 200) {
    GLog.write('showPanoData: Server rejected with code: ' + panoData.code);
    return;
  }
  
  // Code to actually process the GStreetviewData object is contained here
  
}  

サンプルの GStreetviewData 構造を含む全応答を以下に示します。

{
  location: {
    latlng: GLatLng("42.345566, -71.098354")
    pov: {
      yaw: "370.64659986187695"
      pitch: "-20"
      zoom: "1"
    }
    description: "Yawkey Way"
    panoId: "-KNGDaZvSQjMqug7ISM_CA"
  }
  copyright: "© 2008 Google"
  links:[ {
    yaw: "0"
    description: "Yawkey Way"
    panoId: "S142iWXa_4Fi7L7d8HKhuQ"
  },
  {
    yaw: "0"
    description: "Yawkey Way"
    panoId: "2vFI79AjOpHTAYJSCKquFg"
  }
  ]
}

以下のサンプル アプリケーションは、最初のパノラマ オブジェクトを表示し、その ID を抽出し、返された GStreetviewData オブジェクトでリンクされているパノラマ オブジェクトを保存します。その後、ストリートビュー オブジェクトに関連付けられているデータ セットを表示します。ユーザーが [次へ] をクリックするたびに、プロセスが繰り返され、ユーザーは一連の隣接するパノラマ オブジェクトを「ウォーク スルー」できます。

var map;
var myPano;   
var panoClient;
var nextPanoId;

function initialize() {
  var fenwayPark = new GLatLng(42.345573,-71.098326);
  var fenwayPOV = {yaw:370.64659986187695,pitch:-20};
      
  panoClient = new GStreetviewClient();      
   
  map = new GMap2(document.getElementById("map_canvas"));
  map.setCenter(fenwayPark, 15);
  GEvent.addListener(map, "click", function(overlay,latlng) {
    panoClient.getNearestPanorama(latlng, showPanoData);
  });
      
  myPano = new GStreetviewPanorama(document.getElementById("pano"));
  myPano.setLocationAndPOV(fenwayPark, fenwayPOV);
  GEvent.addListener(myPano, "error", handleNoFlash);  
  panoClient.getNearestPanorama(fenwayPark, showPanoData);
}
    
function showPanoData(panoData) {
  if (panoData.code != 200) {
    GLog.write('showPanoData: Server rejected with code: ' + panoData.code);
    return;
  }
  nextPanoId = panoData.links[[0[].panoId;
  var displayString = [[
    "Panorama ID: " + panoData.location.panoId,
    "LatLng: " + panoData.location.latlng,
    "Copyright: " + panoData.copyright,
    "Description: " + panoData.location.description,
    "Next Pano ID: " + panoData.links[[0[].panoId
  [].join("
");
  map.openInfoWindowHtml(panoData.location.latlng, displayString);
     
  GLog.write('Viewer moved to' + panoData.location.latlng);
  myPano.setLocationAndPOV(panoData.location.latlng);
}
    
function next() {
  // Get the next panoId
  // Note that this is not sophisticated. At the end of the block, it will get stuck
  panoClient.getPanoramaById(nextPanoId, showPanoData);
}
    
function handleNoFlash(errorCode) {
  if (errorCode == 603) {
    alert("Error: Flash doesn't appear to be supported by your browser");
    return;
  }
} 

例を表示 (streetview-data.html)

Google Earth プラグインの組み込み

Google Maps API では、デベロッパーが、Maps API アプリケーション内の Google Earth のインスタンス (Google Earth プラグインの個別インストール経由で提供される) を操作できるようになりました。Google Earth のマップ レイヤーは、スタンドアロン Google Earth アプリケーションに外観も動作も似ている個別 GMapType を経由して表示されます。これによって、視点を回転したり、上昇してみたり、ブラウザ内に Google Earth KML 情報を表示したりできます。

注: この Google Earth GMapType を使用するには、Google Earth プラグインがユーザーのコンピュータにインストールされている必要があります。現在、このプラグインは、Microsoft Windows でのみ利用できます。詳細なシステム要件については、Google Earth API デベロッパー ガイドを参照してください。

Google Earth プラグインの読み込み（Windows のみ）

Windows 用の Google Earth プラグインは、次の URL で利用できます。

http://dl.google.com/earth/plugin/GoogleEarthPluginSetup_en.exe

Google Earth プラグインは、Google Maps API とは異なる独自の API でコントロールできます。プラグインの使用と Google Earth API の使用についての詳細は、Google Earth API デベロッパー ガイドを参照してください。

Google Earth プラグインは、Google Maps API. 内でインスタンス化することもできます。

Google Earth プラグインの初期化中

マップへの Google Earth インスタンスの追加は、G_SATELLITE_3D_MAP を GMap2.addmapType() でマップに追加するだけです。次に、このマップ タイプを表示するように直接設定する (GMap2.setMapType() 経由)か、(GMap2.addControl() 経由でマップ タイプ コントロールを追加して) ユーザーが GMapTypeControl 内でこのマップ タイプを選択できるようにします。

次のコードでは G_SATELLITE_3D_MAP マップ タイプがマップに追加され、次にマップ内に Google Earth マップを表示するように、マップを明示的に設定します。(始めてこの例をクリックするとき、Google Earth プラグインのインストールを求めるプロンプトが表示されるので注意してください。)

var map = new GMap2(document.getElementById("map_canvas"),{ size: new GSize(640,480) } );
map.setCenter(new GLatLng(42.366662,-71.106262), 11);
map.addMapType(G_SATELLITE_3D_MAP);
var mapControl = new GMapTypeControl();
map.addControl(mapControl);
map.setMapType(G_SATELLITE_3D_MAP);

例を表示 (services-earth-plugin.html)

ローカル検索

サイトにローカル検索機能を追加する場合は、Google AJAX Search API を使用して、サイトにローカル検索コントロールを埋め込むことができます。このコントロールは GControl オブジェクトのサブクラスで、カスタム コントロール作成の良い例です。

このコントロールを Maps API アプリケーションに追加する前に、Google AJAX Search API URL を追加し、そのサービスの Maps API キーを使用する必要があります。また、以下に示すように、そのコントロール オブジェクトのスタイルシートを読み込む必要もあります。

// Load the Code
<script src="http://www.google.com/uds/api?file=uds.js&v=1.0&key=ABCDEF"
      type="text/javascript"></script>
<script src="http://www.google.com/uds/solutions/localsearch/gmlocalsearch.js" 
      type="text/javascript"></script>

// Load the Style Sheets
<style type="text/css">
  @import url("http://www.google.com/uds/css/gsearch.css");
  @import url("http://www.google.com/uds/solutions/localsearch/gmlocalsearch.css");
</style>

または、AJAX Loader を使用して、共通ローダー経由でこれらのモジュールすべてを読み込むこともできます。

これらの準備作業を行ったら、コントロール自体の読み込みは比較的簡単です。

// create your map
var map = new GMap2(document.getElementById("map_canvas"));

// create a local search control and add it to your map
var lsc = new google.maps.LocalSearch(); 
map.addControl(new google.maps.LocalSearch());

例を表示 (control-localsearch.html)

ローカル検索コントロールの詳細については、「Google AJAX Search API Reference」を参照してください。

KML オーバーレイと GeoRSS オーバーレイ

Google Maps API は、地理情報の表示に KML データ形式と GeoRSS データ形式をサポートしています。これらのデータ形式は GGeoXml オブジェクトを使用して地図に追加されます。このオブジェクトのコンストラクタは、一般公開されている XML ファイルの URL を受け取ります。GGeoXml の位置マークは GMarker として表示されるのに対して、GGeoXml のポリラインとポリゴンは Google Maps API のポリラインとポリゴンとして表示されます。KML ファイル内の <GroundOverlay> 要素は、GGroundOverlay 要素として地図上に表示されます。

GGeoXml オブジェクトは、addOverlay() メソッドを使用して地図に追加されます。(地図から削除するには、removeOverlay() を使用します)。KML と GeoRSS、両方の XML ファイルがサポートされています。GGeoXml は、Google Maps API 内でモジュール化されたオブジェクトであり、最初に使用されるまで読み込みが完了しないのでご注意ください。結果として、ページの後のそのコンストラクタの呼び出しに関する読み込みのみが完了しています。これは、通常、<body> の onload ハンドラ内で、GGeoXml コンストラクタを呼び出すことで達成されます。

// The GGeoXml constructor takes a URL pointing to a KML or GeoRSS file.
// You add the GGeoXml object to the map as an overlay, and remove it as an overlay as well.
// The Maps API determines implicitly whether the file is a KML or GeoRSS file.

var map;
var geoXml;

function initialize() {
  if (GBrowserIsCompatible()) {
    map = new GMap2(document.getElementById("map_canvas")); 
    geoXml = new GGeoXml("http://mapgadgets.googlepages.com/cta.kml");
    map.addControl(new GLargeMapControl());
    map.setCenter(new GLatLng(41.875696,-87.624207), 11); 
    map.addControl(new GLargeMapControl());
    map.addOverlay(geoXml);
  }
} 

GeoRSS の例を表示 (geoxml-rss.html)

KML の例を表示 (geoxml-kml.html)

交通オーバーレイ

Google Maps API では、GOverlay インターフェースを実装する GTrafficOverlay オブジェクトを使用して、交通情報を地図に追加できます。交通情報を地図に追加するには、GMap2.addOverlay() メソッドを使用します。GTrafficOverlay には、交通オーバーレイの表示を切り替えるための 2 つのメソッド (hide() と show()) があります。交通情報は、サポートされている都市に対してのみ表示されます。

GTrafficOverlayOptions オブジェクト直定数を使用して、GTrafficOverlay コンストラクタに任意でオプションを渡すことができます。

// The GTrafficOverlay is unique in that only one object of that type 
// should be added to a map. Adding multiple traffic overlays produces
// no added benefit.

var map;
var trafficInfo;

function initialize() {
  map = new GMap2(document.getElementById("map_canvas")); 
  map.setCenter(new GLatLng(49.496675,-102.65625), 3); 
  var trafficOptions = {incidents:true};
  trafficInfo = new GTrafficOverlay(trafficOptions);
  map.addOverlay(trafficInfo);
} 

交通オーバーレイの例を表示 (trafficOverlay.html)

ルート

GDirections オブジェクトを使用して、(さまざまな交通手段を利用した) ルートを計算する機能を追加できます。GDirections オブジェクトは、クエリ文字列 (「New York, NY to Chicago, IL」など) または指定されたテキストの緯度と経度 (「40.712882, -73.967257 to 41.943181,-87.770677」など) を使用して、ルート結果をリクエストして取得します。また、GDirections オブジェクトは、一連の経由地点を使用した複数の部分からなるルートもサポートしています。ルートは、地図上にルートを描画したポリライン、<div>要素内の一連のテキストによる説明 (「ウィリアムズバーグ ブリッジ ランプで右折」など)、またはその両方で表示されます。

Google Maps API でルートを使用するには、タイプ GDirections のオブジェクトを作成し、結果の受信と表示に GMap2 オブジェクトまたは <div>、あるいはその両方を指定します。デフォルトでは、返された経路に応じて地図の中心と範囲が決定されます (この動作は GDirectionOptions オブジェクト内のパラメータを使用して変更できます)。

ルートの読み込み

ルートをリクエストするには、GDirections.load() メソッドを使用します。このメソッドは、クエリ文字列とオプションの一連の GDirectionsOptions パラメータのセットを受け取ります。次のオプションが用意されています。

• locale は、結果を返すために使用する言語を指定し、入力されている場合は、Maps API hl パラメータに優先します。locale パラメータも hl パラメータも指定されていない場合、ブラウザのデフォルトの言語が使用されます。
• travelMode は、結果を計算するときに使用する移動手段を指定します。
• avoidHighways は、ルート算出時に高速道路を使わないことを指定します。
• getPolyline は、ルート オブジェクトが、返されたルートの描画用に、ポリライン データを返すことを指定します。デフォルトでは、表示用のマップ オブジェクトがある場合にのみ、GDirections オブジェクトがポリライン データを返します。この値を true に設定し、マップを用意しない場合、ポリライン データを直接扱う必要があります。
• getSteps は、これらのルートを表示する <div> パネルが用意されていない場合でも、テキストのルートを返すことを指定します。この値を true に設定し、パネルを用意しない場合、ステップ データを直接扱う必要があります。
• preserveViewport は、マップが自動的に中央に位置して、返されたルートの境界ボックスにズームするのではなく、マップはそのまま現在のビューポート上の中央に位置するように指定します。

交通手段

デフォルトでは、ルートはルート案内とすることを前提としていますが、Directions.load() メソッドを呼び出すときに GTravelMode を渡し、他の交通手段をリクエストすることもできます。サポートされている交通手段は以下のとおりです。

• G_TRAVEL_MODE_DRIVING は、道路網を使った標準のルート案内を示します。
• G_TRAVEL_MODE_WALKING は、歩道や側道 (利用できる場合) を使用する徒歩ルートをリクエストします。

注: 徒歩ルートは、場合によっては明確な歩道を含まないことがあるため、GDirections コンストラクタに <div> を指定した場合にのみ、サポートされます。この <div> は、返される進路変更ごとのテキスト ルートに警告を表示するのに使用されます。こういった <div> が用意されていない場合、徒歩ルートのリクエストではエラーが返されます。

返されたルートの処理

GDirections オブジェクトが、指定された GMap2 オブジェクトを使用して構築された場合、返されるルートにはポリラインオーバーレイが含まれます。GDirections オブジェクトが、指定された <div> 要素で構築された場合、返されるルートには GStep オブジェクトのセットを含む GRoute オブジェクトが含まれます(複数の地点を含むルートで構成されている場合、返されるルートには複数の GRoute オブジェクトが含まれ、各オブジェクトは一連の GStep オブジェクトで構成されます)。

返された情報は、directions オブジェクトにすぐには格納されません。このため、GDirections オブジェクトでは、この状態を確認するためにインターセプトできる load イベントが定義されています。

いったんルートが返されると、デフォルトでは、マップでルートを示すポリラインが表示され、一方テキスト ルートは、それを目的として指定された <div> 内に表示されます。また、GDirections オブジェクトは、GDirections.getPolyline() メソッドまたは GDirections.getRoute(i:Number) メソッドを取得できる結果を内部的に保存します。経路内のステップを取得するには GRoute.getStep(i:Number) メソッドを使用し、そのステップの HTML 形式の要約を取得するには GStep.getDescriptionHtml() を使用します。(以下の「ルートとステップ」を参照。)

GDirections オブジェクトは、インターセプト可能な 3 つのイベントを発行します。

• 「load」: このイベントは、ルート結果が正常に返されたときに、オーバーレイ要素が地図やパネルに追加される前にトリガされます。
• 「addoverlay」: このイベントは、ポリラインまたはテキストのルート コンポーネント、あるいはその両方が、地図または DIV 要素、あるいはその両方に追加された後にトリガされます。
• 「error」: このイベントは、ルート リクエストでエラーが発生した場合にトリガされます。呼び出し元は、GDirections.getStatus() を使用してエラーに関する詳細情報を取得できます。

// Create a directions object and register a map and DIV to hold the 
// resulting computed directions

var map;
var directionsPanel;
var directions;

function initialize() {
  map = new GMap2(document.getElementById("map_canvas"));
  directionsPanel = document.getElementById("my_textual_div");
  map.setCenter(new GLatLng(49.496675,-102.65625), 3);
  directions = new GDirections(map, directionsPanel);
  directions.load("from: 500 Memorial Drive, Cambridge, MA to: 4 Yawkey Way, Boston, MA 02215 (Fenway Park)");
}

例を表示 (directions-simple.html)

次の例は最初の例と同じですが、G_TRAVEL_MODE_WALKING を渡してルートが呼び出された点が異なります。

例を表示 (directions-walking.html)

ルートとステップ

GDirections オブジェクトは、複数の地点で構成されるルートもサポートしています。このルートを構築するには GDirections.loadFromWaypoints() メソッドを使用します。このメソッドは、テキストの入力住所またはテキストの緯度/経度による地点の配列を受け取ります。各経由地点は個別のルートとして計算され、それぞれ一連の GStep オブジェクトを含む、個別の GRoute オブジェクトで返されます。

GRoute オブジェクトは、ルートのステップ数 (タイプ GStep)、出発地点と到着地点のジオコード、および距離、所要時間、到着地点の正確な緯度と経度 (ジオコードが道路区分上にない場合は、到着地点のジオコードと異なる場合があります) などの計算されたその他の情報を格納します。各 GStep オブジェクトにも、テキスト (「サンノゼ方面のランプを経由して US-101 (南) に合流」など) の説明に加えて、距離、時間、正確な緯度と経度を含む計算された情報が含まれます。

Directions API パッケージ内の各種のオブジェクト、メソッド、イベントの詳細については、「API Reference」を参照してください。

例を表示 (directions-advanced.html)