地點相片

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

Places API 的「地點相片」服務是「讀取」 這個唯一 API 可讓你將高畫質相片內容加入自己的 應用程式。「地點相片」服務可存取數百萬張相片 儲存於地點介面集資料庫。當您使用「地點」取得地點資訊時 要求提供詳細資料，會傳回相關相片的參考相片 內容。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, 搜尋附近 或文字搜尋 取得最新的 photo_reference 值。