您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps JavaScript API

為協助您開始,我們將先引導您使用「Google 開發人員控制台」來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps JavaScript API 與相關服務
  3. 建立適當的金鑰
繼續

版本控制

Google Maps JavaScript API 團隊會定期更新 API,以加入新功能、修復錯誤以及改善效能。本頁說明可供您應用程式使用的 API 版本,無論是測試環境或生產環境。API 版本有下列名稱:

  • 實驗
  • 正式發行
  • 凍結

我們也提供根據您應用程式類型或用途來管理版本控制程序的最佳做法。

版本變換和版本類型

每一季我們會推出一個新編號的版本並發行給公眾使用,稱為「實驗」版本。同時,之前發行的實驗版本會變成「正式發行」版本,而之前的正式發行版本則會成為「凍結」版本。這個過程稱為「版本變換」

我們會在整季中持續修復實驗版本和正式發行版本中的錯誤。這些更新都會在 Google Maps JavaScript API 版本資訊中註明。

您可以在 Google Maps JavaScript API 啟動要求的 v 參數,指定您的應用程式中要載入哪個版本的 API。下列是支援的選項:

  • 實驗版本是以 v=3.exp 指定。
  • 正式發行版本是以 v=3 指定。
  • 特定的版本號碼。例如 v=3.25v=3.26

如果您並未明確指定版本,且持有標準方案 (包括未提供金鑰的客戶)的話,預設會收到實驗版本。如果您持有進階方案而沒有指定版本的話,預設會收到正式發行版本。

實驗版本

實驗版本(目前是 3.27)包含於公開時的最新功能和錯誤修復。我們不保證對實驗版本所做的變更能提供穩定的功能。建議您定期使用實驗版本測試您的應用程式,只需在載入 API 時新增 v=3.27 即可。如果您喜歡追求刺激,則可以新增 v=3.exp,以持續收到包含所有最新功能的實驗版本。

您可以使用下列啟動指定實驗版本:

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3.exp
        &key=YOUR_API_KEY&callback=initMap">

正式發行版本

我們會持續將錯誤修復新增至正式發行版本,並同時確保功能集維持穩定。這些錯誤修復列於版本資訊中。

目前的正式發行版是 3.26。您可以使用下列任一啟動要求它:

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3
        &key=YOUR_API_KEY&callback=initMap">

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3.26
        &key=YOUR_API_KEY&callback=initMap">

凍結版本

發行新編號的版本時,我們會「凍結」之前的正式發行版本。這代表我們已不會再為該版本定期提供錯誤修復的更新。不過,我們可能偶爾會對它進行變更,例如出於法律的原因而需要這樣做的時候。

每次我們推出新的凍結版本時,就會淘汰之前的凍結版本。指定淘汰的版本(如 v=3.0 )將一律會傳回目前的凍結版本。

目前的凍結版本是 3.25。您可以使用下列啟動要求它:

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3.25
        &key=YOUR_API_KEY&callback=initMap">

最佳做法

Google Maps JavaScript API 團隊盡一切努力維護不同版本 API 的相容性。然而,為了持續提供最新服務,也為了操作方面的原因,我們有時候會做出一些與現有功能交互影響的變更。在這些情況下,可能有必要使用 Google Maps JavaScript API 來調整程式碼(特別是針對更進階的應用程式),以使程式碼能夠以預期方式運作。以下是我們針對一些常見的版本用法案例所建議的最佳做法。

針對高可用性/高流量的應用程式

「願意投入額外的努力以確保穩定性和可用性」

為了確定版本變換時不會出現任何問題,建議您在啟動中明確指定 API 目前正式發行版的版本號碼。例如,v=3.26。為了避免隨時間而降到凍結版本的 API,請務必訂閱 Google Maps JS API v3 Notifications and Announcements 群組,以便從 Google 收到版本變換通知。

於(每季的)版本變更之後,您的生產系統將會要求 API 的凍結版本。這個時候,我們建議設定一個預備/開發環境,以便使用新的正式發行版本 API 來測試您的應用程式。如果出現任何問題,您可以對程式碼進行必要調整。如果您自信您的應用程式可以順利地使用新的正式發行版本 API,則可以推出所需的修復(如果有的話),同時更新您的應用程式,要求對應新正式發行版本的版本號碼。

針對一般的應用程式

我們建議在啟動要求中指定 v=3。這表示您一律會收到已經承受大量流量並套用必要錯誤修復的最新 Google Maps JavaScript API 正式發行版本。在大部分的情況下,版本變換並不需要採取額外的動作。不過,為了確保您的應用程式可以繼續順利的運作,我們建議您訂閱 Google Maps JS API v3 Notifications and Announcements 群組,以便從 Google 收到版本變換通知。

版本變換之後,您的應用程式便會使用新版的 Google Maps JavaScript API。您可能也要查看版本資訊,瞭解可能會影響到您的任何變更。如果您注意到應用程式內的任何項目沒有正常運作,便可以在啟動要求內明確指定目前的凍結版本號碼以切換回舊版,同時對程式碼進行必要的調整。

針對先進的應用程式

「希望優先存取最新的功能」

對於不特別重視提供持續可用性的應用程式,我們建議您要求 Google Maps JavaScript API 的實驗版本 (v=3.exp),以取得所有最新功能。實驗版本在每週發行前都會由 Google 進行完整測試,並通常都相當穩定。不過,每週的發行週期代表您必須維持較高的警覺,以確保您的應用程式能夠一直以預期方式運作。

檢查版本

如要偵錯,請使用 google.maps.version 屬性來在應用程式中取得目前的 Google Maps JavaScript API 版本。下列程式碼範例會將 API 版本寫入瀏覽器控制台。(如需瀏覽器控制台的詳細資訊,請參閱檢查瀏覽器中的錯誤指南。)

<!DOCTYPE html>
<html>
  <head>
    <title>Display Google Maps API Version</title>
  </head>
  <body>
    <script>
      function initMap() {
        // Add your map here.
        console.log('Google Maps API version: ' + google.maps.version);
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?YOUR_API_KEY&callback=initMap"
    async defer></script>
  </body>
</html>

API 版本的文件

開發人員指南中的說明一律是針對實驗版本。

此外,每個版本皆有個別的參考資料:

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps JavaScript API
Google Maps JavaScript API
需要協助嗎?請前往我們的支援網頁