Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用 Google 地图网址或 Google 地图地点 API 将用户定向至 Google 地图地点详情和路线

在当今这个位置感知型世界中，用户希望能够顺畅地访问地点信息、路线和导航。无论是通过即时通讯应用、本地情境发现应用、物流和运输平台、旅行规划工具还是房地产信息平台，用户通常都需要快速查看地点详细信息或查找从 A 到 B 的最佳路线。虽然开发者可以构建自己的应用内体验，但利用 Google 地图全面且熟悉的界面可以提供更出色的体验。

结构合理的 Google 地图网址对于提供顺畅的用户体验至关重要。不正确的网址会损害这种体验，将用户定向到错误的位置，显示通用地图视图而不是具体详细信息，甚至导致损坏的链接。这会让用户感到沮丧，并阻止他们实现目标。例如，即使使用有效的地图网址，期待获得特定商家详细信息的用户也可能会进入一个没有相关信息的通用地图视图。请参阅以下示例：

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152

此地图网址可用于打开 Google 地图并根据纬度和经度显示位置。不过，它不会向用户提供有关特定地点的详细信息。

仅使用纬度和经度进行搜索

通过准确的网址将您的应用与 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 和 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"
    }
  ]
}

当用户点击或轻触地图上的地图注点时，也可以检索地点 ID。详细了解可点击的地图注点图标（JavaScript、Android、iOS）

实现

使用 Places API 时，开发者只需从响应中提取 googleMapsUri 或 googleMapsLinks 字段，并使用它在 Google 地图应用中或在浏览器中（如果未安装该应用）启动相应的视图。

功能	说明
directionsUri	用于打开 Google 地图以显示从用户当前位置到此地点的路线的链接
placeUri	用于打开 Google 地图以显示此地点的详情页面的链接
writeAReviewUri	用于打开 Google 地图以显示此地点的评价撰写页面的链接
reviewsUri	用于打开 Google 地图以显示此地点的评价页面的链接
photosUri	用于打开 Google 地图以显示此地点的照片页面的链接

查看开发者指南，立即试用此功能。

利用地图网址

利用地图网址，您可以构建一个跨平台通用网址，以启动 Google 地图、执行搜索、获取路线和导航，以及显示地图视图和全景图片。无论使用哪个平台，网址语法都是相同的。您无需 Google API 密钥即可使用地图网址。

可用的地图操作包括：

搜索功能会启动 Google 地图应用或在浏览器中（如果未安装该应用）显示特定地点的图钉，或执行常规搜索并启动地图以显示结果。
路线功能会启动 Google 地图应用或在浏览器中（如果未安装该应用）显示点之间的路线，或在移动设备上的 Google 地图中启用精细导航。
街景全景功能可让您启动查看器，以交互式全景图片的形式显示街景图片。

请访问 GMP 地图网址开发者文档，了解更多功能和示例。

下面我们将深入探讨地图网址的两个关键功能：

在 Google 地图上显示地点详细信息：本部分介绍了如何构建网址，以便在 Google 地图上显示特定地点的详细信息。此外，它还详细介绍了如何通过使用地点 ID 和精确查询来处理名称不唯一的地点。
使用地图网址提供路线：本部分介绍了如何创建网址，以便提供地点之间的路线，包括包含多个航点的路线和精细导航。

在 Google 地图上显示地点详细信息

搜索功能会使用两个参数来完成地点搜索，分别是 query（必需）和 query_place_id（可选）。

所有搜索请求都需要 query 参数。它接受地点名称、以逗号分隔的纬度/经度坐标或常规搜索字词。

搜索网址结构：

https://www.google.com/maps/search/?api=1&parameters

场景 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

如需以编程方式检索地点 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"
    }
  ]
}

当用户点击或轻触地图上的地图注点时，也可以检索地点 ID。详细了解可点击的地图注点图标（JavaScript、Android、iOS）

总结

提供准确的地点详细信息对于提供良好的体验至关重要。为确保用户进入正确的地点详情页面，请使用以下推荐格式之一构建搜索网址：

query=PLACE_NAME, ADDRESS
query=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

分类搜索 - 附近的地点

使用地图网址提供路线

路线功能会显示地图上两个或多个指定点之间的路径，以及距离和行程时间。它让开发者可以更好地控制提供的路线。GMP 的地图网址路线文档详细介绍了如何构建用于自定义路线的网址。

路线网址结构：

https://www.google.com/maps/dir/?api=1&parameters

场景 1：查找从用户当前位置到目的地的最佳路线

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving

此网址会打开 Google 地图并显示从用户当前位置出发的驾车路线。

在此网址中，省略了 origin。如果省略了 origin，路径会默认设置为最相关的起始位置（例如设备位置，如果可用）。如果没有，生成的地图会提供一个表单，供用户输入出发地。出发地和目的地的取值可以是地点名称、地址或以逗号分隔的纬度/经度坐标。

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"
    }
  ]
}

当用户点击或轻触地图上的地图注点时，也可以检索地点 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 地图网页版）和/或所有目的地之间都提供导航功能。在这些情况下，此参数将被忽略。


精细导航	路线预览

总结

通过正确构建地图网址，您可以确保用户快速高效地获取所需信息。

始终指定目的地，并尽可能使用地点 ID 以确保准确性
如果目标是提供即时导航，请添加 dir_action=navigate 参数以触发精细导航。如果设备位置可用并用作出发地（无论是明确设置还是省略），导航将从用户当前位置开始

为您的应用选择合适的方法

您有两个主要选项：利用 Places API 提供的预先设置格式的网址，或在应用中手动构建地图网址。每种方法都有其自身的优缺点。

Places API：

地点详情响应中的 googleMapsUri 和 googleMapsLinks 字段提供了可直接使用的网址。这缩短了开发时间，并最大限度地降低了网址格式错误的风险。
对路线配置的控制较少。虽然 googleMapsLinks 提供了基本路线，但它不支持航点或高级自定义。此外，直接触发精细导航也相对不那么直接。

地图网址：

提供更大的灵活性和控制力。开发者可以构建网址来显示地点详细信息，并配置路线的各个方面，包括添加航点、指定出行方式和启动精细导航。
需要深入了解网址参数和结构。如果操作不当，手动构建会增加出错的可能性。

使用 UTM 参数改进地图网址

为了帮助 Google 更好地了解开发者如何集成地图网址并确保最佳性能，我们建议您在构建网址时添加 UTM 跟踪参数。通过添加 utm_source 和 utm_campaign 参数，您可以提供有价值的数据，以便我们分析使用模式并改进地图网址产品。

对于 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 地图平台解决方案工程师

使用 Google 地图网址或 Google 地图地点 API 将用户定向至 Google 地图地点详情和路线 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

通过准确的网址将您的应用与 Google 地图无缝连接

使用 GMP Places API（新）的 googleMapsUri 或 googleMapsLinks 字段

免费检索地点 ID

实现

利用地图网址

在 Google 地图上显示地点详细信息

使用地图网址进行分类搜索

使用地图网址提供路线

为您的应用选择合适的方法

使用 UTM 参数改进地图网址

后续步骤

贡献者

使用 Google 地图网址或 Google 地图地点 API 将用户定向至 Google 地图地点详情和路线