POST /api/v2/photos

Google Maps 照片擷取 API

每頁讀取某個地點最多 20 筆相簿內容。按照片在相簿中出現的順序取得照片和影片 URL。

請求範例

完整的介面約定請參閱 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 是預留位置。重試進行中的請求時,請保持相同的冪等鍵和請求主體。

回應

範例 JSON
{
  "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 請求其圖像和影片中繼資料。

Google Maps 照片擷取 API 請求參數
欄位含義
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 指向該地點的相簿。

Google Maps 照片擷取 API 回應欄位
欄位含義
photoUrl可用的照片 URL,或影片項目的預覽圖。
videoUrl可選的影片 URL。僅在包含影片來源的影片記錄中出現。
url所請求地點的 Google Maps 相簿 URL。
next是否還有下一個相簿頁。
total本次回應中的記錄數,0 到 20。這不是該地點相簿的總大小。
params本次回應使用的正規化 fid 和 page。

端點將該頁面物件直接作為 JSON 傳回。從頂層讀取 photos。API 傳回的是中繼資料和媒體連結。圖像或影片的可用性取決於來源;相簿項目並不保證有可下載的影片。

每次一個有邊界的頁面

每個回應最多讀取 20 筆相簿內容。

使用傳回的 next 旗標決定您的工作流程是否需要再發請求。

01

從第 1 頁開始

傳送地點的 fid 和第 1 頁。記錄按地點相簿提供的順序排列。

02

檢查目前頁

total 統計的是本次回應傳回的相簿項目數。空白頁面也是有效結果。將記錄納入分析前,請先檢查可用欄位。

03

謹慎地繼續

當 next 為 true 時,遞增 page 並保持 fid 不變。當 next 為 false,或您的工作流程已有足夠媒體記錄時停止。

直觀地探索地點

把相簿中繼資料帶進您的研究工作流程。

01

商家清單研究

檢視與所選商家關聯的相簿,並在傳回記錄旁保留來源相簿連結。

02

照片和影片整理

利用可選的 videoUrl 欄位區分照片記錄和影片記錄,並在您自己的研究介面中展示可用的預覽圖。

03

AI 助理輔助相簿檢視

讓已連線的 AI 助理取得一頁相簿中繼資料,並列出可用的媒體連結以供進一步檢查。

驗證與用量

每頁都使用您的 API 金鑰。

共用 API 額度

傳送攜帶 Authorization: Bearer 的金鑰,且該金鑰需允許 scrapes:write。每個成功的正式頁(包括空白頁)消耗一個 API 請求單位。REST 和 MCP 使用同一 API 額度。如果您使用測試憑證,其回應為模擬資料且不消耗正式額度。

查看 API 方案和限額 →

讓重試始終對應原請求

在首次請求中傳送可選的 Idempotency-Key,逾時重試時用相同請求主體保留該鍵。處理中逾時可能會保留一個已預留單位。如果錯誤回報該嘗試已結束,請遵循其重試指引,再使用新鍵建立新嘗試。

閱讀錯誤與重試指引 →

常見問題

Google Maps 照片擷取 API 傳回什麼?

每個 JSON 回應傳回某個地點最多 20 筆照片和影片中繼資料記錄。每筆記錄都有 photoUrl,影片記錄還可能包含 videoUrl。頂層的 url 指向該地點的相簿。

如何取得地點相簿的 feature ID?

在 Search API 回應中找到符合商家的 place.dataId,並將其作為 fid 傳送。您也可以提供已有的 Maps feature ID。請求後續相簿頁時使用相同的 fid。

Photos API 會下載圖像或影片檔案嗎?

端點以 JSON 傳回中繼資料和媒體 URL。您的應用程式可以檢查可用的連結和相簿來源。傳回哪些記錄和 URL 取決於來源可用性;photoUrl 也可能是影片的預覽圖。

如何對 Google Maps 相簿分頁?

從第 1 頁開始。total 統計該回應中的記錄數。如果 next 為 true,用相同的 fid 請求下一頁,並為新請求使用新的冪等鍵。當 next 為 false 或您的工作流程已有足夠記錄時停止。

相簿順序可以設定嗎?

Photos API 接受 fid 和 page。它按來源提供的相簿順序傳回項目,不提供評論介面那樣的 sort_by 參數。

AI 助理能取得相簿中繼資料嗎?

可以。連接相容的 MCP 用戶端,使用您的 API 憑證呼叫 get_google_maps_photos。Agent Skill 還提供工作流程說明和 REST 備用方案。每個成功的正式相簿頁都使用共用 API 額度。

踏出下一步

探索某個地點的相簿。

建立 API 金鑰,提供地點的 feature ID,取得結構化的照片和影片中繼資料。