一切就绪!

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

激活 Google Maps Android API

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

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

Google 地图 Intent

Google 地图 Android 应用 公开了若干个 Intent,您可以利用它们在显示模式、搜索模式、导航模式或街景模式下启动 Google 地图。 如果您想在应用内嵌入地图,请参阅 Google Maps Android API 入门指南

概览

Intent用于通过描述您想在某个Intent 对象中执行的简单操作(如“显示地图”或“显示前往机场的路线”)来启动另一应用中的某个 Activity。

Google 地图 Android 应用 支持若干种不同的 Intent,让您可以启动 Google 地图应用并执行下列四项操作之一:

  1. 以指定缩放比例显示指定位置的地图。
  2. 搜索位置或地点,并将它们显示在地图上。
  3. 请求从一个位置前往另一个位置的路线。 可返回以下三种 交通模式的路线:行车、步行、骑行。
  4. 在 Google 街景中显示全景图像。

本页面介绍可用于 Google 地图 Android 应用的 Intent。 如需了解有关 Intent 和 Intent 过滤器Android 平台通用 Intent 的详细信息,请参阅 Android 开发者文档。

Intent 请求

如需通过 Intent 启动 Google 地图,您必须先创建一个 Intent 对象,并指定其操作、URI 和软件包。

  • 操作:所有 Google 地图 Intent 都称作“查看”操作 — ACTION_VIEW
  • URI:Google 地图 Intent 使用的 URI 编码字符串指定所需操作,以及一些用于执行操作的数据。

  • 软件包:调用 setPackage("com.google.android.apps.maps") 将确保 Google 地图 Android 应用对 Intent 进行处理。 如果未设置软件包, 将由系统决定哪些应用可以处理 Intent。 如果有多个应用可用,系统可能会询问用户想要使用哪一个应用。

创建 Intent 后,您可以通过多种方式请求系统启动相关应用。 一个常见方法是将 Intent 传递给 startActivity() 方法。 系统将启动必要的应用 — 在此情况下则是 Google 地图 — 并启动相应的 Activity

// Create a Uri from an intent string. Use the result to create an Intent.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");

// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");

// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

如果系统无法找到可响应 Intent 的应用,您的应用可能会崩溃。 因此,您应该先确认接收应用已安装,然后再将其中一个 Intent 提供给用户。

如需确认存在可接收 Intent 的应用,请对 Intent 对象调用 resolveActivity()。 如果结果为非空,则至少有一个应用能够处理该 Intent,并且可以安全调用 startActivity()。 如果结果为空, 则您不应使用该 Intent。如有可能,您应禁用调用该 Intent 的功能。

if (mapIntent.resolveActivity(getPackageManager()) != null) {
    ...
}

例如,如需显示旧金山的地图,您可以使用以下代码:

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
    startActivity(mapIntent);
}

URI 编码查询字符串

传递给 Google 地图 Intent 的所有字符串都必须是 URI 编码字符串。 例如, 字符串“1st & Pike, Seattle”应编码为 1st%20%26%20Pike%2C%20Seattle。 字符串中的空格可使用 %20 编码或替换为加号 (+)。

您可以使用 android.net.Uri parse() 方法为字符串编码。 例如:

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"));

显示地图

使用 geo: Intent 可按指定缩放比例显示指定位置的地图。

geo:latitude,longitude?z=zoom

参数

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

示例

// Creates an Intent that will load a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

搜索位置

此 Intent 用于在指定视区内显示搜索查询。 如果查询只有一个结果, 您可以利用此 Intent 在特定地点或地址(如标志性建筑、商家、地理景观或城镇)显示一个图钉。

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address
geo:0,0?q=latitude,longitude(label)

参数

除了用于显示地图的参数外,搜索还支持下列参数:

  • q 定义要在地图上突出显示的地点。 q 参数是所有搜索请求的必备参数。 它接受地点名称或地址形式的位置。 字符串应为 URL 转义字符串,因此“City Hall, New York, NY”这样的地址应转换为“City+Hall,New+York,NY”。

  • label 允许您在地图上标示的地点处设置自定义标签。 label 必须以字符串形式指定。

分类搜索

如果您传递的是常规搜索词,Google 地图会尝试在您指定的经度/纬度附近查找与搜索条件匹配的位置。 如果未指定位置,Google 地图将尝试查找附近的列表。 例如:

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Search for restaurants in San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

搜索旧金山的餐馆

您可以通过指定缩放参数以及查询字符串进一步影响搜索结果。 在下例中,添加 10 这一缩放比例将尝试在城市一级而不是在附近查找餐馆。

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

位置搜索

搜索特定地址时,将在该位置处显示一个图钉。

Uri gmmIntentUri = Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

上例设置的纬度/经度为 0,0,但传递的地址采用的是查询字符串形式。 搜索非常具体的位置时,无需提供经度和纬度。 不过,如果您不知道确切地址,则可尝试通过指定坐标来影响搜索的结果。 例如, 对“Main Street”执行地址搜索将返回过多结果。

// Searching for 'Main Street' will return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

向 Intent URI 添加纬度/经度将使结果倾向于特定区域:

// Searches for 'Main Street' near San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

如果您知道搜索将返回单个值,可能希望传递可选标签。 标签必须以字符串形式指定,它们将出现在地图标记之下。 请注意,仅当以纬度/经度坐标形式指定 q 时,方可使用标签。

// Display a label at the location of Google's Sydney office
Uri gmmIntentUri = Uri.parse("geo:0,0?q=-33.8666,151.1957(Google+Sydney)");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

启动转弯提示导航

此 Intent 用于启动 Google 地图导航,获得前往指定地址或坐标的转弯提示路线。 一律以用户当前位置为起点提供路线。

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude

参数

  • q:设置导航搜索的终点。 它可以是一个纬度、经度或查询格式的地址。 如果它是返回多个结果的查询字符串, 将选择第一个结果。

  • mode 设置交通方式。 模式为可选,默认模式为行车,可设置为下列值之一:

    • d 代表行车
    • w 代表步行
    • b 代表骑行
  • avoid 设置路线应尝试避开的特征。 Avoid 为可选,可设置为下列一个或多个值:

    • t 代表收费
    • h 代表高速公路
    • f 代表渡口

示例

以下 Intent 将请求前往澳大利亚悉尼塔朗加动物园的转弯提示导航:

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

前往塔朗加动物园的路线

如果您不想支付通行费或乘坐渡船,您可以请求尽量避开这些路段的路线。

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

如果您想做一点练习,可以改为请求骑行路线。

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

显示街景全景图

可使用 google.streetview Intent 启动 Google 街景。 Google 街景提供其整个 覆盖区域内从指定位置获得的全景视图

此外,还提供用户贡献照片球街景特别收藏

google.streetview:cbll=latitude,longitude&cbp=0,bearing,0,zoom,tilt
google.streetview:panoid=id&cbp=0,bearing,0,zoom,tilt

参数

所有 google.streetview URI 都必须包括 cbllpanoid 参数。

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

  • panoid 是具体的全景图 ID。 Google 地图将在同时指定 panoidcbll 的情况下使用该全景图 ID。 全景图 ID 由 StreetViewPanoramaLocation 对象提供给 Android 应用。

  • cbp 是一个可选参数,用于调整摄像头的初始朝向。 cbp 参数带 5 个逗号分隔值,这些值均为可选值。 最重要的值是第二个值、第四个值和第五个值,它们分别用于设置方位、缩放比例和倾斜角度。 第一个值和第三个值不受支持, 应将它们设置为 0

    • bearing:以与北方所呈的顺时针角度指示摄像头的罗盘航向。 正北方为 0,东方为 90,南方为 180,西方为 270。传递给方位的值将环绕; 即 0°、360° 和 720° 都将指向同一方向。 按照定义,方位是五个逗号分隔值中的第二个值。

    • zoom:设置摄像头的缩放比例。 默认缩放比例设置为 0。缩放比例 1 将使放大倍率加倍。 缩放比例锁定在 0 与当前全景图的最大缩放比例之间。

    这意味着,任何不在此范围内的值都将设置为该范围内最接近的极值。 例如,值 -1 将设置为 0。缩放比例是五个逗号分隔值中的第四个值。

    • tilt:指定摄像头的向上或向下角度。 范围是 -90 至 0 至 90, 90 为垂直俯视,0 为水平居中,-90 为垂直仰视。

示例

以下是一些使用街景 intent 的示例。

// Displays an image of the Swiss Alp
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia
Uri gmmIntentUri = Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter will angle the camera slightly up, and towards the east.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

街景中的金字塔

发送以下问题的反馈:

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