一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Maps Embed API

为帮助您起步,我们将引导您在 Google Developers Console 中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Maps Embed API
  3. 创建相应密钥
继续

Google Maps Embed API

概览

Google Maps Embed API 允许您通过简单的 HTTP 请求在您的网站上放置交互式地图或街景全景图。 可通过将 Google Maps Embed API URL 设置为 iframe 的 src 属性,方便地将其嵌入您的网页或博客:

<iframe
  width="600"
  height="450"
  frameborder="0" style="border:0"
  src="https://www.google.com/maps/embed/v1/place?key=YOUR_API_KEY
    &q=Space+Needle,Seattle+WA" allowfullscreen>
</iframe>

为您量身打造的地图

您的网站的每一位访客都会看到专为其量身定制的 Google 地图。 如果他们使用 Google 帐户登录,则其查看的地图上将会直接嵌入他们保存的地点、住宅和办公位置以及其他内容。

此外,这还意味着与地图的交互(如为位置添加星标)将得到保存,以方便在桌面版或移动版 Google 地图中进行查看。

这些用户专属详情对其他用户不可见。 每一位访客都会看到为其量身定制的地图。

轻松嵌入

Google Maps Embed API 地图可轻松添加到您的网页中—只需将您生成的 URL 设置为某个 iframe src 属性的值。 通过 iframe 的 height 属性和 width 属性控制地图的大小。 无需 JavaScript。

无使用限制

Google Maps Embed API 不受使用限制。 将地图或街景全景图嵌入您的高流量网站时,无需担心达到使用上限或每秒查询次数限制。

地图广告

Google Maps Embed API 可能包括地图广告。 任何给定地图中展示的广告形式和广告组可能随时变更,恕不另行通知。

设置 URL 格式

Google Maps Embed API 请求的 URL 格式如下:

https://www.google.com/maps/embed/v1/MODE?key=YOUR_API_KEY&parameters

其中:

  • {MODE}placedirectionssearchviewstreetview 之一
  • {YOUR_API_KEY} 是您的免费 API 密钥
  • parameters 包括可选参数以及模式专属参数

API 密钥

向 Google Maps Embed API 发出的所有请求都必须以一个免费 API 密钥作为 key 参数的值。 密钥让您可以监控您的应用对 Maps API 的使用情况,并可确保 Google 可以在必要时就网站/应用相关事宜与您联系。

要开始使用 Google Maps Embed API,请点击下面的按钮,系统将自动激活 Google Maps Embed API 并获取 API 密钥。

获取密钥

或者,请按照下列步骤获取 API 密钥:

  1. 转至 Google API Console
  2. 创建或选择一个项目。
  3. 点击 Continue 以启用 API。
  4. Credentials 页面上,获取 API 密钥(并设置 API 密钥限制)。
    注:如果已有不受限的 API 密钥或有浏览器限制的密钥,可以使用该密钥。
  5. 我们建议您按照以下最佳实践保护您的 API 密钥


在 Google API Console 中,您还可以查找现有密钥查看已启用的 API 的列表

如需了解有关使用 Google API Console 的详细信息,请参阅 API Console 帮助

API 密钥限制的类型

Google Maps API 可用于 Android 或 iOS 应用、网络浏览器,并可通过 HTTP 网络服务使用。任何平台上的 API 均可以使用通用(无限制的)API 密钥。您可以选择向 API 密钥添加限制(例如 HTTP 引荐来源网址)。受限后,密钥仅会在支持这一类型限制的平台上有效。详细了解密钥和凭据

地图模式

有四种地图嵌入模式可供您使用。 模式在请求 URL 中指定。

Place 模式

Place 模式会在特定地点或地址(如标志性建筑、商家、地理景观或城镇)处显示一个图钉。

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

以下 URL 参数为必需参数:

  • q 定义要在地图上突出显示的地点。 它接受地点名称、地址或地点 ID 形式的位置。 字符串应为 URL 转义字符串,因此“City Hall, New York, NY”这样的地址应转换为 City+Hall,New+York,NY

(将空格设置为转义字符时,Google Maps Embed API 同时支持 +%20。) 地点 ID 应带有 place_id: 前缀。

归因保存

登录 Google 帐户的用户将可以保存 q 参数指示的地点。 保存的地点将出现在 Web 或移动设备上的其他 Google 地图中。 默认情况下,从嵌入式地图保存的地点将包括提供方说明信息,以提醒用户在其保存该地点时所处的位置。您可以通过以下参数对提供方说明进行个性化设置。

  • attribution_source 将保存归因于您的网站或应用。 您必须先加入自定义 attribution_source,然后再设置 attribution_web_urlattribution_ios_deep_link_id。 默认值为显示地图的页面的 URL 路径,例如:

https://example.com/path/ * attribution_web_url 指定返回您的网站的链接。 如果未指定 attribution_sourceattribution_web_url 将默认使用显示嵌入式地图的 URL,例如:

https://example.com/path/page.html * attribution_ios_deep_link_id 指定提供 iOS 应用内部深层链接的 URL 架构。 在 iOS 版 Google 地图上查看时,将在 attribution_web_url 位置上显示 attribution_ios_deep_link_id

下面的示例显示了不列颠哥伦比亚省维多利亚市皇后酒店的一个图钉。 保存该位置将把保存归因于“Google Maps Embed API”。 提供方说明将以 URL 形式出现。 该示例利用 Google 地图网址架构向 iOS 用户提供驾车路线。

https://www.google.com/maps/embed/v1/place?key=YOUR_API_KEY
  &q=Fairmont+Empress,Victoria+BC
  &attribution_source=Google+Maps+Embed+API
  &attribution_web_url=http://www.fairmont.com/empress-victoria/
  &attribution_ios_deep_link_id=comgooglemaps://?daddr=Fairmont+Empress,+Victoria,+BC

Directions 模式

Directions 模式显示地图上指定的两个点或更多个点之间的路径以及距离和行程时间。

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

以下 URL 参数为必需参数:

  • origin 定义所显示路线的起点。 该值可以是地点名称、地址或地点 ID

字符串应为 URL 转义字符串,因此“City Hall, New York, NY”这样的地址应转换为 City+Hall,New+York,NY。 (将空格设置为转义字符时,Google Maps Embed API 同时支持 +%20。)

地点 ID 应带有 place_id: 前缀。 * destination 定义路线的终点。

以下 URL 参数为可选参数:

  • waypoints 指定起点与目的地之间的路线途经的一个或多个中途地点。 可以通过使用管道字符 (|) 分隔地点来指定多个路径点(例如:

Berlin,Germany|Paris,France)。 您可以指定多达 20 个路径点。 各路径点可以是地点名称、地址或地点 ID。

  • mode 定义出行方式。 选项为 drivingwalking(首选步道和人行道,如有)、bicycling(路线途径自行车道和首选街道,如有)、transitflying

如果未指定模式,Google Maps Embed API 将为指定路线显示一个或多个最相关的模式。

  • avoid 指示 Google 地图避开 tollsferries 和/或 highways。 使用管道字符分隔多个值(例如: avoid=tolls|highways)。 请注意,这不会将包括受限特征的路线排除在外,其作用仅仅是通过影响结果来获得更有利的路线。

  • units 指定在结果中显示距离时使用 metric 还是 imperial 单位。 如果未指定 units,则由查询的 origin 国家决定使用什么单位。

Search 模式显示可见地图区域内的搜索结果。 建议通过在搜索词中加入位置 (record+stores+in+Seattle) 或通过加入 center 参数和 zoom 参数设置搜索边界来定义搜索位置。

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

以下 URL 参数为必需参数:

  • q 指定搜索词。 它可以包括地理限制,如 in+Seattlenear+98033

View 模式

View 模式返回不带标记或路线的地图。

下面的示例使用可选的 maptype 参数显示了地图的卫星视图。

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

以下 URL 参数为必需参数:

  • center 定义地图窗口的中心,接受逗号分隔值形式的纬度和经度 (-33.8569,151.2152)。

可选参数

下列可选参数可用于以上所列的任一地图模式。

  • center 定义地图视图的中心。 它接受逗号分隔纬度和经度值(如 37.4218,-122.0840)。

  • zoom 设置地图的初始缩放比例。 可接受的值范围是 0(全世界)至 21(个别建筑)。 上限可能因所选位置可用地图数据的不同而有所差异。

  • maptype 可以是 roadmap(默认值)或 satellite,定义要加载的地图图块类型。

  • language 定义 UI 元素和地图图块上显示的标签所使用的语言。 请注意,只有部分国家图块支持此参数;如果图块集不支持所请求的特定语言,将使用该图块集的默认语言。 默认情况下,访客看到的地图将使用其母语。

  • region 根据地缘政治敏感性定义要显示的相应边界和标签。 接受以双字符 ccTLD(顶级域)值形式指定的地区代码。

地点 ID 参数

Google Maps Embed API 支持使用地点 ID 来替代提供地点名称或地址。 地点 ID 是对地点进行唯一标识的可靠方法。 请参阅 Google Places API 文档,了解有关地点 ID 查找和使用方法的详细信息。

Google Maps Embed API 接受使用地点 ID 表示下列 URL 参数:

  • q

  • origin

  • destination

  • waypoints

如需使用地点 ID,您必须先添加前缀 place_id:。 以下代码将纽约市政厅指定为路线 request: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8 的起点。

街景模式

Google Maps Embed API 允许您在您的网站或博客上以交互式全景图形式显示街景图像。 Google 街景提供其整个覆盖区域内从指定位置获得的全景视图。 此外,还提供用户贡献照片球街景特别收藏

每张街景全景图均提供以单个位置为中心的 360 度全视图。 图像包含 360 度水平视图(全包围)和 180 度垂直视图(从直上至直下)。 streetview 模式提供了一个查看器,通过中心位置的摄像头将生成的全景图渲染为一个球面。

您可以通过操纵摄像头来控制摄像头的缩放比例和朝向。

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

以下其中一个 URL 参数为必需参数:

  • location 接受逗号分隔值形式的纬度和经度 (46.414382,10.013988)。 API 将显示在离该位置最近处拍摄的全景图。 由于街景图像会定期更新,并且可能每次拍摄照片的位置都略有差异,因此可能出现图像更新后您的位置对应于不同全景图的情况。

  • pano 是具体的全景图 ID。 如果您指定了 pano,则您还可以指定 location。 只有在 API 找不到全景图 ID 时,才会使用 location

以下 URL 参数为可选参数:

  • heading 以与北方所呈的顺时针角度指示摄像头的罗盘航向。 接受的值范围是 -180° 至 360°。

  • pitch 指定摄像头的向上或向下角度。 pitch 的指定度数范围是 -90° 至 90°。 正值将使摄像头呈向上角度,而负值将使摄像头呈向下角度。 默认间距 0° 的设置取决于摄像头在拍摄图像时的位置。 因此,间距 0° 通常(但并非始终)是水平间距。 例如,在小山上拍摄的图像所呈现的默认间距可能并非水平间距。

  • fov 决定图像的水平视野。 视野以度数表示,范围是 10° - 100°。 其默认值为 90°。 在处理固定尺寸视口时,可将视野视为缩放比例,数字越小,表示缩放比例越大。

  • language 定义 UI 元素和标签所使用的语言。 默认情况下,访客看到的 UI 元素将使用其母语。

  • region 根据地缘政治敏感性定义要显示的相应边界和标签。 接受以双字符 ccTLD(顶级域)值形式指定的地区代码。

嵌入地图

如需在您的网页上使用 Google Maps Embed API,请将您生成的 URL 设置为 iframe src 属性的值。 通过 iframe 的 height 属性和 width 属性控制地图的大小:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  src="https://www.google.com/maps/embed/v1/search?key=YOUR_API_KEY&q=record+stores+in+Seattle" allowfullscreen>
</iframe>

提示:向您的 iframe 属性添加 allowfullscreen,以允许某些地图部分全屏显示。

提示frameborder="0" 属性和 style="border:0" 属性可删除地图周围的标准 iframe 边框。

您可以调整 iframe 的大小,使其适合自己网站的结构和设计,但据我们发现,访客通常认为地图越大,越便于交互。

请注意,不支持任一维度的尺寸低于 200px 的嵌入式地图。

发送以下问题的反馈:

此网页
Google Maps Embed API
Google Maps Embed API
需要帮助?请访问我们的支持页面