地点照片

选择平台Android iOS JavaScript Web 服务

地点照片服务是 Places API 的一部分,是一种只读 API,可支持您将高品质照片内容添加到应用中。借助地点照片服务,您可以访问存储在“地点”数据库中的数百万张照片。当您使用“地点详情”请求获取地点信息时,系统会返回相关照片内容的照片引用。“查找地点”、“附近搜索”和“文字搜索”请求也会为每个地点返回一个照片引用(如相关)。然后,您可以使用照片服务访问引用的照片,并将图片调整为适合您的应用的最佳尺寸。

地点照片请求

地点照片请求是一个 HTTP URL,其格式如下:

https://maps.googleapis.com/maps/api/place/photo?parameters

您需要使用某些参数,才能发起搜索请求。根据网址的标准,所有参数均使用和号字符 (&) 进行分隔。下面枚举了参数及其可能的值。

Required parameters

  • photo_reference

    A string identifier that uniquely identifies a photo. Photo references are returned from either a Place Search or Place Details request.

Optional parameters

  • maxheight

    Specifies the maximum desired height, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio. Both the maxheight and maxwidth properties accept an integer between 1 and 1600.

  • maxwidth

    Specifies the maximum desired width, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio. Both the maxheight and maxwidth properties accept an integer between 1 and 1600.

Generated from the OpenAPI specification. Edit Report bug

照片引用

对地点照片服务的所有请求都必须包含 photoreference,它会在查找地点、附近搜索、文本搜索或地点详情请求的响应中返回。如果地点有相关的摄影内容,对这些请求的响应将包含 photos[] 字段。

注意:返回的照片数量因请求而异。

  • “查找地点”、“附近搜索”或“文字搜索”请求最多返回数组中的一个 photo 元素。
  • 地点详情请求最多返回十个 photo 元素。

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

  • photo_reference - 当您执行照片请求时用于识别照片的字符串。
  • height - 图片的高度上限。
  • width - 图片的宽度上限。
  • html_attributions[] - 包含任何必需的归因。此字段将始终存在,但可能为空。

照片服务返回的照片来自各种位置,包括商家所有者和用户贡献的照片。在大多数情况下,使用这些照片时不会注明出处,或者会将必需的出处作为图片的一部分。不过,如果返回的 photo 元素在 html_attributions 字段中包含值,则无论在何处显示图片,您都必须在应用中添加额外的提供方信息。

下面显示了一个 photos[] 数组示例。

...
"photos" : [
   {
      "html_attributions" : [],
      "height" : 853,
      "width" : 1280,
      "photo_reference" : "CnRvAAAAwMpdHeWlXl-lH0vp7lez4znKPIWSWvgvZFISdKx45AwJVP1Qp37YOrH7sqHMJ8C-vBDC546decipPHchJhHZL94RcTUfPa1jWzo-rSHaTlbNtjh-N68RkcToUCuY9v2HNpo5mziqkir37WU8FJEqVBIQ4k938TI3e7bf8xq-uwDZcxoUbO_ZJzPxremiQurAYzCTwRhE_V0"
   }
...

地点照片示例

下面显示了一个请求示例。此请求将返回所引用的图片,并调整其大小以使其宽度不超过 400 像素。

https://maps.googleapis.com/maps/api/place/photo
  ?maxwidth=400
  &photo_reference=Aap_uEA7vb0DDYVJWEaX3O-AtYp77AaswQKSGtDaimt3gt7QCNpdjp1BkdM6acJ96xTec3tsV_ZJNL_JP-lqsVxydG3nh739RE_hepOOL05tfJh2_ranjMadb3VoBYFvF0ma6S24qZ6QJUuV6sSRrhCskSBP5C1myCzsebztMfGvm7ij3gZT
  &key=YOUR_API_KEY

地点照片回复

地点照片请求成功后,系统会返回一张图片。图片的类型取决于最初提交的照片的类型。

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

超出配额的图片

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

  • 未正确指定提交的照片引用。
  • 请求未包含 maxwidthmaxheight 参数。
  • maxwidthmaxheight 参数的值已设置为 null