地点照片（新）

请选择平台： Android iOS Web 服务
欧洲经济区 (EEA) 开发者

简介

地点照片（新）服务是一个只读 API，可让您向应用添加高品质的照片内容。借助地点照片（新），您可以访问存储在地点数据库中的数百万张照片。

当您使用“地点详情（新）”“附近搜索（新）”或“文本搜索（新）”请求获取地点信息时，还可以请求相关照片内容的照片资源。使用 Place Photos（新），您可以访问所引用的照片，并根据自己的应用将图片调整为最适合的大小。

借助 API Explorer，您可以发出实时请求，以便熟悉 API 和 API 选项：

“地点照片”（新）请求

Place Photos (New) 请求是向以下格式的网址发出的 HTTP GET 请求： 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

其中，以下参数为必需参数：

  • NAME 包含照片的资源名称。
  • API_KEY 包含 API 密钥。
  • PARAMETERS 包含 maxHeightPx 参数、maxWidthPx 参数或两者兼有。

下文介绍了必需参数和可选参数的完整列表。

必需参数

照片名称

唯一标识照片的字符串标识符。照片名称通过 地点详情（新）、附近搜索（新）或文本搜索（新） 请求返回，位于 photos[] 数组中每个元素的 name 属性中。

如需查看示例，请参阅获取照片名称。

maxHeightPx 和 maxWidthPx

指定图片的最大预期高度和宽度（以像素为单位）。如果图片小于指定值，则返回原始图片。如果图片在任一维度上更大，系统会将其缩放为与较小的维度匹配，但会限制为原始宽高比。maxheight 和 maxwidth 属性均接受介于 1 到 4800 之间的整数。

您必须指定 maxHeightPx 和/或 maxWidthPx。

可选参数

skipHttpRedirect

如果值为 false（默认值），则向图片发出 HTTP 重定向，以返回图片。 如果值为 true，则跳过重定向并返回包含图片详细信息的 JSON 响应。 例如：

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

对于非 HTTP 请求，此选项会被忽略。

获取照片名称

对 Place Photos（新）的所有请求都必须包含照片资源名称，该名称在对“附近搜索（新）”“文本搜索（新）”或“地点详情（新）”请求的响应中返回。如果相应地点有相关的照片内容，则对这些请求的响应会包含一个 photos[] 数组。

photo[] 的每个元素都包含以下字段：

  • name - 在执行照片请求时，包含照片资源名称的字符串。此字符串的格式如下：

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx - 图片的最大高度（以像素为单位）。
  • widthPx - 图片的最大宽度（以像素为单位）。
  • authorAttributions[] - 任何必需的署名信息。此字段始终存在，但可能为空。

Place Photos (New) 返回的照片来自各种位置，包括商家和用户贡献的照片。在大多数情况下，使用这些照片时可以不包含提供方说明，或者可以在图片中显示必要的提供方说明。但是，如果返回的 photo 元素在 authorAttributions 字段中包含值，无论您在哪里显示相应图片，都要在应用中包含额外的提供方说明。

以下示例展示了一个包含字段掩码中 photos 的“地点详情（新）”请求，以便响应中包含 photos[] 数组：

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
 以下示例展示了响应中的 photos[] 数组。 
    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },
    ...

请求地点照片

以下示例请求使用资源 name 返回一张图片，并调整其大小，使其高度和宽度不超过 400 像素：

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

成功的 Place Photos (New) 请求的响应是一张图片。

错误代码

“地点照片（新）”请求可能会返回以下错误代码。

超出配额 (403)

如果您的请求超出可用配额，服务器会返回 HTTP 403 状态，并显示以下图片，指明配额已超出：

已超出配额通知

请求无效 (404)

如果服务器无法理解您的请求，则会返回 HTTP 400 状态，表示请求无效。无效请求最常见的原因包括：

请求次数过多 (429)

Google 建议按需加载照片。如果您尝试一次性显示某个地点的所有图片，服务器可能会返回 HTTP 429 状态，表明同时加载的照片过多。如果您收到此错误消息，请与支持团队联系，并申请增加配额。

试试看！

借助 API Explorer，您可以发出示例请求，以便熟悉 API 和 API 选项。

如需提出要求，请执行以下操作：

  1. 选择页面右侧的 API 图标 。
  2. 将 name 参数设置为： 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. 将 skipHttpRedirect 设置为 true，以便请求返回 JSON 响应。默认情况下，请求会返回 API Explorer 无法显示的图片。
  4. 选择执行按钮。在对话框中，选择您要用于提出请求的账号。

  5. 在 API 浏览器面板中，选择全屏图标 以展开 API 浏览器窗口。