©2009 Google -
Code 首頁 -
網站服務條款 -
隱私權政策 -
網站目錄
Google Code 提供下列語言介面：
English -
Español -
日本語 -
한국어 -
Português -
Pусский -
中文(简体) -
中文(繁體)
|
中文(繁體)
| Sign in
同樣好用的地圖，再加上 SLA、支援以及廣告的控制
歡迎使用「Google 地圖 API」的開發人員使用說明！只要使用「Google 地圖 JavaScript API」，就能在網頁中內嵌 Google 地圖。如果要使用此 API，請先申請 API 金鑰，收到 API 金鑰之後，就可以根據本使用說明的指示來開發地圖應用程式。
最新！在「地圖 API」中的反向地理編碼 (Reverse Geocoding)！
本使用說明的目標讀者是熟悉 JavaScript 程式設計與物件導向程式設計概念的人。也請您先熟悉一下使用者觀點的 Google 地圖。網路上可以找到很多 JavaScript 教學課程。
本篇使用說明並不詳盡；目的只是讓您可以快速開始探索「Google 地圖 API」、開發很酷的應用程式。所以我們也準備了 Google 地圖 API 參考文件，相對而言內容較為完整。
我們最近重新整理了這篇使用說明，加入了詳細的概念資訊，並將討論群組區分為下列幾個重點：
希望本文件經過重新設計後，更方便您的參考，也希望能幫助到初次使用「地圖 API」的開發人員。針對此使用說明，也歡迎您提出意見反應。請加入地圖 API 開發人員論壇，以提供您的意見並討論相關 API。
「Google 地圖 API」現在支援 Mapplet (地圖 + 小工具)，讓您可以在「Google 地圖」之中內嵌外部主控的應用程式。這些 Mapplet 會在自己的 iFrame 中執行，這麼一來您就可以將經過混搭的資料再與其他元件整合 (例如將某網站的程式碼與其他網站的程式碼結合)。這為在「Google 地圖」中進行程式設計工作的您，開啟了一個全新的紀元！撰寫 Mapplet 十分容易，要注意的是，有些功能的運作方式與「Google 地圖 API」有所不同。請參考「Google 地圖」Mapplet 使用說明和參考文件，瞭解詳情。
「Google 地圖 API」現在已經完全與 Google AJAX API 整合。在此架構下，您只要載入一個 API 金鑰，就適用於所有支援的 Google AJAX API (包括「Google 地圖」)。這個架構也會為各個 API 提供共用命名空間，允許不同的 Google API 一起操作。但也別擔心！如果不想使用 Google AJAX API 架構，也可以繼續使用現有的命名空間。
使用 Google AJAX API 架構十分簡單。只要遵照下列步驟，就能讓您的應用程式改用此架構：
http://maps.google.com/apis 載入 API，改從 http://www.google.com/jsapi 載入共用載入程式。您可以將現有的「Google 地圖 API」金鑰傳送到此網址：
<script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
google.load 方法載入您要的特定 API。google.load 方法需要特定 API 與欲載入版本的引數：
<script type="text/javascript">
google.load("maps", "2");
</script>
google.maps.* 命名空間取代 G 首碼。使用 google.setOnLoadCallback() 來執行所有的初始化。例如，使用 Google AJAX API 載入程式的時候，GMap2 物件就是對應至 google.maps.Map2：
<script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
<script type="text/javascript">
google.load("maps", "2.x");
// Call this function when the page has been loaded
function initialize() {
var map = new google.maps.Map2(document.getElementById("map"));
map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);
}
google.setOnLoadCallback(initialize);
</script>
有關使用 Google AJAX API 載入程式的完整使用說明，可於下列網址取得：http://code.google.com/apis/ajax/documentation/。
顯示文字資訊時 (例如控制項的名稱、版權宣告以及行車導航等)，「Google 地圖 API」會根據瀏覽器的設定來選擇要顯示的語言。但您也可以要「地圖 API」忽略瀏覽器的語言設定，而強制以特定語言來顯示資訊，作法是加入「地圖 API」javascript 程式碼時，一併在 <script> 標籤中加上 hl 參數，指定要使用的網域語言。
例如，若要以德語顯示地圖 API 應用程式，請將 &hl=de 新增至 <script> 標籤，如下所示：
<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=abcdefg&hl=de"
另請參閱網域語言的支援清單。請注意，我們經常更新支援的語言，因此這份清單可能不是最新的內容。
使用「Google 地圖 API」時，會要求您指出自己的應用程式是否使用感應器 (例如 GPS 定位器) 來判斷使用者的位置。這點對行動裝置而言，尤其重要。應用程式如果包括「地圖 API」javascript 程式碼，就必須傳送 sensor 參數給 <script> 標籤，以指出您的應用程式是否使用感應器裝置。
判斷使用者位置的應用程式如果是以 http://maps.google.com/maps 或 Common Loader 來載入「地圖 API」JavaScript，就必須傳送 &sensor=true。
#
# Example using sensor when loading the Maps JavaScript API
#
<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=abcdefg&sensor=true">
#
# Example using sensor when loading the Maps API via the common loader
#
<script type="text/javascript" src="http://www.google.com/jsapi?key=abcdef"></script>
<script type="text/javascript">
google.load("maps", "2",{"other_params":"sensor=true"});
function initialize() {
var map = new google.maps.Map2(document.getElementById("map"));
map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);
}
google.setOnLoadCallback(initialize);
</script>
請注意，即使您的裝置不使用感應裝置，仍然必須傳送此參數，並將其值設定為 false。
開始使用「Google 地圖 API」之前，請注意下列考量，以確保您的應用程式在其預設平台上順利地運作。
「Google 地圖 API」支援的瀏覽器與Google 地圖網站支援的瀏覽器相同。指令碼 http://maps.google.com/maps?file=api&v=2 幾乎可以在任何一種瀏覽器中進行剖析，而不發生任何錯誤，因此您可以在檢查相容性之前安全地使用該指令碼。
有時候，如果使用者的瀏覽器不相容，不同的應用程式就需要不同的行為。「地圖 API」提供全域方法 (GBrowserIsCompatible()) 來檢查相容性，但是當它偵測到瀏覽器不相容的時候，並不會有任何自動的行為。本說明文件中大部分的範例都不會檢查瀏覽器相容性，碰到舊的瀏覽器也不會顯示錯誤訊息。顯然地，面對瀏覽器不相容的情形，真正的應用程式要有一些更恰當的措施，但為了讓範例更容易閱讀，我們省略了這類檢查。
無可避免地，功能多樣的應用程式會遭遇到瀏覽器和平台之間不一致的問題。對於這些問題，沒有簡單的解決方案，但是 Google 地圖 API 開發人員論壇和 quirksmode.org 應該能幫您找出一些暫時的解決方法。
我們建議您，如果網頁有地圖，就使用與標準相容的 XHTML。瀏覽器看到網頁上方的 XHTML DOCTYPE 之後，就會以「標準相容模式」呈現網頁，在不同瀏覽器之間的行為也就較為統一。網頁如果沒有註明該定義，可能會以「Quirks 模式」呈現，造成版面配置不一致。
如果您要在地圖上顯示折線 (類似「Google 地圖」用來顯示行車導航的線條)，就需要在 XHTML 文件中加入 VML 命名空間，讓每個行為在 Internet Explorer 中都可以正常運作。這種 XHTML 文件開頭看起來像是這樣：
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
http://maps.google.com/maps?file=api&v=2 網址中的 v 參數會參照要使用的「Google 地圖 API」的「版本」號碼。大部分的 API 使用者會在該網址中傳送 v=2 參數，使用目前的「第 2 版」API。但您也可以傳送 v=2.x，就能取得最新的發佈版本 (包括最新的功能)。但是請您注意，最新的發佈可能不像 v=2 發佈版本來得可靠。我們會經常更新「Google 地圖 API」(有時候是每周)，除非發現問題，否則 v=2.x 發佈版本的功能都會移轉至 v=2 發佈版本。
但除此之外，您也可以傳送 v=2.s 參數，使用「穩定」版本的 API。這個版本更新速度較不頻繁，大約是每幾個月更新一次。因為 v=2 和 v=2.x 發佈大約每兩個星期就會更新一次，因此有些開發人員會比較想使用穩定的 v=2.s。請注意，與最新版本相較，穩定版本可能會落後數個版本，無法提供部分最新功能。
API 如有更新，都會標示版本 (例如「版本 2.76」)。API 更新後，根據之前版本的較舊程式碼，可能會與宣傳的運作方式不同。如果您要讓應用程式固定使用特定版本的 API，可以在 v 參數中明確指出該版本 (例如 v=2.75)。但我們並不建議這種作法。程式碼如有更新，最好還是讓您的產品根據更新的程式碼來運作。
如果 API 有重大更新，我們會改變主要版本號碼，並在 Google 程式碼和地圖 API 開發人員論壇張貼通知。屆時，我們預計會同時支援新舊兩版至少一個月，以便您移轉程式碼。
「地圖」小組也會以最新的錯誤修正和效能改善，在背景更新 API。這些錯誤修正應該只會改善效能並修正錯誤，但有時可能意外中斷某些 API 用戶端。如果發生這種問題，請使用地圖 API 開發人員論壇來回報。
本使用說明參照的是「版本 2」的「地圖 API」( 2006 年 4 月 3 日發佈。如果您的 API 是使用「版本 1」的「地圖 API」(亦即您在 2006 年 4 月 3 日前開發網站)，則請為網站升級。請參閱版本 2 升級指南以取得詳細資訊。
請注意，此使用說明中大部分的範例僅顯示相關的 JavaScript 程式碼，而非完整的 HTML 檔案。您可以將 JavaScript 程式碼插入自己的主要 HTML 檔案，或者也可以按一下範例之後的連結，就能下載每個範例的完整 HTML 檔案。
「Google 地圖 API」鼓勵使用函式 Closure，而 API 事件處理系統 GEvent 會將事件附加至 DOM 節點，幾乎會讓部分瀏覽器無可避免地流失記憶體，尤其是 Internet Explorer。「版本 2」的「地圖 API」引進新的方法 (GUnload())，可以移除引起這些流失的大部分循環參照。您應該呼叫網頁中 onunload 事件的 GUnload()，以減少應用程式流失記憶體的可能：
<body onunload="GUnload()">
使用此函式後，幾乎已經完全排除 Internet Explorer 在「Google 地圖」流失記憶體的情況，不過，如果您發現有記憶體耗用的問題，請還是要在自己的網站上使用 Drip 之類的工具來測試記憶體流失的情形。
這裡有一些其他資源。請注意，這些網站並非 Google 所有或支援。
如果您的程式碼無法發揮作用，下列方法可以協助您解決問題：