從第 1 頁開始
傳送地點的 fid 和第 1 頁。記錄按地點相簿提供的順序排列。
完整的介面約定請參閱 API 文件。
curl https://gmapscrawl.com/api/v2/photos \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: place-photos-page-1-example" \
-d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1}'請將範例 fid 替換為您地點的 feature ID。此回應是模擬的;example.com 的媒體 URL 是預留位置。重試進行中的請求時,請保持相同的冪等鍵和請求主體。
{
"photos": [
{
"photoUrl": "https://example.com/gallery-image.jpg"
},
{
"photoUrl": "https://example.com/gallery-preview.jpg",
"videoUrl": "https://example.com/gallery-video.mp4"
}
],
"next": false,
"total": 2,
"url": "https://www.google.com/maps/uv?pb=!1s0x89c259af336b3341:0xa4969e07ce3108de!15sCgIgAQ",
"params": {
"fid": "0x89c259af336b3341:0xa4969e07ce3108de",
"page": 1
}
}API 在同一回應中傳回 JSON。逾時後,請使用相同的 Idempotency-Key 以不變的請求主體重試。測試憑證傳回模擬資料,不消耗您的正式額度。
從一個地點開始
使用地點的 feature ID 請求其圖像和影片中繼資料。
| 欄位 | 含義 |
|---|---|
| fid · 必填 | Google Maps feature ID,例如 0x89c259af336b3341:0xa4969e07ce3108de。使用 Search API 結果中的 place.dataId,或您已有的 feature ID。 |
| page · 預設 1 | 正整數頁碼。僅當上一個回應傳回 next: true 時才增加。 |
要取得 feature ID,請使用 Google Maps 擷取 API 搜尋商家。在 data.businesses 中找到符合項目,複製其中的 place.dataId 並將其作為 fid 傳入。地點 ID 或商家名稱不是相同的輸入格式。
相簿記錄
每個項目都有用於圖像或影片預覽的 photoUrl。影片項目還包含 videoUrl。頂層的 url 指向該地點的相簿。
| 欄位 | 含義 |
|---|---|
| photoUrl | 可用的照片 URL,或影片項目的預覽圖。 |
| videoUrl | 可選的影片 URL。僅在包含影片來源的影片記錄中出現。 |
| url | 所請求地點的 Google Maps 相簿 URL。 |
| next | 是否還有下一個相簿頁。 |
| total | 本次回應中的記錄數,0 到 20。這不是該地點相簿的總大小。 |
| params | 本次回應使用的正規化 fid 和 page。 |
端點將該頁面物件直接作為 JSON 傳回。從頂層讀取 photos。API 傳回的是中繼資料和媒體連結。圖像或影片的可用性取決於來源;相簿項目並不保證有可下載的影片。
每次一個有邊界的頁面
使用傳回的 next 旗標決定您的工作流程是否需要再發請求。
傳送地點的 fid 和第 1 頁。記錄按地點相簿提供的順序排列。
total 統計的是本次回應傳回的相簿項目數。空白頁面也是有效結果。將記錄納入分析前,請先檢查可用欄位。
當 next 為 true 時,遞增 page 並保持 fid 不變。當 next 為 false,或您的工作流程已有足夠媒體記錄時停止。
直觀地探索地點
檢視與所選商家關聯的相簿,並在傳回記錄旁保留來源相簿連結。
利用可選的 videoUrl 欄位區分照片記錄和影片記錄,並在您自己的研究介面中展示可用的預覽圖。
讓已連線的 AI 助理取得一頁相簿中繼資料,並列出可用的媒體連結以供進一步檢查。
驗證與用量
傳送攜帶 Authorization: Bearer 的金鑰,且該金鑰需允許 scrapes:write。每個成功的正式頁(包括空白頁)消耗一個 API 請求單位。REST 和 MCP 使用同一 API 額度。如果您使用測試憑證,其回應為模擬資料且不消耗正式額度。
在首次請求中傳送可選的 Idempotency-Key,逾時重試時用相同請求主體保留該鍵。處理中逾時可能會保留一個已預留單位。如果錯誤回報該嘗試已結束,請遵循其重試指引,再使用新鍵建立新嘗試。
每個 JSON 回應傳回某個地點最多 20 筆照片和影片中繼資料記錄。每筆記錄都有 photoUrl,影片記錄還可能包含 videoUrl。頂層的 url 指向該地點的相簿。
在 Search API 回應中找到符合商家的 place.dataId,並將其作為 fid 傳送。您也可以提供已有的 Maps feature ID。請求後續相簿頁時使用相同的 fid。
端點以 JSON 傳回中繼資料和媒體 URL。您的應用程式可以檢查可用的連結和相簿來源。傳回哪些記錄和 URL 取決於來源可用性;photoUrl 也可能是影片的預覽圖。
從第 1 頁開始。total 統計該回應中的記錄數。如果 next 為 true,用相同的 fid 請求下一頁,並為新請求使用新的冪等鍵。當 next 為 false 或您的工作流程已有足夠記錄時停止。
Photos API 接受 fid 和 page。它按來源提供的相簿順序傳回項目,不提供評論介面那樣的 sort_by 參數。
可以。連接相容的 MCP 用戶端,使用您的 API 憑證呼叫 get_google_maps_photos。Agent Skill 還提供工作流程說明和 REST 備用方案。每個成功的正式相簿頁都使用共用 API 額度。