开始使用

简介

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

无需 Google API 密钥即可使用地图网址。

通用跨平台语法

作为 Android 应用、iOS 应用或网站的开发者,您可以构建一个通用网址,该网址将打开 Google 地图并执行所请求的操作,无论地图打开时使用的是哪个平台。

  • 在 Android 设备上:
    • 如果 Android 版 Google 地图应用已安装且有效,该网址会在 Google 地图应用中启动 Google 地图并执行请求的操作。
    • 如果 Google 地图应用未安装或已停用,该网址会在浏览器中启动 Google 地图,并执行请求的操作。
  • 在 iOS 设备上:
    • 如果安装了 iOS 版 Google 地图应用,该网址会在 Google 地图应用中启动 Google 地图并执行请求的操作。
    • 如果未安装 Google 地图应用,该网址会在浏览器中启动 Google 地图,并执行请求的操作。
  • 在任何其他设备上,该网址会在浏览器中启动 Google 地图,并执行请求的操作。

建议您使用跨平台网址从您的应用或网站启动 Google 地图,因为这些通用网址可让您更广泛地处理地图请求,无论使用哪个平台。对于可能仅在移动平台上正常运行的功能(例如,精细导航),您可能希望使用适用于 Android 或 iOS 的平台专用选项。请参阅以下文档:

启动 Google 地图并执行特定操作

如需启动 Google 地图并视情况执行所支持的任一功能,请根据要求的操作,使用下列形式之一的网址架构:

  • 搜索 - 启动显示特定地点图钉的 Google 地图,或执行常规搜索并启动地图以显示结果:
    https://www.google.com/maps/search/?api=1&parameters
  • 路线 - 查询路线和启动 Google 地图并提供结果:
    https://www.google.com/maps/dir/?api=1&parameters
  • 显示地图 - 启动 Google 地图且不显示标记或路线:
    https://www.google.com/maps/@?api=1&map_action=map&parameters
  • 显示街景全景图片 - 启动互动式全景图片:
    https://www.google.com/maps/@?api=1&map_action=pano&parameters

重要提示:参数 api=1 用于标识此网址的目标地图网址版本。每个请求中都必须包含此参数。唯一有效值是 1。如果网址中没有 api=1,系统会忽略所有参数,而默认的 Google 地图应用将在浏览器中或 Google 地图移动应用中启动,具体取决于所使用的平台(例如 https://www.google.com/maps)。

构建有效网址

您必须对网址进行正确编码

例如,某些参数使用竖线字符 (|) 作为分隔符,而在最终到达网址中,您必须将其编码为 %7C。其他参数使用逗号分隔值,例如纬度/经度坐标或城市、州/省。您必须将逗号编码为 %2C。使用 %20 对空格进行编码,或将其替换为加号 (+)。

此外,每个请求的网址不得超过 2,048 个字符。构建网址时请注意此限制。

地图操作次数

可用的地图操作包括:搜索、查询路线、显示地图和显示街景全景图片。您可以在请求网址中指定操作以及必需参数和可选参数。根据网址的标准,您使用和号 (&) 字符来分隔参数。对于每项操作,搜索参数部分都会枚举参数及其可能的值。

搜索

搜索操作显示可见地图区域内的搜索结果。搜索特定地点时,生成的地图会在指定位置放置一个图钉,并显示可用的地点详情。

构建搜索网址

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

参数

  • query(必需):定义要在地图上突出显示的地点。所有搜索请求都需要查询参数。
    • 将地点指定为地点名称、地址或以逗号分隔的纬度/经度坐标。字符串应进行网址编码,因此“City Hall, New York, NY”这样的地址应转换为 City+Hall%2C+New+York%2C+NY
    • 将常规搜索字词指定为网址编码字符串,例如 grocery+storesrestaurants+in+seattle+wa
  • query_place_id(可选):地点 ID 是唯一标识地点的文本标识符。对于 search 操作,您必须指定 query,但您也可以指定 query_place_id。如果您同时指定了这两个参数,则只有在 Google 地图无法找到地点 ID 时,才会使用 query。如果您尝试明确链接到特定场所,则地点 ID 是保证关联到正确地点的最佳保证。当您使用纬度/经度坐标查询特定位置时,还建议提交 query_place_id

搜索示例

位置搜索

在位置搜索中,您使用地点名称、地址或经纬度坐标(以逗号分隔)搜索特定位置,并且生成的地图会在该位置显示一个图钉。以下三个示例显示了使用不同位置值搜索相同位置 CenturyLink 字段(美国华盛顿西雅图的体育馆)。

示例 1:搜索地点名称“CenturyLink 字段”会生成以下映射:

https://www.google.com/maps/search/?api=1&query=centurylink+field

示例 2:使用纬度/经度坐标以及地点 ID 搜索 CenturyLink 字段会生成以下地图:

https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393&query_place_id=ChIJKxjxuaNqkFQR3CK6O1HNNqY

示例 3:仅使用纬度/经度坐标搜索 CenturyLink 字段会生成以下地图。请注意,地图中有一个图钉,但未在地图或侧边栏中提供额外的地点信息:

https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393

分类搜索

在分类搜索中,您只需传递一个常规搜索字词,Google 地图就会尝试在您指定的位置附近查找符合搜索条件的商家信息。 如果未指定位置,Google 地图会尝试查找您当前所在位置附近的列表。如果您希望为分类搜索提供位置,请将位置添加到常规搜索字符串(例如 pizza+seattle+wa)中。

在此示例中,搜索华盛顿州西雅图的披萨店,会生成以下地图:

https://www.google.com/maps/search/?api=1&query=pizza+seattle+wa


路线

路线操作会显示地图上两个或多个指定点之间的路径,以及距离和行程时间。

构建路线网址

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

参数

  • origin:定义显示路线的起点。默认为最相关的起始位置,例如设备位置(如果有)。如果没有,则生成的地图可能会提供一个空白表单,以便用户进入出发地。该值可以是地点名称、地址或以逗号分隔的纬度/经度坐标。字符串应进行网址编码,因此“City Hall, New York, NY”这样的地址应转换为 City+Hall%2C+New+York%2C+NY

    注意:除非您在网址中指定 origin_place_id,否则此参数是可选的。如果您选择指定 origin_place_id,则还必须在网址中添加 origin

  • origin_place_id(可选):地点 ID 是唯一标识地点的文本标识符。如果您尝试明确指定某个场所,最好使用地点 ID 来保证您关联到正确的地点。使用此参数的网址还必须包含 origin
  • destination:用于定义路线的端点。如果没有,则生成的地图可能会提供一个空白表单,以便用户进入目的地。该值可以是地点名称、地址或以逗号分隔的纬度/经度坐标。字符串应进行网址编码,因此“City Hall, New York, NY”这样的地址应转换为 City+Hall%2C+New+York%2C+NY

    注意:除非您在网址中指定 destination_place_id,否则此参数是可选的。如果您选择指定 destination_place_id,则还必须在网址中添加 destination

  • destination_place_id(可选):地点 ID 是唯一标识地点的文本标识符。如果您尝试明确指定某个场所,最好使用地点 ID 来保证您关联到正确的地点。使用此参数的网址还必须包含 destination
  • travelmode(可选):定义出行方式。选项包括 drivingwalking(如果首选步行街和人行道,则为优先)、bicycling(通过自行车道和首选街道(如果有))或 transit。如果未指定 travelmode,Google 地图会显示指定路线和/或用户偏好的一个或多个相关模式。
  • dir_action=navigate(可选):根据出发地是否启动精细导航或向指定目的地的路线预览。如果用户指定了出发地,但该地址距离用户的当前位置不远,或者当前设备位置不可用,则地图会启动路线预览。如果用户未指定某个源站(在这种情况下,该源站会默认为当前设备位置),或者该源站接近用户的当前位置,地图会启动精细导航。请注意,并非所有 Google 地图产品和/或所有目的地之间都提供导航功能;在这种情况下,系统会忽略此参数。
  • waypoints:指定在 origindestination 之间路由路线的一个或多个中间位置。使用竖线字符 (|) 分隔地点即可指定多个航点(例如 Berlin,Germany|Paris,France)。允许的航点数量因链接打开的平台而异,移动浏览器最多支持三个航点,否则最多支持九个航点。途经点在地图上的显示顺序与在网址中列出的顺序相同。 每个航点可以是地点名称、地址或以逗号分隔的纬度/经度坐标。字符串应进行网址编码,因此航点(例如“柏林, 德国|巴黎, 法国”)应转换为 Berlin%2CGermany%7CParis%2CFrance

    注意:

    • 并非所有 Google 地图产品都支持航点;在这些情况下,系统会忽略此参数。
    • 除非您在网址中指定 waypoint_place_ids,否则此参数是可选的。如果您选择指定 waypoint_place_ids,则还必须在网址中添加 waypoints
  • waypoint_place_ids(可选):地点 ID 是唯一标识地点的文本标识符。Waypoint_place_ids 可让您提供与 waypoints 列表相匹配的地点 ID 列表。地点 ID 应按照与航点相同的顺序列出,并使用竖线字符“|”(网址编码为 %7C)分隔。如果您尝试明确指定某些场所,则地点 ID 是保证关联到正确地点的最佳保证。 使用此参数的网址还必须包含 waypoints

路线示例

以下网址可在路线模式下启动地图,并提供一个表单,供用户输入出发地和目的地。

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

以下示例将启动一个地图,其中包含从太空针塔到华盛顿州西雅图派克市场的骑行路线。

https://www.google.com/maps/dir/?api=1&origin=Space+Needle+Seattle+WA&destination=Pike+Place+Market+Seattle+WA&travelmode=bicycling

以下示例将启动一个地图,其中包含从澳大利亚 Google 悉尼至维多利亚女王大厦的步行路线。

https://www.google.com/maps/dir/?api=1&origin=Google+Pyrmont+NSW&destination=QVB&destination_place_id=ChIJISz8NjyuEmsRFTQ9Iw7Ear8&travelmode=walking


显示地图

地图操作会返回不带标记或路线的地图。

构建地图网址

https://www.google.com/maps/@?api=1&map_action=map&parameters

参数

  • map_action=map(必需):指定要显示的地图视图的类型。地图和街景的端点相同。为确保显示地图,必须将 map_action 指定为 map
  • center(可选):定义地图窗口的中心,并接受逗号分隔值形式的纬度/经度坐标(例如,-33.8569,151.2152)。
  • zoom(可选):设置地图的初始缩放级别。可接受的值是 0(全世界)至 21(个别建筑)之间的整数。上限因所选位置可用地图数据而异。默认值为 15。
  • basemap(可选):定义要显示的地图类型。该值可以是 roadmap(默认值)、satelliteterrain
  • layer(可选):定义要在地图上显示的额外图层(如果有)。该值可以是以下项之一:none(默认)、transittrafficbicycling

地图示例

此示例网址将启动以用户当前所在位置为中心的默认 Google 地图。

https://www.google.com/maps/@?api=1&map_action=map

以下示例显示了一个以澳大利亚新南威尔士州卡通巴(以 -33.712206,150.311941 为中心)为中心的地图,并设置可选的 zoombasemap 参数。

https://www.google.com/maps/@?api=1&map_action=map&center=-33.712206%2C150.311941&zoom=12&basemap=terrain


显示街景全景图片

借助全景图片操作,您可以启动查看器,从而将街景图像显示为互动式全景图片。每张街景全景图片均能以单个位置提供 360 度全景视图。图片包含 360 度水平视图(完整环绕一周)和 180 度垂直视图(从直上至直下)。全景图片操作会启动观看器,将生成的全景图片渲染为一个以相机为中心的球体。您可以操控相机,以控制相机的缩放和方向。

Google 街景提供整个覆盖区域内指定位置的全景视图。您也可以使用由用户提交的全景照片街景集锦

构建街景网址

https://www.google.com/maps/@?api=1&map_action=pano&parameters

参数

  • map_action=pano(必需):指定要显示的视图类型。地图和街景的端点相同。为了确保显示全景图片,必须将 action 指定为 pano

此外,还必须提供以下网址参数之一:

  • viewpoint:查看器显示距离 viewpoint 位置最近的照片,以以英文逗号分隔的纬度/经度坐标(例如 46.414382,10.013988)的形式指定。由于街景图像会定期刷新,并且每次拍摄照片的位置都略有不同,因此在图像更新后,您的位置可能会拍摄到不同的全景图片。
  • pano:要显示的图片的具体全景图片 ID。如果您指定了 pano,还可以指定 viewpoint。仅当 Google 地图无法找到全景图片 ID 时,才会使用 viewpoint。如果指定了 pano,但未找到,并且未指定 viewpoint,则系统不会显示全景图片。相反,Google 地图会在默认模式下打开,显示以用户当前位置为中心的地图。

以下网址参数为可选参数:

  • heading:以与北方所呈的顺时针角度指示相机的罗盘方向。接受的值范围在 -180 度到 360 度之间。如果省略此参数,则根据查询的视点(如果已指定)和图片的实际位置来选择默认方向。
  • pitch:指定相机的向上或向下角度。 音高是以 -90 到 90 之间的度数指定的。正值将使相机呈向上角度,而负值将使相机向下倾斜。默认间距 0 根据拍摄图片时的相机位置设置。因此,间距 0 通常(但并非始终)是水平间距。例如,在山上拍摄的图像所呈现的默认间距可能并非水平间距。
  • fov:确定图片的水平视野。 视野以度数表示,范围为 10 - 100。默认值为 90。 在处理固定尺寸的视口时,视野会被视为缩放级别,数字越小,表示缩放级别越大。

街景示例

前两个示例展示了埃菲尔铁塔的全景。该示例只对位置使用 viewpoint,并设置可选的 headingpitchfov 参数。为了便于比较,示例 2 使用了 pano ID 以及第一个示例中设置的相同参数。第三个示例展示了室内全景图片。

示例 1:仅使用 viewpoint 指定位置。

https://www.google.com/maps/@?api=1&map_action=pano&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

示例 2:使用 pano ID 以及 viewpoint 位置。 pano ID 优先于 viewpoint。 在此示例中,找到了全景图片 ID,因此 viewpoint 会被忽略。请注意,与仅使用 viewpoint 找到的图片相比,为 pano ID 显示的全景图片略有不同,而且更新时间也更短。

https://www.google.com/maps/@?api=1&map_action=pano&pano=tu510ie_z4ptBZYo2BGEJg&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

示例 3:显示英国伦敦萨拉斯特洛餐厅内使用全景图片 ID 指定的全景图片。

https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA

查找全景图片 ID

若要查找特定全景图片的 ID,您可以使用多种方法。

更多示例

使用航点的路线示例

以下路线示例会启动 Google 地图,并显示从法国巴黎到法国塞勒堡的行车路线,其中包括以下航点:

国家/地区,城市地名地点 ID
1. 法国凡尔赛 凡尔赛宫 ChIJdUyx15R95kcRj85ZX8H8OAU
2. 法国沙特尔 沙特尔大教堂 ChIJKzGHdEgM5EcR_OBTT3nQoEA
3. 法国勒曼 勒芒圣朱利安大教堂 ChIJG2LvQNCI4kcRKXNoAsPi1Mc
4. 法国卡昂 卡昂城堡 ChIJ06tnGbxCCkgRsfNjEQMwUsc

在示例网址中,各个航点的定义方式不同,因此您可以比较航点在结果地图上显示时的差异。

示例 1:定义为城市、国家/地区的航点:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance

示例 2:定义为特定地点名称的路径点:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Palace+of+Versailles%7CChartres+Cathedral%7CCathedral+of+Saint+Julian+of+Le+Mans%7CCaen+Castle

示例 3:定义为城市、国家/地区的航点,并为每个航点内的特定场所提供 waypoint_place_ids

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance&waypoint_place_ids=ChIJdUyx15R95kcRj85ZX8H8OAU%7CChIJKzGHdEgM5EcR_OBTT3nQoEA%7CChIJG2LvQNCI4kcRKXNoAsPi1Mc%7CChIJ06tnGbxCCkgRsfNjEQMwUsc

示例 4:将航点定义为“城市,国家”,但与前一个示例相比,列出航点的顺序有所不同。演示地图会按照网址中列出的航点显示这些航点。

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CCaen%2CFrance%7CLe+Mans%2CFrance%7CChartres%2CFrance

地图示例

显示具有指定 basemap(卫星)和 layer(公交)的地图。

https://www.google.com/maps/@?api=1&map_action=map&center=37.7992940%2C-122.3976113&zoom=15&basemap=satellite&layer=transit

街景示例

使用 FIFE 图像键作为 pano ID 显示街景全景图片。请注意,pano ID 以 F: 开头。

https://www.google.com/maps/@?api=1&map_action=pano&pano=F:-ud6AZSB-sQg/V0cfCSV3OWI/AAAAAAAAG1U/UQEoc5sXPQEIP7zzD6SWzmKb8Vbug47uQCLIB&heading=22&pitch=-5&fov=55