简介
利用地图网址,您可以构建一个跨平台通用网址,以启动 Google 地图并执行搜索、获取路线和导航,以及显示地图视图和全景图片。无论使用哪个平台,网址语法都是相同的。
无需 Google API 密钥即可使用地图网址。
通用跨平台语法
作为 Android 应用、iOS 应用或网站的开发者,您可以构建一个通用网址,该网址将打开 Google 地图并执行所请求的操作,无论地图打开时使用的是哪个平台。
- 在 Android 设备上:
- 如果 Android 版 Google 地图应用已安装且有效,该网址会在 Google 地图应用中启动 Google 地图并执行请求的操作。
- 如果 Google 地图应用未安装或已停用,该网址会在浏览器中启动 Google 地图,并执行请求的操作。
- 在 iOS 设备上:
- 如果安装了 iOS 版 Google 地图应用,该网址会在 Google 地图应用中启动 Google 地图并执行请求的操作。
- 如果未安装 Google 地图应用,该网址会在浏览器中启动 Google 地图,并执行请求的操作。
- 在任何其他设备上,该网址会在浏览器中启动 Google 地图,并执行请求的操作。
建议您使用跨平台网址从您的应用或网站启动 Google 地图,因为这些通用网址可让您更广泛地处理地图请求,无论使用哪个平台。对于可能仅在移动平台上正常运行的功能(例如,精细导航),您可能希望使用适用于 Android 或 iOS 的平台专用选项。请参阅以下文档:
- Android 版 Google 地图 intent - 专门用于启动 Android 版 Google 地图应用
- Google 地图网址方案 (iOS) - 专门用于启动 iOS 版 Google 地图应用
启动 Google 地图并执行特定操作
如需启动 Google 地图并视情况执行所支持的任一功能,请根据要求的操作,使用下列形式之一的网址架构:
- 搜索 - 启动显示特定地点图钉的 Google 地图,或执行常规搜索并启动地图以显示结果:
https://www.google.com/maps/search/?api=1¶meters
- 路线 - 查询路线和启动 Google 地图并提供结果:
https://www.google.com/maps/dir/?api=1¶meters
- 显示地图 - 启动 Google 地图且不显示标记或路线:
https://www.google.com/maps/@?api=1&map_action=map¶meters
- 显示街景全景图片 - 启动互动式全景图片:
https://www.google.com/maps/@?api=1&map_action=pano¶meters
重要提示:参数 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¶meters
参数
query
(必需):定义要在地图上突出显示的地点。所有搜索请求都需要查询参数。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 字段会生成以下地图:
示例 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¶meters
参数
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
(可选):定义出行方式。选项包括driving
、walking
(如果首选步行街和人行道,则为优先)、bicycling
(通过自行车道和首选街道(如果有))或transit
。如果未指定travelmode
,Google 地图会显示指定路线和/或用户偏好的一个或多个相关模式。dir_action=navigate
(可选):根据出发地是否启动精细导航或向指定目的地的路线预览。如果用户指定了出发地,但该地址距离用户的当前位置不远,或者当前设备位置不可用,则地图会启动路线预览。如果用户未指定某个源站(在这种情况下,该源站会默认为当前设备位置),或者该源站接近用户的当前位置,地图会启动精细导航。请注意,并非所有 Google 地图产品和/或所有目的地之间都提供导航功能;在这种情况下,系统会忽略此参数。waypoints
:指定在origin
和destination
之间路由路线的一个或多个中间位置。使用竖线字符 (|
) 分隔地点即可指定多个航点(例如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
以下示例将启动一个地图,其中包含从太空针塔到华盛顿州西雅图派克市场的骑行路线。
以下示例将启动一个地图,其中包含从澳大利亚 Google 悉尼至维多利亚女王大厦的步行路线。
显示地图
地图操作会返回不带标记或路线的地图。
构建地图网址
https://www.google.com/maps/@?api=1&map_action=map¶meters
参数
map_action=map
(必需):指定要显示的地图视图的类型。地图和街景的端点相同。为确保显示地图,必须将map_action
指定为map
。center
(可选):定义地图窗口的中心,并接受逗号分隔值形式的纬度/经度坐标(例如,-33.8569,151.2152
)。zoom
(可选):设置地图的初始缩放级别。可接受的值是 0(全世界)至 21(个别建筑)之间的整数。上限因所选位置可用地图数据而异。默认值为 15。basemap
(可选):定义要显示的地图类型。该值可以是roadmap
(默认值)、satellite
或terrain
。layer
(可选):定义要在地图上显示的额外图层(如果有)。该值可以是以下项之一:none
(默认)、transit
、traffic
或bicycling
。
地图示例
此示例网址将启动以用户当前所在位置为中心的默认 Google 地图。
https://www.google.com/maps/@?api=1&map_action=map
以下示例显示了一个以澳大利亚新南威尔士州卡通巴(以 -33.712206,150.311941
为中心)为中心的地图,并设置可选的 zoom
和 basemap
参数。
显示街景全景图片
借助全景图片操作,您可以启动查看器,从而将街景图像显示为互动式全景图片。每张街景全景图片均能以单个位置提供 360 度全景视图。图片包含 360 度水平视图(完整环绕一周)和 180 度垂直视图(从直上至直下)。全景图片操作会启动观看器,将生成的全景图片渲染为一个以相机为中心的球体。您可以操控相机,以控制相机的缩放和方向。
Google 街景提供整个覆盖区域内指定位置的全景视图。您也可以使用由用户提交的全景照片和街景集锦。
构建街景网址
https://www.google.com/maps/@?api=1&map_action=pano¶meters
参数
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
,并设置可选的 heading
、pitch
和 fov
参数。为了便于比较,示例 2 使用了 pano
ID 以及第一个示例中设置的相同参数。第三个示例展示了室内全景图片。
示例 1:仅使用 viewpoint
指定位置。
示例 2:使用 pano
ID 以及 viewpoint
位置。
pano
ID 优先于 viewpoint
。
在此示例中,找到了全景图片 ID,因此 viewpoint
会被忽略。请注意,与仅使用 viewpoint
找到的图片相比,为 pano
ID 显示的全景图片略有不同,而且更新时间也更短。
示例 3:显示英国伦敦萨拉斯特洛餐厅内使用全景图片 ID 指定的全景图片。
https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA
查找全景图片 ID
若要查找特定全景图片的 ID,您可以使用多种方法。
- 对于 JavaScript,请使用 StreetViewPanorama 类。
- 对于 Android,请使用公共类 StreetViewPanoramaLocation。
- 对于 iOS,请使用 GMSPanorama 类。
- 您还可以使用 Google Street View Image API 发出元数据请求。 图片元数据请求提供有关街景全景图片的数据,包括全景图片 ID。
更多示例
使用航点的路线示例
以下路线示例会启动 Google 地图,并显示从法国巴黎到法国塞勒堡的行车路线,其中包括以下航点:
国家/地区,城市 | 地名 | 地点 ID |
---|---|---|
1. 法国凡尔赛 | 凡尔赛宫 | ChIJdUyx15R95kcRj85ZX8H8OAU |
2. 法国沙特尔 | 沙特尔大教堂 | ChIJKzGHdEgM5EcR_OBTT3nQoEA |
3. 法国勒曼 | 勒芒圣朱利安大教堂 | ChIJG2LvQNCI4kcRKXNoAsPi1Mc |
4. 法国卡昂 | 卡昂城堡 | ChIJ06tnGbxCCkgRsfNjEQMwUsc |
在示例网址中,各个航点的定义方式不同,因此您可以比较航点在结果地图上显示时的差异。
示例 1:定义为城市、国家/地区的航点:
示例 2:定义为特定地点名称的路径点:
示例 3:定义为城市、国家/地区的航点,并为每个航点内的特定场所提供 waypoint_place_ids
:
示例 4:将航点定义为“城市,国家”,但与前一个示例相比,列出航点的顺序有所不同。演示地图会按照网址中列出的航点显示这些航点。
地图示例
显示具有指定 basemap
(卫星)和 layer
(公交)的地图。
街景示例
使用 FIFE 图像键作为 pano
ID 显示街景全景图片。请注意,pano
ID 以 F: 开头。