服務

服務總覽

「Google 地圖 API」會定期擴充，增加新功能和特色，通常會先在 maps.google.com 發佈。本章節會介紹這些服務。注意：因為「服務」的定義可能較為模糊，因此這個部分的內容較為廣泛。基本上，無法放到其他地方的所有內容，我們都把它放在這個部分了。

XML 和資料剖析

「Google 地圖 API」提供一種工廠方法 (factory method)，以建立適用於各種瀏覽器的 XmlHttpRequest() 物件，此物件可以在最新版本的 Internet Explorer、Firefox 以及 Safari 運作。與所有的 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 也會匯出較簡單的 GDownloadUrl() 方法，供一般 HTTP GET 要求使用，這類要求不需要 XmlHttpRequest() readyState 檢查。上述範例可以使用 GDownloadUrl() 重新撰寫如下：

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

您可以使用靜態方法 GXml.parse() 剖析 XML 文件，此方法接受 XML 的字串做為其唯一的引數。此方法與大部分先進的瀏覽器相容，但是如果瀏覽器原始不支援 XML 剖析，則會產生例外狀況。

在此範例中，我們下載靜態檔案 ("data.xml")，檔案中包含以 XML 格式、使用 GDownloadUrl 方法的 lat/lng 座標清單。下載完成時，我們以 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 類別參考文件，取得詳細資訊。

地理編碼

地理編碼 (Geocoding) 是將地址 (例如 1600 Amphitheatre Parkway, Mountain View, CA) 轉換為地理座標 (例如緯度 37.423021 和經度 -122.083739)，您可以用地理座標來放置標記或指出地圖上的位置。「Google 地圖 API」包括地理編碼服務，您可以透過 HTTP 要求直接存取此服務，或者使用 GClientGeocoder 物件。

請注意，地理編碼會耗用大量的時間和資源。所以，請儘可能預先地理編碼您的地址 (使用 HTTP Geocoder 或其他地理編碼服務)，並使用地理編碼快取來儲存結果。

地理編碼物件

您可以透過 GClientGeocoder 物件來使用「Google 地圖 API」地理編碼服務。使用 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)

您也可以修改「地圖 API」Geocoder，透過 GClientGeocoder.setViewport() 方法讓指定檢視區中的結果 (表示為類型 GLatLngBounds 的界限方塊) 優先。您可以使用 GClientGeocoder.setBaseCountryCode() 方法，將結果篩選為特定網域 (國家/地區)。只要是主要「Google 地圖」應用程式提供地理編碼的所在，每個網域都可以傳送地理編碼要求。例如，在西班牙網域 (http://maps.google.es，指定國家/地區代碼為 es) 以及預設的美國網域 (http://maps.google.com)搜尋「Toledo」，傳回的結果就會不同：

擷取有結構的地址

如果您要得到關於地址的結構資訊，GClientGeocoder 也提供 getLocations() 方法，可傳回由下列資訊組成的 JSON 物件：

• Status
• • request -- 要求類型。在此情況下，它永遠是 geocode。
  • code -- 回應代碼 (與 HTTP 狀態碼類似)，指出地理編碼要求是否成功。請參閱狀態碼的完整清單。
• Placemark -- 如果 Geocoder 找到多個符合項目，則會傳回多個地標。
• • address -- 適當格式且大小寫正確的地址。
  • AddressDetails -- 地址格式為 xAL (即 eXtensible Address Language)，一種地址格式的國際標準。
  • • Accuracy -- 指出將指定地址進行地理編碼時的精確性屬性。請參閱可能值的清單。
  • Point -- 3D 空間的點。
  • • coordinates -- 地址的經度、緯度以及高度。在此案例中，高度永遠設為 0。

我們在此顯示 Google 總部地址由 Geocoder 傳回的 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() 方法將地址進行地理編碼，擷取適當格式版本的地址以及來自 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.html)

反向地理編碼

「地理編碼」一詞通常是指將人類可閱讀的地址轉換為地圖上的點。如果將此程序反過來，也就是將點翻譯為人類可閱讀的地址，則稱為「反向地理編碼」(Reverse Geocoding)。

GClientGeocoder.getLocations() 方法同時支援標準和反向地理編碼。如果您將 GLatLng 物件 (而不是 String 地址) 傳給此方法，則 Geocoder 會執行反向查詢，並傳回結構 JSON 物件的「最接近地址」的位置。請注意，如果提供的 GLatLng 找不到完全符合的地址，最接近地址的位置可能會與原先查詢的緯度和經度值不太一樣。

注意：反向地理編碼並非完全精準。Geocoder 會在一定的容許範圍內，嘗試找出最近的地址位置；如果找不到任何符合的項目，Geocoder 通常會傳回 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 預設會搭配用戶端快取。快取會儲存 Geocoder 回應，如果有地址再次要求地理編碼，則可以更快的回應。您可以將 null 傳送給 GClientGeocoder 物件的 setCache() 方法，停用快取。不過，我們建議維持啟用快取，以改善效能。要變更 GClientGeocoder 使用的快取，可呼叫 setCache() 並傳入新的快取。要清空目前快取的內容，請在 Geocoder 上或直接在快取上呼叫 reset() 方法。

我們鼓勵開發人員建置自己的用戶端快取。在此範例中，我們建構的快取包含預先計算的 Geocoder 回應，其中為地理編碼 API 涵蓋之國家/地區的六個大都市。首先，我們建置地理編碼回應的陣列。接著，我們擴充標準 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 進行地理編碼

您也可以使用伺服器端指令碼，直接使用「地圖 API」Geocoder。透過用戶端 Geocoder 時不建議使用此方法；不過，除錯時，或無法使用 JavaScript GClientGeocoder 物件時，則很有用。

如果要使用「Google 地圖 API Geocoder」，請將要求傳送到 http://maps.google.com/maps/geo?，並於 URI 中使用下列參數：

• q (「必要」) — 要進行地理編碼的地址。
• key (「必要」) — 您的 API 金鑰。
• sensor (「必要」) — 指出地理編碼要求是否來自具有位置感應器的裝置。此值必須為 true 或 false。
• output (「必要」) — 產生輸出的格式。選項為 xml、kml、csv 或 (預設) json。
• ll (「選用」) — 檢視區中心的 {latitude,longitude}，以逗號分隔的字串表示 (例如「ll=40.479581,-117.773438」)。必須同時將 spn 參數傳送給 Geocoder，此參數才有意義。
• spn (「選用」) — 檢視區的「span」，以逗號分隔的字串 {latitude,longitude} 表示 (例如「spn=11.1873,22.5」)。必須同時將 ll 參數傳送給 Geocoder，此參數才有意義。
• gl (「選用」) — 國家/地區代碼，指定為 ccTLD (「頂層網域」) 兩個字元值。

注意：gl 和 spn,ll 檢視區參數只會影響 (不會完全限制) 來自 Geocoder 的結果。

在此範例中，我們要求 Google 總部的地理座標。

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

我們特別用 sensor 做為範例中變數 true_or_false 的名稱，以強調您必須明確地將此值設定為 true 或 false。

如果您指定 json 為輸出，則回應會格式化為 JSON 物件。如果指定 xml 或 kml，則回應會以 KML 傳回。除了 MIME 類型之外，XML 和 KML 輸出是相同的。

例如，這個回應是 Geocoder 傳回的「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 格式傳回的回覆是由四個數字組成，由逗號分隔：

1. HTTP 狀態碼
2. 精確性 (請參閱精確性常數)
3. 緯度
4. 經度

下列範例顯示三個地址的回覆，精確性由小到大：「State St, Troy, NY」、「2nd st & State St, Troy, NY」以及「7 State St, Troy, NY」

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

使用 Street View 物件

要使用 Street View Panorama 物件，則用戶端的瀏覽器必須支援 Flash 外掛程式。

Google Street View 提供指定道路 360 度全景的檢視，涵蓋「Google 地圖」的所有區域。Street View 圖片的範例如下所示。

Google Street View 使用大部分瀏覽器都支援的 Flash® 外掛程式，來顯示這些互動式圖片。「Google 地圖 API」現在提供 Street View 服務，以取得並操縱 Google Street View 中使用的圖片！

GStreetviewPanorama 物件

GStreetviewPanorama 物件 (提供 API 介面給 Street View Flash® 檢視器) 支援用來處理 Street View 圖片。要將 Street View 整合入您的「地圖 API」應用程式，需要遵循下列幾個簡單步驟：

1. 建立容器 (通常是 <div> 元素)，以容納 Street View Flash® 檢視器。
2. 建立 GStreetviewPanorama 物件，並將它放在容器中。
3. 初始化 Street View 物件以參照特定位置，並顯示初始「檢視點」(POV)。
4. 檢查 603 錯誤值，以處理不支援的瀏覽器。

GStreetviewPanorama 物件的建構函式中必須有容器。這也可以讓您使用 GStreetviewPanoramaOptions 參數 (選用) 來設定其位置。在建構以變更其位置和 POV 之後，在物件上呼叫 setLocationAndPOV()。

關於容器和設定位置以及檢視點的詳細資訊，如下所述。

Street View 容器

Street View Flash 檢視器需要容器 DOM 節點以顯示其內容，通常是 <div> 元素。要讓全景圖片顯示最佳，建議至少大小要有 200 x 200 像素。我們也不鼓勵使用大型檢視器，因為這樣會讓 Flash 檢視器消耗太多記憶體，可能會影響瀏覽器效能。

GStreetviewPanorama 建構函式需要 container 參數，以識別顯示 Street View Flash 檢視器的初始容器元素。您可以 hide() GStreetviewPanorama 物件，暫時不顯示它，或者 show() 該物件，讓它重新顯示在檢視器。

您想要變更 Street View Flash 檢視器的容器時，請寄送 setContainer() 方法，將要附加的新項目傳送給它。如果容器調整大小，您可以將 checkResize() 方法傳送給 GStreetviewPanorama 物件，強制它調整大小以符合新的大小。

如果要從 DOM 整個移除 Street View Flash，並釋放其記憶體，請將 remove() 方法傳送給該物件。如果您要從 DOM 移除容器元素，則必須呼叫此方法；否則用戶端的瀏覽器會發生記憶體流失。

Street View 位置

Street View 圖片包括位置 (相對於 GLatLng) 和特殊方向 (一種 GPov)，兩者結合後就可以定出圖片所顯示的景色。這兩個參數可以使用選用的 GStreetviewPanoramaOptions 參數，在建構 Street View 物件時指定。

如果想知道目前支援 Street View 的城市清單，請參閱 Google 地圖說明中心。要判斷某位置是否支援 Street View 資料，有三種基本方式：

• 您可以儲存已知有效 Street View 位置的 GLatLng。
• 您可以檢查 GStreetviewOverlay 地圖方塊疊加層，並目視檢查道路網。支援 Street View 的道路在疊加層上會以藍色明顯標示。然後可以按一下事件或地理編碼邏輯，將支援的位置傳送至 GStreetviewPanorama 物件。(請參閱Street View 疊加層。)
• 您可以使用 GStreetviewClient 物件，指定傳送 GLatLng，以執行查詢 Street View 物件。GStreetviewClient 物件支援多種查詢，可找出全景資料。(請參閱Street View 用戶端查詢。)

請注意，最後兩個方法並不精確：在這些情況下，Street View 服務不需要 (而且通常不接收) 精確的緯度和經度，而是會搜尋距離指定 GLatLng「最近」的全景資料。

下列範例使用 GStreetviewPanoramaOptions 來指出初始緯度和經度，以使用 Street View POV 保留空白，代表預設檢視為向北。

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

檢視範例 (streetview-simple.html)

Street View 錯誤處理

因為 Google Street View 需要 Flash® 外掛程式的支援，所以您的程式碼應檢查使用者的瀏覽器是否可以使用此外掛程式。您可以在應用程式中，為 GStreetviewPanorama 物件上的 error 事件註冊事件處理常式，來達成此目的。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;
  }
}  

Street View 檢視點 (POV)

Street View 位置定義相機拍攝某圖片的位置，但是它沒有定義相機拍攝圖片的方向。因此，GPov 物件實字定義三個 Property：

• yaw 定義相機位置相對於正北的旋轉角度 (以度為單位)。偏角角度以順時針方向測量 (90 度為正東方)。
• pitch 定義相機初始預設傾斜角度的「向上」或「向下」變異量，預設傾斜角度通常 (但並非永遠) 是水平。(例如，從山丘上拍攝的圖片的預設傾斜角度就不是水平的。)負值的傾斜角度為向上仰角 (直到 -90 度為垂直向上，再從對角的方向回到預設傾斜角度)，而正值為向下俯角 (直到 +90 度為垂直向下，再從對角的方向回到預設傾斜角度)。
• zoom 定義此檢視的縮放等級 (有效限制「視野」)，0 代表縮到最小。Street View 位置不同，能提供的縮放等級檢視也可能不同。

根據預設，這些值全都為 0，定義為水平檢視，方向為正北，並以最寬的可能視野顯示。

設定全景檢視

如同稍早所述，您可以根據全景物件的建構、使用 GStreetviewPanoramaOptions 參數，為它設定位置和 GPov。

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);

您也可以在建構 GStreetviewPanorama 物件之後，使用 setLocationAndPOV() 方法設定位置和 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)

使用 Street View 疊加層

要判斷某道路是否支援 Street View，最簡單的方式便是使用 GStreetviewOverlay 物件。只要建立此類型的疊加層，並將它加入地圖；包含 Street View 資料的道路便會在地圖上以藍色框線顯示。

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)

您知道某地理區域支援 Street View 之後，就可以加入邏輯，透過傳播 GStreetviewPanorama 物件回應在有效 Street View 道路上按一下的事件。

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)

如果知道特定位置支援 Street View，您可以將位置資訊和 POV 儲存起來，並將這些資訊放到該物件本身。

Street View 用戶端查詢

對使用者而言，如果只是目視檢查 GStreetviewOverlay，常常並無法判斷道路是否支援 Street View，而且也不方便。因此，API 提供服務，可用程式設計方式來提出要求，抓取 Street View 資料。此服務使用 GStreetviewClient 物件來完成。

執行 Street View 查詢

GStreetviewClient 物件會使用 Google 的 Street View 服務，來執行全景資料查詢。因為此查詢為非同步，所以此類別的方法需要回呼函式，來處理接收到的資料。如果沒有傳回任何資料，則所有指定的回呼會傳送 null，因此您的回呼函式中要做這類的檢查。

GStreetviewClient 方法 getNearestPanoramaLatLng() 會從指定位置 (位置本身會以 GLatLng 傳送) 抓取附近全景圖片的 GLatLng。

而 getNearestPanorama() 和 getPanoramaById() 兩者則抓取 GStreetviewData 物件，此物件儲存特定全景物件的中繼資料。下列章節會說明此資料。

處理用戶端回應

GStreetviewData 物件的結構由三個 Property 組成：location、copyright (包含所顯示特定圖片的資訊) 以及 links (它提供全景物件附近的資訊)。這些 Property 的結構描述如下：

# 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 物件實字的完整描述會顯示在地圖 API 參考文件。)

注意：請勿混淆 GStreetviewData.location Property 與 window.location Property。如果想從這個物件的 location Property 擷取資料，請先確認您確實從 Street View 伺服器接收到回應 (如下所示)。否則，location Property 會預設為 window.location，可能會發生意想不到的行為。

如果成功要求 GStreetviewClient 物件，它會傳送 GLatLng 或 GStreetviewData 物件給指定的回呼函式。不過，因為抓取 Street View 資料為非同步，用戶端物件可能不會抓取到這些資料物件，因此您的程式碼不應預期屆時用戶端仍然會存在。而是要時時檢查從任何要求傳回的 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 物件中，並顯示與該 Street View 物件關聯的資料集。使用者每按一次「下一步」，就會重複該程序，允許使用者沿著附近的全景物件瀏覽一遍。

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 Plug-in 互動

「Google 地圖 API」現在允許開發人員在其「地圖 API」應用程式中調整「Google 地球」的實例 (透過安裝另外的「Google Earth Plug-in」來提供)。「Google 地球」地圖圖層會透過個別的 GMapType 來顯示。GMapType 的樣子和行為跟獨立的「Google 地球」應用程式很像，您可以旋轉視角、查看高度並在瀏覽器中檢視「Google 地球」KML 資訊。

注意：「Google Earth Plug-in」必須安裝在使用者的電腦，才能使用此「Google 地球」GMapType。目前，此外掛程式只能在 Microsoft Windows 上使用。完整的系統需求，請參閱 Google 地球 API 開發人員指南。

載入 Google Earth Plug-in(僅 Windows 適用)

「Google Earth Plug-in (Windows 版)」可於下列網址取得：

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

「Google Earth Plug-in」可以透過它本身的 API 來控制，此 API 與「Google 地圖 API」不同。請參閱 Google 地球 API 開發人員指南，取得使用此外掛程式以及使用「Google 地圖 API」的完整資訊。

「Google Earth Plug-in」也可以在「Google 地圖 API」中具現化。

初始化 Google Earth Plug-in

要在地圖上加入「Google 地球」實例，只要將 G_SATELLITE_3D_MAP 以 GMap2.addmapType() 加入您的地圖即可。然後，您可以直接在地圖上顯示此地圖類型 (透過 GMap2.setMapType())，或者允許使用者在 GMapTypeControl 中選取此地圖類型 (藉由新增 GMap2.addControl() 地圖類型)。

下面的程式碼會將 G_SATELLITE_3D_MAP 地圖類型加入地圖，然後明確設定在地圖中顯示「Google 地圖」地圖類型。(請注意，第一次按一下這個範例時，會提示您安裝 Google Earth Plug-in。)

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 搜尋 API」在網站上內嵌在地搜尋控制項。此控制項是 GControl 物件的子類別，也是建立自訂控制項的良好範例。

將此控制項加入地圖 API 應用程式之前，您需要加入「Google AJAX 搜尋 API」網址，並為該服務使用您的地圖 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 搜尋 API 參考文件

KML/GeoRSS 疊加層

「Google 地圖 API」支援以 KML 和 GeoRSS 資料格式來顯示地理資訊。這些資料格式應使用 GGeoXml 物件加入地圖，此物件的建構函式接受可公開存取 XML 檔案的網址。GGeoXml 地標會呈現為 GMarker，而 GGeoXml 折線和多邊形會呈現為「Google 地圖 API」折線和多邊形。KML 中的 <GroundOverlay> 元素會呈現為地圖上的 GGroundOverlay 元素。

GGeoXml 物件會使用 addOverlay() 方法加入地圖。(您可以使用 removeOverlay() 將它們從地圖移除。)同時支援 KML 和 GeoRSS XML 檔案。請注意，GGeoXml 在「Google 地圖 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 地圖 API」可讓您使用 GTrafficOverlay 物件，在地圖上加入交通資訊，該物件是實作 GOverlay 介面。您可以使用 GMap2.addOverlay() 方法，將交通資訊加入地圖。GTrafficOverlay 有兩個方法 (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 到 41.943181,-87.770677」)。GDirections 物件也可以使用一系列路點，提供分為多部分的導航。導航可以是在地圖上以折線繪製路線，或是在 <div> 元素中使用一系列文字描述 (例如「Turn right onto the Williamsburg Bridge ramp」)，或兩者同時使用。

要在「Google 地圖 API」使用導航，請建立類型 GDirections 的物件，並指派 GMap2 物件和/或 <div> 來接收並顯示結果。根據預設，地圖會由傳回的路線包圍、置中 (不過，您可以在 GDirectionOptions 物件中使用參數來變更)。

載入導航

導航使用 GDirections.load() 方法來進行要求。此方法接受查詢字串和一組選用的 GDirectionsOptions 參數。可以使用下列選項：

• locale 指定傳回結果要使用的語言，會覆寫地圖 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> 元素來建構，則傳回的導航將會包含 GRoute 物件 (其中包含一組 GStep 物件)。(如果導航是由多點導航所組成，則傳回的導航會包含多個 GRoute 物件，每個都是由一系列的 GStep 物件組成。)

請注意，導航物件不會立即填入傳回的資訊。因此，GDirections 物件定義「load」事件，您可以攔截這個事件來判斷此狀態：

傳回導航後，地圖會根據預設顯示路線的折線，而文字導航會顯示在依此目的所提供的 <div> 中。GDirections 物件也會在內部儲存結果，您可以使用 GDirections.getPolyline() 和/或 GDirections.getRoute(i:Number) 方法來取用。路線中的步驟可以使用 GRoute.getStep(i:Number) 方法來抓取，而步驟的 HTML 摘要可以使用 GStep.getDescriptionHtml() 抓取。(請參閱下面的路線和步驟。)

GDirections 物件也會引發三個您可以攔截的事件：

• 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() 方式來建構。此方法接受文字輸入陣列或文字緯度/經度點的陣列。每個路點都計算為個別的路線，並於個別的 GRoute 物件中傳回，每個傳回的物件又包含一系列的 GStep 物件。

GRoute 物件會儲存該路線的步驟 (類型 GStep 的) 號碼、路線的起點和終點地理編碼，以及其他已計算的資訊 (例如距離、期間以及端點實際的經緯度)。如果地理編碼不是位於道路路段上的話，端點可能與終點地理編碼不同。每個 GStep 物件也會包含該文字的描述 (例如「從 San Jose 交流道轉 US-101 S 公路」) 以及已計算的資訊，包括距離、期間以及實際的經緯度。

如需關於「導航 API」套件中各種物件、方法以及事件的詳細說明，請參閱 API 參考文件。

檢視範例 (directions-advanced.html)