Place Photo (新版) 服務是唯讀 API,可讓您在應用程式中加入高品質的相片內容。您可以透過 Place Photo 服務,存取數百萬張儲存在地點介面集資料庫的相片。
使用 Place Details、搜尋附近或搜尋文字要求取得地點資訊時,您也可以要求相關相片內容的相片資源。之後,您可以使用「地點相片」服務存取參照的相片,並配合應用程式將圖片調整至最佳尺寸。
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。相片名稱會透過 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 要求的這個選項。
取得相片名稱
傳送至「地點相片」服務的所有要求都必須包含相片資源名稱,並在 Nearby Search、Text Search 或 Place Details 要求的回應中傳回。如果地點有相關攝影內容,則回應這些要求的回應會包含 photos[]
陣列。
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
成功的 Place Photo 要求回應會是圖片。圖片類型取決於原始提交的相片類型。
如果要求超出可用配額,伺服器會傳回 HTTP 403 狀態,並顯示下圖,表示已超出配額:
如果伺服器無法瞭解您的要求,就會傳回 HTTP 400 狀態,表示要求無效。無效要求最常見的原因包括:
- 提交的相片名稱有誤。
- 要求未包含
maxHeightPx
或maxWidthPx
參數。 maxHeightPx
或maxWidthtPx
參數的值已設為null
。name
已過期。如果name
到期,請向 Place Details (新版)、Nearby Search (新版) 或 Text Search (新版) 提出要求,以取得新的name
。
試試看!
您可以使用 API Explorer 提出範例要求,熟悉 API 和 API 選項。
提出要求的方法如下:
- 選取頁面右側的 API 圖示 。
- 將
name
參數設為:places/PLACE_ID/photos/PHOTO_RESOURCE/media
- 將
skipHttpRedirect
設為true
,讓要求傳回 JSON 回應。根據預設,要求會傳回圖片,但 API Explorer 無法顯示圖片。 - 選取「執行」按鈕。在彈出式視窗中,選擇要用來提出要求的帳戶。
在「API Explorer」面板中選取展開圖示 ,展開「API Explorer」視窗。