本頁面由 Cloud Translation API 翻譯而成。

地點相片 (新)

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

使用 Place Details、Nearby Search 或 Text Search 要求取得地點資訊時，也可以要求相關攝影內容的相片資源。之後，您可以使用「地點相片」服務存取參照的相片，並將圖片調整為適合應用程式的大小。

您可以透過 API Explorer 發出即時要求，熟悉 API 和 API 選項：

地點相片要求

「地點相片」要求是指向網址的 HTTP GET 要求，格式如下：

https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

以下為必要參數：

NAME 包含相片的資源名稱。
API_KEY：包含 API 金鑰。
PARAMETERS 包含 maxHeightPx 參數和/或 maxWidthPx 參數。

必要和選用參數的完整清單如下。

必要參數

相片名稱

專門用來識別相片的字串 ID。系統會透過 photos[] 陣列每個元素的 name 屬性中的 Place Details (New)、Nearby Search (New) 或 Text Search (New) 要求傳回相片名稱。

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

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 Photo 服務發出的所有要求都必須包含相片資源名稱，回應 Nearby Search、Text Search 或 Place Details 要求。如果地點有相關照片內容，這些要求的回應會包含 photos[] 陣列。

注意： 如要在回應中加入 photos[] 陣列，請務必在要求的欄位遮罩中加入 photos (Place Details) 或 places.photos (Nearby Search 和 Text Search)。每個 API 最多可傳回 10 張某個地點的相片。

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

name：執行相片要求時，包含相片資源名稱的字串。這個字串的格式如下：
```
places/PLACE_ID/photos/PHOTO_RESOURCE
```
heightPx：圖片的高度上限，以像素為單位。
widthPx：圖片的寬度上限，以像素為單位。
authorAttributions[]：任何必要的作者資訊。這個欄位一律會顯示，但可能會留空。

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

下列範例顯示 Place Details 要求，其中包含欄位遮罩中的 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/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

「地點相片」要求的回應是圖片。圖片類型會因最初提交的相片類型而異。

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

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

提交的相片名稱不正確。
要求中未包含 maxHeightPx 或 maxWidthPx 參數。
maxHeightPx 或 maxWidthtPx 參數的值已設為 null。
name已過期。如果 name 過期，請向 Place Details (New)、Nearby Search (新版) 或 Text Search (新版) 提出要求，取得新的 name。

試試看！

您可以透過 API Explorer 提出範例要求熟悉 API 和 API 選項

如何提出要求：

選取頁面右側的 API 圖示。
將 name 參數設為：
```
places/PLACE_ID/photos/PHOTO_RESOURCE/media
```
注意： 請務必使用近期 Place Details 要求中的 name，因為 name 可能會過期。
將 skipHttpRedirect 設為 true，讓要求傳回 JSON 回應。根據預設，要求會傳回圖片，而 API Explorer 無法顯示圖片。
選取「執行」按鈕。在彈出式視窗中，選擇要用來提出要求的帳戶。
在 API Explorer 面板中選取展開圖示，展開 API Explorer 視窗。