地點相片

選取平台： Android iOS JavaScript 網路服務

Place API 服務是 Places API 的一部分，是一種唯讀 API，可讓您在應用程式中加入高品質相片內容。「地點相片」服務可讓您存取儲存在地點資料庫資料庫中的數百萬張相片。使用 Place Details 要求取得地點資訊時，系統會傳回相關相片內容的相片參照。Find Place、Nearby Search 和 Text Search 要求也會視情況傳回每個地點的單一相片參照。之後，您可以使用「地點相片」服務存取參照的相片，並配合應用程式將圖片調整至最佳尺寸。

地點相片要求

地點相片要求是 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，做為回應「Find Place」、「Nearby Search」、「Text Search」或「Place Details」要求的回應中。如果地點有相關的相片內容，則這類要求的回應會包含 photos[] 欄位。

注意：系統傳回的相片數量會因要求而異。

  • Find Place、Nearby Search 或 Text Search 要求最多會傳回陣列中的一個 photo 元素。
  • Place Details 要求最多會傳回十個 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 狀態，表示無效的要求。無效要求最常見的原因包括：

  • 您提交的相片參照有誤。
  • 要求不含 maxwidth 或 maxheight 參數。
  • maxwidth 或 maxheight 參數的值已設為 null。