在当今这个位置感知世界中，用户希望能够顺畅地访问地点信息、路线和导航。无论是通过即时通讯应用、本地情境发现应用、物流和运输平台、旅游规划工具还是房地产信息平台，用户通常都需要快速查看位置详情或找到从 A 到 B 的最佳路线。虽然开发者可以构建自己的应用内体验，但利用 Google 地图全面而熟悉的界面可提供更出色的体验。
结构合理的 Google 地图网址对于提供顺畅的用户体验至关重要。不正确的网址会影响这种体验，导致用户被定向到错误的位置、显示通用的地图视图而不是具体详情，甚至导致链接损坏。这会让用户感到沮丧，并妨碍他们实现目标。 例如，即使 Google 地图网址有效，期待获取特定商家详细信息的用户也可能会进入一个没有相关信息的一般地图视图。请参阅以下示例：
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152
此地图网址可用于打开 Google 地图并显示基于经纬度的位置。不过，它不会向用户提供有关特定地点的详细信息。
通过准确的网址将您的应用与 Google 地图无缝连接
Google Maps Platform (GMP) 提供两种主要方法来构建准确的网址：Places API（新），需要 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 Places 数据库中和 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"
}
]
}当用户点击或点按地图上的 POI 时，也可以检索地点 ID。详细了解可点击的 POI 图标（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 地图移动版中启用精细导航。
借助 Street View 全景图片功能，您可以启动查看器，以交互式全景图片的形式显示街景图片。
如需探索更多函数和示例，请参阅 GMP 地图网址开发者文档。
下面我们将深入探讨 Google 地图网址的两项关键功能：
在 Google 地图上显示地点详细信息：本部分介绍如何构建网址，以便在 Google 地图上显示特定地点的详细信息。此外，该指南还详细介绍了如何使用地点 ID 和精确查询来处理名称不唯一的地点。
使用 Google 地图网址提供路线：本部分介绍了如何创建可提供地点之间路线的网址，包括包含多个途经点的路线和逐向导航。
在 Google 地图上显示地点详情
搜索功能需要两个参数才能完成地点搜索，分别是 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 Places 数据库中和 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 和 Places 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"
}
]
}当用户点击或点按地图上的 POI 时，也可以检索地点 ID。详细了解可点击的 POI 图标（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 地图会尝试查找您当前位置附近的商家信息。
场景 1：附近地点搜索
https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now
使用 Google 地图网址提供路线
“路线”功能可显示地图上两个或多个指定点之间的路径，以及距离和行程时间。这可让开发者更好地控制所提供的路线。GMP 的“地图网址 - 路线”文档详细介绍了如何构建用于自定义路线的网址。
路线网址结构：
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 和 Places 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"
}
]
}当用户点击或点按地图上的 POI 时，也可以检索地点 ID。详细了解可点击的 POI 图标（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 参数以触发精细导航。如果设备位置信息可用并用作出发地（明确设置或省略），导航将从用户的当前位置开始
为应用选择合适的方法
您主要有两种选择：利用 Places 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 Maps Platform 解决方案工程师