地点照片（新）

简介

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

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

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

“地点照片（新）”请求

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 请求，系统会忽略此选项。

获取照片名称

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

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

• name - 一个字符串，用于在您执行 Google 相册请求时包含相册的资源名称。此字符串的格式如下：

  places/PLACE_ID/photos/PHOTO_RESOURCE

• heightPx - 图片的最大高度（以像素为单位）。
• widthPx - 图片的最大宽度（以像素为单位）。
• authorAttributions[] - 所有必需的提供方说明。此字段始终存在，但可能为空。

地点照片（新）返回的照片来自各种位置，包括商家和用户贡献的照片。在大多数情况下，使用这些照片时可以不包含提供方说明，或者可以在图片中显示必要的提供方说明。但是，如果返回的 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" : [
      {
        "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/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

成功地点照片（新）请求的响应是图片。图片的类型取决于最初提交的照片的类型。

错误代码

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

超出配额 (403)

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

请求无效 (404)

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

• 提交的照片名称未正确指定。
• 请求未包含 maxHeightPx 或 maxWidthPx 参数。
• maxHeightPx 或 maxWidthtPx 参数的值已设置为 null。
• name已过期。如果 name 过期，请向地点详情（新）、附近搜索（新）或文本搜索（新）发出请求，以获取新的 name。

请求过多 (429)

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

试试看！

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

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

1. 选择页面右侧的 API 图标 api。
2. 将 name 参数设置为：

   places/PLACE_ID/photos/PHOTO_RESOURCE/media

3. 将 skipHttpRedirect 设置为 true，以便请求返回 JSON 响应。默认情况下，该请求会返回图片，但 API Explorer 无法显示该图片。
4. 选择执行按钮。在对话框中，选择您要用于发出请求的账号。

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