Place Photos (舊版)

歐洲經濟區 (EEA) 開發人員

Place Photos (舊版) 是 Places API 的一部分，屬於唯讀 API，可讓您在應用程式中加入高畫質相片內容。您可以透過 Place Photos (舊版)，存取儲存在 Places 資料庫中的數百萬張相片。使用 Place Details 要求取得地點資訊時，系統會傳回相片參照，提供您相關的影像內容。此外，Find Place (舊版)、Nearby Search (舊版) 和 Text Search (舊版) 要求也會視情況傳回每個地點的單一相片參照。之後，您可以使用 Place Photos (舊版) 存取參照的相片，並配合應用程式將圖片調整至最佳尺寸。

Place Photos (舊版) 要求

Place Photos (舊版) 要求的 HTTP 網址格式如下：

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

您必須加入某些參數，才能提出搜尋要求。依照網址標準，所有參數都會以 & 字元分隔。以下列出參數和可能的值。

必要參數

photo_reference

用來識別相片的專屬字串 ID。相片參照會從 Place Search 或 Place Details 要求傳回。

maxheight 或 maxwidth

maxheight：指定圖片的偏好高度上限 (以像素為單位)。如果圖片小於指定值，系統會傳回原始圖片。如果圖片在任一維度上較大，則會縮放至兩個維度中較小的一個，並限制為原始顯示比例。

maxwidth：指定圖片的偏好寬度上限 (以像素為單位)。如果圖片小於指定值，系統會傳回原始圖片。如果圖片的任一維度較大，系統會縮放圖片，使其符合兩個維度中較小的維度，並限制為原始顯示比例。

maxheight 和 maxwidth 屬性都接受介於 1 和 1600 之間的整數。

您必須指定 maxheight 或 maxwidth，或兩者皆指定。

參考相片

所有傳送至 Place Photos (舊版) 的要求都必須包含 photo_reference，這項資訊會在 Find Place (舊版)、Nearby Search (舊版)、Text Search (舊版) 或 Place Details (舊版) 要求的回應中傳回。如果地點有相關的影像內容，這些要求的回應就會包含 photos[] 欄位。

  • Find Place (舊版)、Nearby Search (舊版) 或 Text Search (舊版) 要求最多會傳回陣列中的一個 photo 元素。
  • Place Details (舊版) 要求最多會傳回十個 photo 元素。

每個 photo 元素都包含下列欄位：

  • photo_reference：執行 Place Photos (舊版) 要求時，用於識別相片的字串。
  • height：圖片高度上限。
  • width：圖片寬度上限。
  • html_attributions[]：包含任何必要的出處資訊。這個欄位一律會顯示，但可能為空。

Place Photos (舊版) 傳回的相片取自各種地點，包括業主和使用者提供的相片。在大多數情況下，使用這些相片時可以不包含作者資訊，圖片本身也可能已加入必要的作者資訊。不過，如果傳回的 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 Photos (舊版) 範例

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

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

Place Photos (舊版) 回應

Place Photos (舊版) 要求成功時，回應會是一張圖片。圖片類型取決於原本提交的相片類型。

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

超出配額圖片

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