Maps JavaScript API 快速參考

Maps JavaScript API 是用戶端網頁 API,可用於在網頁上建立 2D 和 3D 地圖、新增標記、自訂圖形、動畫和互動式資料層,以及使用 Places Library 建構位置功能。

Maps JavaScript API:重要資訊

  • 產品:Maps JavaScript API
  • 別名:Maps JS API、Maps JS API 第 3 版
  • 類別:地圖
  • 平台:JavaScript (瀏覽器)
  • 執行位置:用戶端 (應用程式或瀏覽器程式碼)
  • 推出階段:GA
  • 生命週期:有效
  • 總覽:Maps JavaScript API 總覽
  • 適用地區:全球。功能涵蓋範圍 (例如 3D 地圖、路況、路線和邊界樣式) 因國家/地區而異;歐洲經濟區帳單地址適用歐洲經濟區服務條款。(涵蓋範圍詳細資料)

Maps JavaScript API:使用時機

在下列情況下使用 Maps JavaScript API:

  • 您需要在網頁上,顯示含有自訂標記、圖形或資料層的互動式 2D 或 3D 地圖。
  • 您需要使用進階標記和折線,顯示自有資料串流中的即時資產位置和移動路徑。
  • 您需要繪製地理圍欄 (圓形、多邊形),並在瀏覽器中測試座標是否落在圍欄內。
  • 您需要透過 Places 程式庫,在網頁應用程式中提供用戶端 Place Search、Place Autocomplete 或 Place Details。

在下列情況下,請勿使用 Maps JavaScript API:

  • 您需要嵌入商家地點地圖或路線連結,但不想編寫自訂 JavaScript。請改用 Maps Embed API。
  • 您只需要一個連結,即可開啟 Google 地圖,並顯示地點、搜尋結果或路線。請改用 Maps 網址。
  • 您必須整合共乘或預約配送車隊追蹤功能,以及行動 Driver SDK 和後端 JWT 驗證。請改用 Fleet Engine Service。

Maps JavaScript API:設定

官方 Maps JavaScript API 套件:

  • npm:@googlemaps/js-api-loader
  • npm:@types/google.maps
  • npm:@googlemaps/markerclusterer

Maps JavaScript API:常見錯誤

  • 問題:API 金鑰或帳單設定錯誤時,系統不會顯示錯誤訊息,而是顯示顏色較深的地圖或負片效果的街景服務圖像,並加上「僅供開發使用」圖片浮水印。修正方式:啟用雲端專案的計費功能、在每項要求中加入有效的 API 金鑰,並查看瀏覽器控制台中的特定錯誤代碼。請參閱 /maps/documentation/javascript/error-messages。
  • 問題:PlacesService、DirectionsService 和 DistanceMatrixService 等舊版服務會在未啟用舊版 API 的新專案中擲回 LegacyApiNotActivatedMapError。修正方式:改用 Places API (新版) 和 Routes API 支援的新版對等項目 (Place 類別、Route 類別、RouteMatrix 類別)。請參閱 /maps/legacy#LegacyApiNotActivatedMapError。
  • 問題:自 3.65 版起,衛星和混合地圖不再切換至 45° 圖像,且 map.setTilt(45) 沒有作用。修正方式:改用 3D 地圖,不要使用 45° 圖像。詳情請參閱 /maps/deprecations。
  • 問題:進階標記需要地圖 ID,因此未建立地圖 ID 的地圖無法使用 AdvancedMarkerElement。修正方式:在 Cloud 控制台中建立地圖 ID (或使用 DEMO_MAP_ID 進行測試),並在地圖上設定 mapId。請參閱 /maps/documentation/javascript/advanced-markers/start。

Maps JavaScript API:舊版和已淘汰的功能

  • Directions Service (google.maps.DirectionsService):自 2025 年 3 月 1 日起,舊版。替代方案:Route 類別。症狀:專案未啟用舊版 Directions API,卻出現 LegacyApiNotActivatedMapError。請參閱遷移指南。
  • 距離矩陣 Service (google.maps.DistanceMatrixService):自 2025 年 3 月 1 日起為舊版。替代方案:RouteMatrix 類別。症狀:在未啟用舊版 Distance Matrix API 的專案中,LegacyApiNotActivatedMapError。請參閱遷移指南。
  • Places Service (google.maps.places.PlacesService):自 2025 年 3 月 1 日起,舊版。替代方案:Place 類別 (Places API (新版))。症狀:在未啟用舊版 Places API 的專案中,LegacyApiNotActivatedMapError。請參閱遷移指南。
  • google.maps.Marker:自 2024 年 2 月 22 日起淘汰。替代方案:google.maps.marker.AdvancedMarkerElement。症狀:仍可運作,且未排定停止,但不會修正現有錯誤。請參閱遷移指南。
  • KmlLayer:自 2026 年 4 月 30 日起淘汰。替代方案:資料集的資料導向樣式,或搭配資料層使用第三方 KML 剖析器。症狀:3.66 以上版本不支援 KmlLayer;3.65 版是支援該功能的最後版本,將於 2027 年 5 月停用。請參閱遷移指南。
  • 熱視圖圖層 (視覺化程式庫):2026 年 5 月 20 日起停用。替代方案:deck.gl HeatmapLayer 等第三方程式庫。症狀:2026 年 5 月起停用。請參閱遷移指南。
  • 繪圖程式庫:自 2026 年 6 月 4 日起停用。替代方案:Terra Draw。症狀:2026 年 5 月起停用。請參閱遷移指南。
  • 45° 圖像:自 2026 年 5 月 20 日起停用。替代方案:3D 地圖。症狀:map.setTilt(45) 無效,衛星檢視仍維持由上而下的視角。請參閱遷移指南。
  • google.maps.event.addDomListener() 和 addDomListenerOnce():自 2022 年 4 月 7 日起淘汰。替代方案:標準 DOM addEventListener()。
  • Place Autocomplete 服務中的 bounds、location 和 radius 選項:2023 年 5 月 18 日起已淘汰。替代方案:locationBias 和 locationRestriction。
  • Places UI Kit 中的 gmp-place-content-config (PlaceContentConfigElement):已淘汰。替代方案:直接在 Place Details 元素或 Place Search 設定中加入內容元素。
  • 當地特色資料庫:已停用。替代方案:Places Library。

Maps JavaScript API 的用途

請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。

Maps JavaScript API:地址驗證

Maps JavaScript API:界線資料導向樣式

Maps JavaScript API:資料集資料導向樣式

Maps JavaScript API:資料集

  • 在地圖中新增 KML 圖層。注意:Maps JavaScript API 已淘汰 KmlLayer (最後支援版本為 3.65,2027 年 5 月停用);請改用邊界或資料集的資料導向樣式,或在資料層載入 GeoJSON。Android 和 iOS 仍可透過 Maps SDK 公用程式庫支援 KML 圖層。
  • 在地圖中加入 GeoRSS 圖層。注意:Maps JavaScript API 已淘汰這項功能 (KmlLayer 最後支援的版本為 3.65,將於 2027 年 5 月停用);請將 GeoRSS 動態饋給轉換為 GeoJSON,並使用 map.data.addGeoJson() 載入資料層。
  • 在地圖中加入 GeoJSON 資料。

Maps JavaScript API:路線和路徑規劃

Maps JavaScript API:海拔

Maps JavaScript API:Fleet Engine

Maps JavaScript API:地理編碼

Maps JavaScript API:地圖

Maps JavaScript API:地圖註解

Maps JavaScript API:地圖樣式設定

Maps JavaScript API:其他

Maps JavaScript API:擬真 3D 地圖

Maps JavaScript API:地點

Maps JavaScript API:Places UI Kit

  • 在網頁或行動應用程式中,新增 UI 元素,顯示特定地點的 AI 輔助摘要和評論。注意:僅支援網頁 (Maps JavaScript API Places UI Kit);行動 Places UI Kit 不含 AI 摘要元素。歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請使用 Maps JavaScript API 中的用戶端 Places UI Kit 元件,而非從後端伺服器呼叫 Places API Web 服務。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 將 CSS 樣式套用至地點資料 UI 元素。注意:CSS 自訂屬性適用於 Maps JavaScript API Places UI Kit 元素;Places SDK for Android 和 Places SDK for iOS 則會使用主題和樣式屬性,以程式輔助方式設定 Place UI Kit 檢視區塊的樣式。歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API Web 服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 使用 UI 元素自訂工具,自訂地點資料 UI 元素的樣式和設定。注意:歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API Web 服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 在網頁或行動應用程式中,新增顯示特定地點資訊的 UI 元素。注意:歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API 網路服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 在網頁中新增 UI 元素,根據查詢字串顯示地點清單。注意:網頁 (Maps JavaScript API) 和行動應用程式 (Places SDK for Android 和 Places SDK for iOS) 皆支援。歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API Web 服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 在網頁中加入 UI 元素,顯示特定位置附近的地點清單。注意:網頁 (Maps JavaScript API) 和行動應用程式 (Places SDK for Android 和 Places SDK for iOS) 皆支援。歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API Web 服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq
  • 在網頁或應用程式中加入基本的自動完成 UI 元素,根據查詢字串傳回 Google 地點 ID。注意:歐洲經濟區法規遵循規定:如要在歐洲經濟區 (EEA) 的地圖上顯示地點資料,請勿從後端伺服器呼叫 Places API Web 服務。在目標平台上使用用戶端 Places UI Kit 元件 (網頁版 Maps JavaScript API、Android 版 Places SDK for Android,或 iOS 版 Places SDK for iOS)。完整規定和常見問題:https://developers.google.com/maps/comms/eea/faq

Maps JavaScript API:街景服務