地點相片 (新)

選取平台： Android iOS 網路服務
歐洲經濟區 (EEA) 開發人員

簡介

Place Photos (New) 服務是唯讀 API，可讓您在應用程式中加入高品質的相片內容。您可以透過「地點相片 (新版)」存取儲存在地點資料庫中的數百萬張相片。

使用 Place Details (新版)、Nearby Search (新版) 或 Text Search (新版) 要求取得地點資訊時，您也可以要求相關影像內容的相片資源。之後，您可以使用「地點相片 (新版)」存取參照的相片，並配合應用程式將圖片調整至最佳尺寸。

您可以使用 APIs Explorer 傳送即時要求，熟悉 API 和 API 選項：

Place Photos (New) 要求

地點相片 (新版) 要求是向網址發出的 HTTP GET 要求，格式如下： 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

以下是必要參數：

  • NAME 包含相片的資源名稱。
  • API_KEY 包含 API 金鑰。
  • PARAMETERS 包含 maxHeightPx 參數、maxWidthPx 參數或兩者。

以下列出必要和選用參數的完整清單。

必要參數

相片名稱

可明確識別相片的字串 ID。相片名稱會透過 Place Details (新版)、Nearby Search (新版) 或 Text Search (新版) 要求，在 photos[] 陣列中每個元素的 name 屬性中傳回。

如需範例，請參閱「取得相片名稱」。

maxHeightPx 和 maxWidthPx

指定圖片的最大預期高度和寬度 (以像素為單位)。如果圖片小於指定值，系統會傳回原始圖片。如果圖片任一維度較大，系統會縮放圖片，使其符合較小的維度，並保留原始顯示比例。maxheight 和 maxwidth 屬性都接受介於 1 到 4800 之間的整數。

您必須指定 maxHeightPx、maxWidthPx 或兩者。

選用參數

skipHttpRedirect

如果為 false (預設)，請對圖片進行 HTTP 重新導向，以傳回圖片。 如果 true，請略過重新導向，並傳回包含圖片詳細資料的 JSON 回應。 例如：

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

非 HTTP 要求會忽略這個選項。

取得相片名稱

所有 Place Photos (新版) 要求都必須包含相片資源名稱，這項名稱會在 Nearby Search (新版)、Text Search (新版) 或 Place Details (新版) 要求的回應中傳回。如果地點有相關的影像內容，這些要求的回應會包含 photos[] 陣列。

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

  • name：字串，內含您執行相片要求時的相片資源名稱。這個字串的格式如下：

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx：圖片的高度上限 (以像素為單位)。
  • widthPx：圖片寬度上限 (以像素為單位)。
  • authorAttributions[] - 任何必要出處資訊。這個欄位一律會顯示，但可能為空。

「地點相片 (新版)」服務傳回的相片取自各種地點，包括業主和使用者提供的相片。在大多數情況下，使用這些相片時可以不包含作者資訊，圖片本身也可能已加入必要的作者資訊。不過，如果傳回的 photo 元素在 authorAttributions 欄位中包含值，您每次顯示圖片時就必須在應用程式中另外加入作者資訊。

以下範例顯示 Place Details (New) 要求，其中包含欄位遮罩中的 photos，因此回應會包含 photos[] 陣列：

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
 以下是回應中 photos[] 陣列的範例。 
    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },
    ...

要求地點相片

以下範例要求會使用資源 name 傳回圖片，並調整圖片大小，使圖片高度和寬度最多為 400 像素：

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

如果地點相片 (新版) 要求成功，回應會是圖片。

錯誤代碼

Place Photos (New) 要求可能會傳回下列錯誤代碼。

超過配額 (403)

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

配額已超過通知

要求無效 (404)

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

要求數量過多 (429)

Google 建議您視需要載入相片。如果嘗試一次顯示某地點的所有圖片，伺服器可能會傳回 HTTP 429 狀態，表示同時載入的相片過多。如果收到這則錯誤訊息，請與支援團隊聯絡，並要求提高配額。

試試看！

您可以使用 API Explorer 提出範例要求，熟悉 API 和 API 選項。

如何提出要求：

  1. 選取頁面右側的 API 圖示 。
  2. 將 name 參數設為： 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. 將 skipHttpRedirect 設為 true，要求就會傳回 JSON 回應。根據預設，要求會傳回圖片，但 API Explorer 無法顯示。
  4. 選取「執行」按鈕。在對話方塊中，選擇要用於提出要求的帳戶。

  5. 在 API Explorer 面板中，選取全螢幕圖示 ，展開 API Explorer 視窗。