在当今位置感知型世界中，用户希望能够顺畅地访问地点信息、路线和导航信息。无论是通过即时通讯应用、本地情境发现应用、物流和交通平台、旅行规划工具还是房地产信息平台，用户通常都需要快速查看位置详情或查找从 A 到 B 的最佳路线。虽然开发者可以构建自己的应用内体验，但利用 Google 地图全面且熟悉的界面可以提供更出色的体验。
为了提供顺畅的用户体验，结构良好的 Google 地图网址至关重要。 不正确的网址会破坏这种体验，将用户定向到错误的位置、显示常规地图视图而非具体详细信息，甚至导致链接损坏。这会让用户感到沮丧，并阻止他们实现目标。 例如，即使用户使用的是有效的 Google 地图网址，但如果他们希望查看特定商家的详细信息，却可能会跳转到没有相关信息的一般地图视图。请参阅下面的示例：
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152
此 Google 地图网址可用于打开 Google 地图并根据经纬度显示位置。不过，它不会向用户提供特定地点的详细信息。
通过准确的网址将您的应用与 Google 地图无缝关联
Google Maps Platform (GMP) 提供了两种主要方法来构建准确的网址：需要 API 密钥的 Places API（新版），以及免费且无需密钥的地图网址。以下解决方案可针对不同的场景和用例提供帮助：
使用 GMP Places API（新版）的 googleMapsUri 或 googleMapsLinks 字段
GMP Places API（新） 会返回有关特定地点的一组全面信息。请求 googleMapsUri 或 googleMapsLinks 字段（通过在字段掩码中指定）时，API 响应中会包含地点对象。此对象包含预格式化的网址，可用于直接在 Google 地图中打开相应的视图（例如地点详情视图）。
示例：
“地点详情”请求
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: YOUR_API_KEY" \ -H "X-Goog-FieldMask: googleMapsUri,googleMapsLinks" \ https://places.googleapis.com/v1/places/ChIJ3S-JXmauEmsRUcIaWtf4MzE
地点详情响应：
{
"googleMapsUri": "https://maps.google.com/?cid=3545450935484072529",
"googleMapsLinks": {
"directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!3e0",
"placeUri": "https://maps.google.com/?cid=3545450935484072529",
"writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!12e1",
"reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!9m1!1b1",
"photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!10e5"
}
}在上面的示例中，ChIJ3S-JXmauEmsRUcIaWtf4MzE 是悉尼歌剧院的地点 ID。地点 ID 是唯一标识 Google 地点数据库中和 Google 地图上的地点的文本标识符。
免费检索地点 ID
如需以编程方式检索地点 ID，您可以使用 Places API：文本搜索（仅限 ID）功能。这是获取地点 ID 的免费方法。详细了解地点 ID 和 Place API（新） 请求。
Places API 文本搜索（仅 ID）请求：
curl -X POST -d '{"textQuery" : "Sydney Opera House"}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'Places API 文本搜索（仅 ID）响应：
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}当用户点击或点按地图上的地图注点时，也可以检索地点 ID。详细了解可点击的地图注点图标(JavaScript、Android、iOS)
实现
使用 Places API 时，开发者只需从响应中提取 googleMapsUri 或 googleMapsLinks 字段，然后使用该字段在 Google 地图应用中或浏览器中（如果未安装该应用）启动相应视图即可。
| 功能 | 说明 |
|---|---|
| directionsUri | 用于打开 Google 地图的链接，以显示从用户当前位置到此地点的路线 |
| placeUri | 指向 Google 地图中相应地点详情页面的链接 |
| writeAReviewUri | 指向 Google 地图中用于撰写此地点评价的页面的链接 |
| reviewsUri | 用于在 Google 地图中打开此地点评价页面的链接 |
| photosUri | 用于在 Google 地图中打开此地点的照片页面的链接 |
查看开发者指南，立即试用此功能。
使用 Google 地图网址
利用地图网址，您可以构建一个跨平台通用网址，以启动 Google 地图、执行搜索、获取路线和导航，以及显示地图视图和全景图片。无论使用的平台如何，网址语法都是相同的。您无需 Google API 密钥即可使用 Google 地图网址。
可用的地图操作包括：
搜索功能会启动 Google 地图应用（如果未安装该应用，则会在浏览器中启动），显示特定地点的图钉，或执行常规搜索并启动地图来显示结果。
路线功能会启动 Google 地图应用，如果未安装用于显示点对点路线或在移动设备上启用 Google 地图精细导航的应用，则会在浏览器中启动。
借助街景全景图片功能，您可以启动查看器，以交互式全景图片的形式显示街景图片。
如需探索更多函数和示例，请参阅 GMP 地图网址开发者文档。
下面详细介绍了 Google 地图网址的两项关键功能：
在 Google 地图上显示地点详情：本部分介绍了如何构建网址，以便在 Google 地图上显示特定地点的详细信息。其中还详细介绍了如何使用地点 ID 和精确查询处理名称不唯一的地点。
使用 Google 地图网址提供路线：本部分介绍了如何创建用于提供地点之间路线的网址，包括包含多个路点和精细导航的路线。
在 Google 地图上显示地点详情
Search 函数接受两个参数来完成地点搜索，这两个参数分别是 query（必需）和 query_place_id（可选）。
所有搜索请求都必须包含 query 参数。它接受地点名称、逗号分隔的经纬度坐标或一般搜索字词。
搜索网址结构：
https://www.google.com/maps/search/?api=1¶meters
场景 1：显示具有唯一地名的地点详情
https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House
现在，假设某个地点的名称不唯一。如果您仅按此非唯一名称进行搜索，会出现什么情况？请参阅下一个场景。
场景 2：搜索地点以查找非唯一地名
https://www.google.com/maps/search/?api=1&query=7-Eleven
由于地点名称不唯一，因此此网址会在视口中打开附近 7-Eleven 商店的列表。然后，用户可以选择特定商店来查看其详细信息。
如需避免显示位置列表并直接访问特定详情页面，您可以使用更精确的方法。请参阅下一个示例。
场景 3：显示非唯一地名的地点详情
处理常见地名时，简单的名称搜索通常会返回一个地点列表。如需直接链接到特定详情页面，您可以使用以下方法之一：
方法 1：使用包含地点名称和地址的精确查询
https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia
在此网址中，query 参数的格式为地点名称、地址。这有助于缩小搜索范围，并直接链接到预期位置。
方法 2：使用地点 ID
地点 ID 可唯一标识 Google 地点数据库中和 Google 地图上的地点。
https://www.google.com/maps/search/?api=1&query=7-Elevan&query_place_id=ChIJGcmcg7ZC1moRAOacd3HoEwM
其中，ChIJGcmcg7ZC1moRAOacd3HoEwM 是特定地点的唯一地点 ID。query 参数仍然是必需的，但只有在 Google 地图找不到地点 ID 时才会使用。
场景 4：使用纬度和经度坐标以及地点 ID 显示地点详情
使用地点 ID 可确保 Google 地图显示详细的地点信息。
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE
免费检索地点 ID
如需以编程方式检索地点 ID，您可以使用 Places API：文本搜索（仅限 ID）功能。这是获取地点 ID 的免费方法。详细了解地点 ID 和 Place API（新版） 请求。
Places API 文本搜索（仅 ID）请求：
curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'Places API 文本搜索（仅 ID）响应：
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}当用户点击或点按地图上的地图注点时，也可以检索地点 ID。详细了解可点击的地图注点图标(JavaScript、Android、iOS)
总结
提供准确的地点详情对打造良好体验至关重要。为确保用户到达正确的地点详情页面，请使用以下推荐格式之一构建搜索网址：
query=PLACE_NAME, ADDRESSquery=PLACE_NAME&query_place_id=PLACE_ID
如果您的目标是显示特定地点的详细信息，请避免在 query 参数中仅使用纬度/经度坐标。query=latitude,longitude、query=PLACE_NAME,latitude,longitude 或 query=ADDRESS,latitude,longitude 等格式无法始终跳转到所需的地点详情页面。而是会显示相应位置的纬度和经度。
使用 Google 地图网址进行分类搜索
在分类搜索中，您传递一个常规搜索字词，Google 地图会尝试在您指定的地点附近查找符合您条件的商家信息。如果未指定位置，Google 地图会尝试查找您当前位置附近的商家信息。
场景 1：附近地点搜索
https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now
使用 Google 地图网址提供路线
“路线”功能会在地图上显示两个或多个指定地点之间的路径，以及距离和行程时间。它让开发者可以更好地控制所提供的路线。GMP 的 Google 地图网址导航文档详细介绍了如何构建自定义导航的网址。
路线网址结构：
https://www.google.com/maps/dir/?api=1¶meters
场景 1：查找从用户当前位置到目的地的最佳路线
https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving
此网址会打开 Google 地图，并显示从用户当前位置出发的驾车路线。
在此网址中，省略了 origin。如果省略 origin，则路径默认为最相关的起始位置，例如设备位置（如果有）。如果没有，生成的地图会提供一个表单，供用户输入起点。
起点和终点的值可以是地点名称、地址或以英文逗号分隔的纬度/经度坐标。
travelmode 是可选参数。它定义了旅行方式。此参数的设置如下：
- 驾车
- 步行
- 骑车
- 双轮机动车
- transit
如果未指定 travelmode，Google 地图会显示与指定路线和/或用户偏好设置最相关的一个或多个模式。
开发者还可以使用 origin_place_id 参数和 destination_place_id 指定地点 ID。使用地点 ID 是确保您关联到正确地点的最佳方式。
免费检索地点 ID
如需以编程方式检索地点 ID，您可以使用 Places API：文本搜索（仅限 ID）功能。这是获取地点 ID 的免费方法。详细了解地点 ID 和 Place API（新版） 请求。
Places API 文本搜索（仅 ID）请求：
curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'Places API 文本搜索（仅 ID）响应：
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}当用户点击或点按地图上的地图注点时，也可以检索地点 ID。详细了解可点击的地图注点图标(JavaScript、Android、iOS)
场景 3：提供精细导航
https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate
如果用户的当前位置（设备位置）可用且用作起点（在省略起点参数时，显式提供或隐式使用），在网址中设置 dir_action=navigate 将以精细导航模式启动 Google 地图。否则，系统会显示路线预览。
设置 dir_action=navigate 且满足以下条件时，系统会启动精细导航：
- 已指定来源，且该来源靠近用户的当前位置
- 省略了来源，并提供用户的当前位置
在以下情况下，系统会启动路线预览：
- 未设置
dir_action=navigate - 已设置
dir_action=navigate并指定了来源，但来源距离用户的当前位置较远 - 设置了
dir_action=navigate并省略了来源，并且无法获取用户的当前位置
请注意，导航功能并非适用于所有 Google 地图产品（例如 Google 地图网页版），也并非适用于所有目的地。在这种情况下，此参数将被忽略。
 |
 |
总结
通过正确构建 Google 地图网址，您可以确保用户能够快速、高效地获取所需的信息。
请始终指定目的地，并尽可能使用地点 ID 以确保准确性
如果目标是提供即时导航，请添加 dir_action=navigate 参数以触发精细导航。如果设备位置信息可用且用作起点（显式设置或省略），导航将从用户的当前位置开始
为应用选择合适的方法
您有两种主要方法可供选择：利用地点 API 提供的预格式化网址，或在应用中手动构建 Google 地图网址。每种方法都有各自的优点和缺点。
Places API：
地点详情响应中的
googleMapsUri和googleMapsLinks字段提供可供使用的网址。这有助于缩短开发时间，并最大限度地降低网址格式错误的风险。对方向的配置控制较少。虽然
googleMapsLinks提供基本路线，但不支持航点或高级自定义。此外，直接触发精细导航相对来说不太简单。
地图网址：
提供更高的灵活性和控制力。开发者可以构建网址来显示地点详情，并配置路线的各个方面，包括添加路点、指定出行方式和启动精细导航。
需要深入了解网址参数和结构。如果手动构建不当，可能会增加出错的可能性。
使用 UTM 参数改进 Google 地图网址
为了帮助 Google 更好地了解开发者如何集成 Google 地图网址，并确保最佳效果，我们建议您在构建网址时添加 UTM 跟踪参数。通过添加 utm_source 和 utm_campaign 参数，您可以提供有价值的数据，以便我们分析使用模式并改进 Google 地图网址产品。
对于 utm_source 参数，请使用应用的名称。utm_campaign 参数应反映用户的预期操作，例如“location_sharing”“place_details_search”或“directions_request”。
例如，包含 UTM 参数的网址可能如下所示：
https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YourAppName&utm_campaign=place_details_search
始终使用这些参数有助于我们找出有待改进的地方，更有效地排查问题，并最终为所有用户提供更好的体验。
后续步骤
建议的进一步阅读：
贡献者
主要作者：
Teresa Qin | Google 地图平台解决方案工程师