地點相片

Places Photo 服務屬於 Places API 的一部分,這個唯讀 API 可讓您在應用程式中加入高畫質相片內容。「地點相片」服務可讓您存取「地點」資料庫中儲存的數百萬張相片。使用 Place Details 要求取得地點資訊時,系統會傳回相關相片內容的相片參考。如果找到相關地點,「尋找地點」、「附近搜尋」和「文字搜尋」要求也會傳回每個地點的單一相片參考。然後,您可以使用相簿服務存取參照的相片,並將圖片調整為適合您應用程式的大小。

地點相片要求

「地點相片」要求是採用以下格式的 HTTP 網址:

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