地点照片(新)

Place Photo(新)服务是一种只读 API,可让您向应用添加高品质摄影内容。借助地点照片服务,您可以访问存储在地点数据库中的数百万张照片。

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

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

试试吧!

地点照片请求

地点照片请求是对格式如下的网址的 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 请求,系统会忽略此选项。

获取照片名称

向地点照片服务发出的所有请求都必须包含在对“附近搜索”“文本搜索”或“地点详情”请求的响应中返回的照片资源名称。如果地点具有相关的照片内容,对这些请求的响应会包含 photos[] 数组。

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

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

    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[] 数组的示例。
    ...
    "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

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

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

“超出配额”图片

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

试试看!

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

如需发出请求,请执行以下操作:

  1. name 参数设置为:
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  2. skipHttpRedirect 设置为 true,以便请求返回 JSON 响应。默认情况下,请求会返回图片,而 API Explorer 无法显示该图片。
  3. 选择执行按钮。在弹出式窗口中,选择您要用于发出请求的帐号。