地點相片

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

注意：伺服器端和用戶端程式庫

Places API 也適用於 Google 地圖服務適用的 Java 用戶端、Python 用戶端、Go 用戶端和 Node.js 用戶端。Places API 和用戶端程式庫適用於伺服器應用程式。

想在 JavaScript 應用程式中使用這個服務？查看 Maps JavaScript API Places Library。

Places API 的「地點相片」服務是唯讀 API，可讓您在應用程式中加入高品質的相片內容。您可以透過 Place Photo 服務，存取儲存在地點介面集資料庫中的數百萬張相片。使用 Place Details 要求取得地點資訊時，系統會傳回相片參照，提供您相關的影像內容。Find Place、Nearby Search 和 Text Search 要求也會視情況傳回每個地點的單一相片參照。之後，您可以使用「地點相片」服務存取參照的相片，並將圖片調整為最適合應用程式的大小。

Place Photo 要求

「地點相片」要求是採用下列格式的 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.
maxheight or maxwidth
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.
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.
You must specify either maxheight, or maxwidth, or both.

相片參考

傳送至「地點相片」服務的所有要求都必須包含 photo_reference，並傳回在 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 欄位中包含值，您每次顯示圖片時就必須在應用程式中另外加入屬性。

以下範例顯示 Place Details 要求：

curl "https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJcUElzOzMQQwRLuV30nMUEUM&key=YOUR_API_KEY"

以下顯示回應中的 photos[] 陣列範例。

...
"photos" : [
   {
      "html_attributions" : [],
      "height" : 853,
      "width" : 1280,
      "photo_reference" : "ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q"
   }
...

Place Photo 範例

要求範例如下所示。這項要求會傳回所參照的圖片，調整大小，將寬度不超過 400 像素。

https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q&key=YOUR_API_KEY

Place Photo 回應

成功的 Place Photo 要求回應會是圖片。圖片類型會因原始提交相片的類型而異。

如果您的要求超過可用配額，伺服器會傳回 HTTP 403 狀態並顯示下列圖片，指出已超過配額：

超過配額的圖片

如果伺服器無法理解您的要求，則會傳回 HTTP 400 狀態，表示要求無效。無效要求的常見原因包括：

提交的相片參考資訊有誤。
要求未包含 maxwidth 或 maxheight 參數。
maxwidth 或 maxheight 參數的值已設為 null。
「photo_reference」已過期。如果 photo_reference 過期，請向 Place Details、Find Place、Nearby Search 或 Text Search 提出要求，取得更新後的 photo_reference 值。