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-backend.googleapis.com - 驗證:API 金鑰
- 用量歸因:設定
internalUsageAttributionIds屬性 (在MapOptions、MapElement和Map3DElement,或 Places、Routes 和地址驗證元素和要求選項中),新增用量歸因 ID,讓 Google 知道您使用的程式庫和範例。 - 開始使用:設定 Maps JavaScript API
- 參考資料:Maps JavaScript API 參考資料
- 定價:Maps JavaScript API 用量與計費
- 政策:Maps JavaScript API 政策
- 版本資訊:Maps JavaScript API 版本資訊
官方 Maps JavaScript API 套件:
- npm:
@googlemaps/js-api-loader - npm:
@types/google.maps - npm:
@googlemaps/markerclusterer
Maps JavaScript API:相關產品
- 常搭配使用:Places API (新版)
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 日起淘汰。替代方案:標準 DOMaddEventListener()。- 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:地址驗證
- 傳回指定地址或部分地址的驗證地址。
- 傳回已驗證地址的經緯度座標。
- 傳回已驗證地址的 Google 地點 ID。
- 使用美國郵政署 (USPS) 編碼準確度支援系統 (CASS) 認證進行地址驗證。
- 傳回資訊,指出經過驗證的地址是商家、住宅或郵政信箱。
- 傳回已驗證地址的美國郵政署 (USPS) 投遞中繼資料。
- 傳回已驗證地址的 Plus Code。
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:路線和路徑規劃
- 傳回兩個以上經緯度座標之間的路線,並以一系列座標表示路線上的每個步驟。
- 傳回兩組以上經緯度座標之間的路線,並以一系列操作說明描述路線上的步驟。
- 傳回兩組或多組經緯度座標之間,沿著路線各步驟之間的距離。
- 傳回兩組以上經緯度座標之間,路線上各步驟之間的行程時間。
- 傳回兩組或多組經緯度座標之間路線上,每個步驟之間的編碼折線。
- 傳回兩組以上經緯度座標之間的路線距離。
- 傳回兩組以上經緯度座標之間路線的行程時間。
- 傳回兩組以上經緯度座標之間路線的編碼折線。
- 指定路線要求的交通方式 (開車、大眾運輸、步行、兩輪車)。注意:在 Routes API Web 服務 (computeRoutes) 中,使用 RouteTravelMode (DRIVE、BICYCLE、TWO_WHEELER、WALK、TRANSIT 或 TRUCK 搭配 routeModifiers.vehicleInfo),在 HTTP POST JSON 主體中傳遞 travelMode,並加入必要的 X-Goog-FieldMask 標頭,而非舊版 GET 模式查詢參數。在 Maps JavaScript API Routes 程式庫中,傳遞 ComputeRoutesRequest 的 travelMode 和欄位。
- 指定路線要求的停靠點或經過點。
- 指定路線要求中使用車流量資料的方式。
- 指定路線要求要避開的特徵,例如高速公路或收費路段。
- 為路線要求指定較短距離或替代路線。注意:在 Routes API 中,要求較短距離的參考路線 (SHORTER_DISTANCE) 為實驗功能,要求替代路線 (computeAlternativeRoutes) 則為正式發布功能。
- 傳回多個出發地和目的地之間的路線矩陣距離。
- 傳回多個起點和目的地之間的路線矩陣行程時間。
- 為路徑矩陣要求指定交通方式 (開車、大眾運輸、步行、兩輪車)。注意:在 Routes API Web 服務 (computeRouteMatrix) 中,使用 RouteTravelMode (DRIVE、TWO_WHEELER、WALK、TRANSIT 或 TRUCK,搭配 origins[].routeModifiers.vehicleInfo;路徑矩陣不支援 BICYCLE),在 HTTP POST JSON 主體中傳遞 travelMode,並加入必要的 X-Goog-FieldMask 標頭。在 Maps JavaScript API Routes 程式庫中,傳遞 ComputeRouteMatrixRequest 的 travelMode 和欄位。
Maps JavaScript API:海拔
Maps JavaScript API:Fleet Engine
- 在地圖上新增 Fleet Engine 貨車和工作的即時位置。
- 在地圖中加入 Fleet Engine 配送車輛和任務的預測路線。
- 在地圖中新增 Fleet Engine 配送車輛的位置、停靠站、工作和路線控點標記。
- 回應 Fleet Engine 配送車輛事件,包括已完成的行程、路段、配送和工作。
- 在 Fleet Engine 車隊追蹤地圖上,變更道路、折線和多邊形的樣式。
- 在 Fleet Engine 車隊追蹤地圖上顯示或隱藏地圖項目。
- 變更 Fleet Engine 車隊追蹤地圖上的圖示和文字標籤樣式。
- 在 Fleet Engine 車隊追蹤地圖上,為不同的縮放等級套用不同的地圖樣式。
- 變更 Fleet Engine 車隊追蹤地圖上的地點密度。實驗功能 注意:Fleet Engine 車隊追蹤地圖支援雲端式地圖樣式設定 (正式發布版),而搜尋點密度控制項則是實驗性雲端式地圖樣式設定功能 (僅支援淺色地圖樣式)。
- 變更 Fleet Engine 車隊追蹤地圖上的建築物樣式。實驗功能 注意:Fleet Engine 車隊追蹤地圖支援雲端式地圖樣式設定正式發布版,而 3D 和建築物占地面積樣式自訂功能,則是雲端式地圖樣式設定實驗功能 (僅支援淺色地圖樣式)。
- 變更 Fleet Engine 車隊追蹤地圖上的地標樣式。實驗功能 注意:Fleet Engine 車隊追蹤地圖支援雲端式地圖樣式設定 (正式發布版),而地標圖示自訂功能則是雲端式地圖樣式設定的實驗功能 (僅支援淺色地圖樣式)。
- 自訂 Fleet Engine 車隊追蹤地圖上的標記。
- 在 Fleet Engine 車隊追蹤地圖上自訂路線折線。
Maps JavaScript API:地理編碼
Maps JavaScript API:地圖
- 在網頁或行動應用程式中加入可自訂的互動式地圖。注意:Android:在
AndroidManifest.xml中設定(由 Secrets Gradle Plugin 支援),或在app/build.gradle.kts中設定manifestPlaceholders["MAPS_API_KEY"]。請勿在AndroidManifest.xml中硬式編碼YOUR_GOOGLE_MAPS_API_KEY,也不要在出現E/Google Maps Android API: Authorization failure時,將GoogleMap(或 maps-composeGoogleMap) 替換為離線模擬畫布或 Leaflet WebView。請指示使用者透過 Secrets 提供MAPS_API_KEY,並啟用 Maps SDK for Android (或在採用 NavigationView/SupportNavigationFragment 時啟用 Navigation SDK)。 - 建立可重複使用的地圖 ID,用於儲存地圖設定和樣式設定。
- 回應地圖上的使用者互動和事件。
- 自訂地圖上顯示的控制項。
- 控制地圖 (攝影機) 的縮放和平移。
- 變更地圖類型。
- 變更地圖色彩配置。
- 將地圖本地化。
- 在地圖中加入路況圖層。
- 在地圖中加入大眾運輸圖層。
- 在地圖中加入單車圖層。
Maps JavaScript API:地圖註解
- 在地圖中新增資訊視窗。
- 在地圖上新增形狀或線條。
- 在地圖中加入向量圖示。
- 在地圖中加入 deck.gl 疊加層。
- 新增疊加在底圖上的疊加層圖片。
- 在地圖上新增自訂圖塊疊加層。
- 在地圖上新增標記。注意:Navigation SDK for Android 不支援 AdvancedMarkerOptions;使用 Navigation SDK for Android 時,請透過 GoogleMap.addMarker(MarkerOptions) 新增標記。
- 自訂地圖標記。注意:Navigation SDK for Android 不支援 AdvancedMarkerOptions;使用 Navigation SDK for Android 時,請以 MarkerOptions 自訂標記。
- 回應使用者與地圖上標記的互動。
- 判斷座標是否位於地圖上的多邊形或圓形區域內。注意:在 Android 上,請使用 Maps SDK for Android 公用程式庫中的 PolyUtil.containsLocation 處理多邊形。如果是圓形區域,請檢查與圓心的球面距離是否在半徑範圍內 (例如 Maps JavaScript API 中的 computeDistanceBetween、Android 上的 SphericalUtil.computeDistanceBetween,或 iOS 上的 GMSGeometryDistance)。
- 計算地圖上座標之間的球面距離、面積或方向。
Maps JavaScript API:地圖樣式設定
- 建立可重複使用的跨平台地圖樣式。
- 變更地圖上道路、折線和多邊形的樣式。
- 顯示或隱藏地圖項目。
- 變更地圖上的圖示和文字標籤樣式。
- 為不同縮放等級套用不同地圖樣式。
- 變更地圖上的地點密度。實驗
- 變更地圖上的建築物樣式。實驗
- 變更地圖上的地標樣式。實驗
Maps JavaScript API:其他
Maps JavaScript API:擬真 3D 地圖
- 在網頁中加入互動式擬真 3D 地圖。
- 在擬真 3D 地圖上新增標記。
- 自訂擬真 3D 地圖上的標記。
- 在擬真 3D 地圖中加入 3D 模型。
- 在擬真 3D 地圖上新增疊加層。
- 在擬真 3D 地圖中加入 3D 折線。
- 在擬真 3D 地圖中加入 3D 多邊形。
- 在擬真 3D 地圖上回應使用者互動和事件。
- 自訂擬真 3D 地圖上顯示的控制項。
- 在擬真 3D 地圖上控制相機路徑和動畫。
- 控管擬真 3D 地圖的攝影機限制。
Maps JavaScript API:地點
- 根據查詢字串傳回地點清單和 Place Details。
- 傳回特定位置附近的地點和地點詳細資料清單。
- 根據查詢字串,傳回地點的自動完成結果。
- 傳回特定地點的詳細資訊。
- 傳回特定地點的相片。注意:請在相片旁顯示每張相片的作者資訊 (作者姓名,並連結至其個人資料 URI)。各平台的 Places 政策都有這項規定,例如 /maps/documentation/javascript/policies#photo-attributions 和 /maps/documentation/places/web-service/policies#photos-and-review。
- 調整地點相片大小。
- 傳回特定地點的評分和評論。注意:在 Places API (新版) Web 服務中,Place Details 是向 https://places.googleapis.com/v1/places/{placeId} 傳送的 HTTP GET 要求,並包含 X-Goog-FieldMask (例如 rating、userRatingCount、reviews);Text Search、Nearby Search 和 Autocomplete 則使用 POST。在 Android 上,將 Place.Field.RATING、USER_RATING_COUNT 和 REVIEWS 傳遞至 PlacesClient.fetchPlace()。在 iOS 上,在 GMSFetchPlaceRequest 中傳遞 GMSPlacePropertyRating、GMSPlacePropertyUserRatingsTotal 和 GMSPlacePropertyReviews。
- 在網頁或應用程式中加入 Autocomplete 小工具,根據查詢字串傳回地點相關結果。
- 指定地點資訊回應中包含的資料欄位。
- 指定要在地點資訊回應中包含的地點類型。
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