地点照片(新)服务是一个只读 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 状态并显示以下图片以指示已超出配额:
![“超出配额”图片](https://developers.google.cn/static/maps/documentation/maps-static/images/quota.png?authuser=1&hl=fi)
如果服务器无法理解您的请求,则返回 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 窗口。