Place Photo (新) 服務是唯讀 API 應用程式的圖片內容Place Photo 服務提供 存取地點介面集資料庫中的數百萬張相片。
使用 Place Details、Nearby Search 或 Text Search 要求取得地點資訊時, 你也可以針對相關的影像內容要求相片資源。使用「相片」服務 之後,您可以查看參照的相片,並將圖片調整成最適合您的 應用程式。
API Explorer 可讓您發出即時要求,以便熟悉 API 以及 API 選項:
試試看!Place Photo 要求
地點相片要求是 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 狀態並顯示下方圖片,表示配額已 超過:
![超過配額的圖片](https://developers.google.cn/static/maps/documentation/maps-static/images/quota.png?authuser=5&hl=zh-tw)
如果伺服器無法理解您的要求,則會傳回 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」視窗。