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 状态,这表示请求无效。导致请求无效的最常见原因包括:
- 未正确指定提交的照片名称。
- 请求不包含
maxHeightPx
或maxWidthPx
参数。 maxHeightPx
或maxWidthtPx
参数的值已设置为null
。name
已过期。如果name
已过期,请向地点详情(新)、附近搜索(新)或文本搜索(新)发出请求,以获取新的name
。
试试看!
借助 API Explorer,您可以发出示例请求,以便熟悉 API 和 API 选项。
如需发出请求,请执行以下操作:
- 选择页面右侧的 API 图标 。
- 将
name
参数设置为:places/PLACE_ID/photos/PHOTO_RESOURCE/media
- 将
skipHttpRedirect
设置为true
,以便请求返回 JSON 响应。默认情况下,请求会返回图片,而 API Explorer 无法显示该图片。 - 选择执行按钮。在弹出式窗口中,选择您要用于发出请求的帐号。
在 API Explorer 面板中,选择展开图标 以展开 API Explorer 窗口。