地点照片（新）

选择平台： Android iOS 网络服务

欧洲经济区 (EEA) 开发者

如果您的账单邮寄地址在欧洲经济区，自 2025 年 7 月 8 日起，您在使用服务时需遵守 Google Maps Platform 的欧洲经济区 (EEA) 服务条款 。具体功能因区域而异。 了解详情。

**重要提示**：使用此端点返回的数据时，您必须遵守 Places API 的适用 政策和提供方说明要求。

简介

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

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

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

试试看！

注意：输入“地点详情（新）”响应正文的 photos 数组中的地点 name，然后点击“执行”。如需查看 照片，请使用“Place Photos (New)” 响应正文中的photoUri值。

Place Photos（新）请求

地点照片（新）请求是向以下格式的网址发出的 HTTP GET 请求：

https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

其中，以下参数是必需的：

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

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

必需参数

照片名称

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

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

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[] 数组。

注意： 如需在响应中添加 photos[] 数组，请务必在请求的字段掩码中添加 photos（地点详情（新））或 places.photos（附近搜索（新）和文本搜索（新））。每个 API 最多可以为某个地点位置返回 10 张照片。

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

• name：一个字符串，其中包含您执行照片请求时照片的资源名称。此字符串的格式如下：

  places/PLACE_ID/photos/PHOTO_RESOURCE

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

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

注意：您无法缓存照片 名称。此外，名称可能会过期。请确保您始终从对“地点详情（新）”、“附近搜索（新）”或“文本搜索（新）” 的请求的响应中获取名称。如需了解详情，请参阅 Google Maps Platform 服务条款第 3.2.3(b) 条（无 缓存）中的缓存限制。

以下示例展示了一个“地点详情（新）”请求，该请求在字段掩码中包含 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（新）请求成功，响应 将是一张图片。

注意 ：图片格式可能会有所不同。系统支持标准图片格式（包括 JPEG、PNG 和 GIF），但 Google 不保证图片的格式。

错误代码

Place Photos（新）请求可能会返回以下错误代码。

超出配额 (403)

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

请求无效 (404)

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

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

请求过多 (429)

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

试试看！

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

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

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

   places/PLACE_ID/photos/PHOTO_RESOURCE/media

   注意： 请确保您使用的是最近的“地点详情（新）”请求中的 name，因为 name 可能会过期。
3. 将 skipHttpRedirect 设置为 true，以便请求返回 JSON 响应。默认情况下，请求会返回 API Explorer 无法显示的图片。
4. 选择执行 按钮。在对话框中，选择您要用于发出请求的账号。

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