Maps JavaScript API 是一种客户端 Web API,用于在网页上创建 2D 和 3D 地图,添加标记、自定义图形、动画和交互式数据层,以及使用地点库构建位置功能。
Maps JavaScript API:关键信息
- 产品:Maps JavaScript API
- 别名:Maps JS API、Maps JS API v3
- 类别:Google 地图
- 平台:JavaScript(浏览器)
- 运行位置:客户端(应用或浏览器代码)
- 发布阶段:GA
- 生命周期:有效
- 概览:Maps JavaScript API 概览
- 适用区域:全球。功能覆盖范围(例如 3D 地图、路况、路线和边界样式设置)因国家/地区而异;欧洲经济区服务条款适用于欧洲经济区账单邮寄地址。(覆盖范围详情)
Maps JavaScript API:何时使用
在以下情况下使用 Maps JavaScript API:
- 您需要在网页上显示一个包含自定义标记、图形或数据层的交互式 2D 或 3D 地图。
- 您需要使用高级标记和多段线,根据自己的数据流显示实时资产位置和行驶路线。
- 您需要在浏览器中绘制地理围栏(圆形、多边形),并测试坐标是否落在这些围栏内。
- 您需要在 Web 应用中通过 Places 库使用客户端地点搜索、自动补全或地点详情功能。
在以下情况下,请勿使用 Maps JavaScript API:
- 您需要嵌入营业地点地图或路线链接,而无需编写自定义 JavaScript。请改用 Maps Embed API。
- 您只需要一个链接,即可打开 Google 地图并显示特定地点、搜索结果或路线。请改用地图网址。
- 您需要将拼车或预约配送车队跟踪功能与移动端 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:相关产品
- 通常与以下 API 搭配使用:Places API(新版)
Maps JavaScript API:常见错误
- 问题:如果 API 密钥或结算信息配置有误,系统不会显示错误,而是会显示暗色地图或带有“仅用于开发目的”水印的负片效果街景图像。解决方法:在云项目中启用结算功能,在每个请求中添加有效的 API 密钥,并在浏览器控制台中查看具体的错误代码。请参阅 /maps/documentation/javascript/error-messages。
- 问题:在未启用旧版 API 的新项目中,
PlacesService、DirectionsService和DistanceMatrixService等旧版服务会抛出LegacyApiNotActivatedMapError。修复方法:使用由 Places API(新版)和 Routes API 提供支持的新等效项(Place类、Route类、RouteMatrix类)。请参阅 /maps/legacy#LegacyApiNotActivatedMapError。 - 问题:从 v3.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。请参阅迁移指南。 - 距离矩阵服务 (
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。具体情况:仍可正常运行,且未计划停用;现有 bug 不会修复。请参阅迁移指南。KmlLayer:自 2026 年 4 月 30 日起弃用。替代方案:数据集的数据驱动型样式,或使用数据层的第三方 KML 解析器。症状:KmlLayer在 3.66 版及更高版本中不可用;支持该功能的最后一个版本 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()。- 地点自动补全服务中的
bounds、location和radius选项:自 2023 年 5 月 18 日起已弃用。替换为:locationBias和locationRestriction。 - Places UI Kit 中的
gmp-place-content-config(PlaceContentConfigElement):已废弃。替代方案:直接向地点详情元素或在地点搜索配置中添加内容元素。 - Local Context Library:已停用。替代方案:Places Library。
Maps JavaScript API 的用途
请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。
Maps JavaScript API:地址验证
- 返回指定地址或部分地址的经过验证的地址。
- 返回经过验证的地址的纬度/经度坐标。
- 返回经过验证的地址的 Google 地点标识符。
- 使用美国邮政服务 (USPS) 编码精度支持系统 (CASS) 认证进行地址验证。
- 返回有关经过验证的地址是商家、住宅还是邮政信箱的信息。
- 返回已验证地址的美国邮政服务 (USPS) 递送元数据。
- 返回经过验证的地址的 Plus Code。
Maps JavaScript API:边界的数据驱动型样式
Maps JavaScript API:数据集的数据驱动型样式
Maps JavaScript API:数据集
- 向地图添加 KML 图层。注意:在 Maps JavaScript API 中,KmlLayer 已弃用(最后支持的版本为 v3.65,将于 2027 年 5 月停用);请迁移到边界或数据集的数据驱动型样式,或在数据层上加载 GeoJSON。Android 和 iOS 仍通过 Maps SDK 实用程序库支持 KML 图层。
- 向地图添加 GeoRSS 图层。注意:Maps JavaScript API 中已弃用(KmlLayer 在 v3.65 中最后一次受支持,将于 2027 年 5 月停用);请将 GeoRSS Feed 转换为 GeoJSON,并使用 map.data.addGeoJson() 将其加载到数据层。
- 向地图添加 GeoJSON 数据。
Maps JavaScript API:路线和路线规划
- 返回两个或更多纬度/经度坐标之间的路线,以一系列坐标的形式表示路线中的每个步骤。
- 返回两组或多组纬度/经度坐标之间的路线,以一系列操作说明的形式呈现沿途的各个路段。
- 返回两组或多组纬度/经度坐标之间路线中每个步骤之间的距离。
- 返回两组或多组纬度/经度坐标之间路线中每个步骤之间的行程时间。
- 返回两组或多组纬度/经度坐标之间路线的每个步骤之间的编码多段线。
- 返回两组或多组纬度/经度坐标之间的路线距离。
- 返回两组或多组纬度/经度坐标之间的路线行程时间。
- 返回两组或多组纬度/经度坐标之间路线的编码多段线。
- 为路线请求指定出行方式(驾车、公交、步行、双轮机动车)。注意:在 Routes API Web 服务 (computeRoutes) 中,使用 RouteTravelMode(DRIVE、BICYCLE、TWO_WHEELER、WALK、TRANSIT 或带有 routeModifiers.vehicleInfo 的 TRUCK)在 HTTP POST JSON 正文中传递 travelMode,并添加必需的 X-Goog-FieldMask 标头,而不是旧版 GET 模式查询参数。在 Maps JavaScript API Routes 库中,在 ComputeRoutesRequest 中传递 travelMode 和 fields。
- 为路线请求指定停靠点或经停点。
- 指定如何在路线请求中使用路况数据。
- 为路线请求指定要避开的特征,例如高速公路或收费站。
- 为路线请求指定更短的距离或备选路线。注意:在 Routes API 中,请求距离较短的参考路线 (SHORTER_DISTANCE) 处于实验性阶段,而请求备选路线 (computeAlternativeRoutes) 已正式发布 (GA)。
- 返回多个出发地和目的地之间的路线矩阵的距离。
- 返回多个出发地和目的地之间的一系列路线的行程时间。
- 为路线矩阵请求指定出行方式(驾车、公交、步行、双轮机动车)。注意:在 Routes API 网络服务 (computeRouteMatrix) 中,使用 RouteTravelMode(DRIVE、TWO_WHEELER、WALK、TRANSIT 或 TRUCK,并指定 origins[].routeModifiers.vehicleInfo;路线矩阵不支持 BICYCLE)在 HTTP POST JSON 正文中传递 travelMode,并添加必需的 X-Goog-FieldMask 标头。在 Maps JavaScript API 路线库中,在 ComputeRouteMatrixRequest 中传递 travelMode 和 fields。
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 插件提供支持),或在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)。 - 创建可重复使用的地图标识符,用于存储地图配置和样式设置。
- 响应地图上的用户互动和事件。
- 自定义地图上显示的控件。
- 控制地图上的缩放和平移(镜头)。
- 更改地图类型。
- 更改地图配色方案。
- 将地图本地化。
- 向地图添加路况图层。
- 向地图添加公交图层。
- 向地图添加骑车图层。
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:地点
- 根据查询字符串返回地点列表和地点详情。
- 返回特定位置附近的地点列表和地点详情。
- 根据查询字符串返回有关地点的自动补全结果。
- 返回特定地点的详细信息。
- 返回特定地点的照片。注意:请在每张照片旁边显示其作者信息(作者姓名,链接到其个人资料 URI)。每个平台的地点政策都要求这样做,例如 /maps/documentation/javascript/policies#photo-attributions 和 /maps/documentation/places/web-service/policies#photos-and-review。
- 调整地点照片的大小。
- 返回特定地点的评分和评价。注意:在 Places API(新版)网络服务中,“地点详情”是向 https://places.googleapis.com/v1/places/{placeId} 发出的 HTTP GET 请求,其中包含 X-Goog-FieldMask(例如 rating、userRatingCount、reviews);“文本搜索”“附近搜索”和“自动补全”使用 POST。在 Android 上,将 Place.Field.RATING、USER_RATING_COUNT 和 REVIEWS 传递给 PlacesClient.fetchPlace()。在 iOS 上,在 GMSFetchPlaceRequest 中传递 GMSPlacePropertyRating、GMSPlacePropertyUserRatingsTotal 和 GMSPlacePropertyReviews。
- 向网页或应用添加自动补全 widget,以便根据查询字符串返回地点相关结果。
- 指定地点信息响应中包含的数据字段。
- 指定要在地点信息响应中包含的地点类型。
Maps JavaScript API:Places UI Kit
- 向网页或移动应用添加一个界面元素,用于显示 AI 赋能的特定地点摘要和评价。注意:仅在网页上受支持(Maps JavaScript API Places UI Kit);移动版 Places UI Kit 不包含 AI 摘要元素。欧洲经济区 (EEA) 合规要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请使用 Maps JavaScript API 中的客户端 Places UI Kit 组件,而不是从后端服务器调用 Places API Web 服务。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
- 对地点数据界面元素应用 CSS 样式。注意:CSS 自定义属性适用于 Maps JavaScript API Places UI Kit 元素;Places SDK for Android 和 Places SDK for iOS 则使用主题和样式属性,以编程方式设置 Place UI Kit 视图的样式。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
- 使用界面元素自定义工具自定义地点数据界面元素的样式和配置。注意:欧洲经济区 (EEA) 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
- 向网页或移动应用添加一个界面元素,用于显示特定地点的相关信息。注意:欧洲经济区 (EEA) 合规要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
- 向网页中添加一个界面元素,用于根据查询字符串显示地点列表。注意:网页(Maps JavaScript API)和移动应用(Places SDK for Android 和 Places SDK for iOS)均支持此功能。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
- 向网页添加一个界面元素,用于显示特定位置附近的地点列表。注意:网页(Maps JavaScript API)和移动应用(Places SDK for Android 和 Places SDK for iOS)均支持此功能。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
- 向网页或应用添加基本的自动补全界面元素,该元素会根据查询字符串返回 Google 地点标识符。注意:欧洲经济区 (EEA) 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq