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 狀態，表示要求無效。無效要求的常見原因包括：