开始使用

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

简介

您可以使用地图网址构建通用的跨平台网址,以启动 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 Field(位于美国华盛顿州西雅图的体育馆)。

示例 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)来指定多个航点。允许的路径点数量因链接打开的平台而异,移动浏览器最多支持三个航点,否则最多支持 9 个航点。航点在地图上的显示顺序与在网址中的显示顺序相同。 每个航点可以是地点名称、地址或以英文逗号分隔的纬度/经度坐标。字符串应进行网址编码,因此“柏林、德国|巴黎、法国”等航点应转换为 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:显示位于英国伦敦的 Sarastro 餐厅的内部全景图片,由全景图片 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