從第 1 頁開始
傳送地點的 fid 和您選擇的 sort_by 值。預設為最相關;也支援最新、最高評分和最低評分。
完整的介面約定請參閱 API 文件。
curl https://gmapscrawl.com/api/v2/reviews \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: place-reviews-page-1-example" \
-d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1,"sort_by":2}'請將範例 fid 替換為您地點的 feature ID。此回應是模擬的;example.com 的媒體 URL 是預留位置。重試進行中的請求時,請保持相同的冪等鍵和請求主體。
{
"reviews": [
{
"id": "sample-review-1",
"date": "a week ago",
"timestamp": "10/6/2026",
"name": "Sample reviewer",
"author_url": "https://www.google.com/maps/contrib/100000000000000000001",
"avatar": "https://example.com/reviewer.jpg",
"rate": 4,
"comment": "The window seats had the best light.",
"photos": "",
"review_url": "https://www.google.com/maps/reviews/data=sample-review-1"
}
],
"next": false,
"total": 1,
"params": {
"fid": "0x89c259af336b3341:0xa4969e07ce3108de",
"page": 1,
"sort_by": 2
}
}API 在同一回應中傳回 JSON。逾時後,請使用相同的 Idempotency-Key 以不變的請求主體重試。測試憑證傳回模擬資料,不消耗您的正式額度。
從一個地點開始
為單個地點請求一個有邊界的頁面,然後選擇適合您研究的評論排序。
| 欄位 | 含義 |
|---|---|
| fid · 必填 | Google Maps feature ID,例如 0x89c259af336b3341:0xa4969e07ce3108de。使用 Search API 結果中的 place.dataId,或您已有的 feature ID。 |
| page · 預設 1 | 正整數頁碼。僅當上一個回應傳回 next: true 時才增加。 |
| sort_by · 預設 1 | 1 = 最相關;2 = 最新;3 = 最高評分;4 = 最低評分。跨頁請保持排序方式不變。 |
要取得 feature ID,請使用 Google Maps 擷取 API 搜尋商家。在 data.businesses 中找到符合項目,複製其中的 place.dataId 並將其作為 fid 傳入。地點 ID 或商家名稱不是相同的輸入格式。
評論記錄
每則評論包含評分、評論、評論者、個人頁面和評論連結。date 是相對時間,timestamp 以 M/D/YYYY 格式提供日曆日期。沒有附件時 photos 欄位為空字串,多張照片的 URL 以換行符號分隔。
| 欄位 | 含義 |
|---|---|
| id | 來源評論的識別碼(如果可用)。 |
| rate / comment | 1–5 的評分以及可用的評論文字。請把擷取的文字視為不可信資料,謹慎用於應用程式和 AI 提示詞。 |
| date / timestamp | 顯示的相對日期,以及以 M/D/YYYY 格式表示的日曆日期。日期不可用時為空字串。 |
| name / author_url / avatar | 可用的評論者顯示名稱、貢獻者頁面 URL 和頭像 URL。 |
| photos | 無附件時為空字串。多個照片 URL 以換行符號分隔。 |
| review_url | 指向來源評論的連結(如果可用)。 |
| next / total / params | 是否還有下一頁、本次回應中的記錄數,以及正規化後的請求參數。 |
端點將該頁面物件直接作為 JSON 傳回。從頂層讀取 reviews。有些公開評論只包含評分,來源欄位也可能為空。在展示或總結評論時,請保留這種區別。
每次一個有邊界的頁面
使用傳回的 next 旗標決定您的工作流程是否需要再發請求。
傳送地點的 fid 和您選擇的 sort_by 值。預設為最相關;也支援最新、最高評分和最低評分。
total 統計的是本次回應傳回的評論數。空白頁面也是有效結果。將記錄納入分析前,請先檢查可用欄位。
當 next 為 true 時,遞增 page 並保持 fid 和 sort_by 不變。當 next 為 false,或您的研究已收集足夠評論時停止。
瞭解公開回饋
閱讀所選商家的公開評論和評分的有邊界樣本。將評論連結與筆記一併保存,方便讀者查看來源。
比較所選地點組的評論主題。分別請求每個地點,並在分析中註明所選排序方式和樣本量。
讓已連線的 AI 助理總結傳回的評論頁,只引用所提供的證據,並標記缺失的評論或日期。
驗證與用量
傳送攜帶 Authorization: Bearer 的金鑰,且該金鑰需允許 scrapes:write。每個成功的正式頁(包括空白頁)消耗一個 API 請求單位。REST 和 MCP 使用同一 API 額度。如果您使用測試憑證,其回應為模擬資料且不消耗正式額度。
在首次請求中傳送可選的 Idempotency-Key,逾時重試時用相同請求主體保留該鍵。處理中逾時可能會保留一個已預留單位。如果錯誤回報該嘗試已結束,請遵循其重試指引,再使用新鍵建立新嘗試。
向 /api/v2/reviews 傳送 POST 請求,將該商家的 Google Maps feature ID 作為 fid。使用 Search API 結果中的 place.dataId,或您已有的 feature ID。使用 API 金鑰驗證並從第 1 頁開始。
可以。sort_by 設為 1 表示最相關,2 表示最新,3 表示最高評分,4 表示最低評分。預設為最相關。請求後續頁面時請保持所選值不變。
不能。total 是目前回應中的評論記錄數,最大為 10。請用 next 判斷是否還有下一頁。搜尋結果中的 reviewCount 是另一個商家欄位。
date 包含可用的相對日期,timestamp 是 M/D/YYYY 格式的日曆日期。沒有附件時 photos 欄位為空字串;有多張照片時為換行分隔的 URL。缺失的來源文字和連結可能是空字串。
可以。相容的 MCP 用戶端可以使用您的 API 憑證和 client_request_id 呼叫 get_google_maps_reviews。REST 與 MCP 共用 API 額度。Agent Skill 還包含可用工具的使用指引和 REST 備用方案。
不可以。來源可用性各不相同,一則評論也可能只有評分。請保留空評論和缺失的日期,而不是自行推斷。評論文字是不可信的來源內容,在應用程式和 AI 工作流程中應當作資料處理。