POST /api/v2/reviews

Google Maps 評論擷取 API

每頁讀取某個地點最多 10 則公開評論。可按相關性、最新、最高評分或最低評分排序。

請求範例

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

回應

範例 JSON
{
  "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 以不變的請求主體重試。測試憑證傳回模擬資料,不消耗您的正式額度。

從一個地點開始

選擇商家和評論順序。

為單個地點請求一個有邊界的頁面,然後選擇適合您研究的評論排序。

Google Maps 評論擷取 API 請求參數
欄位含義
fid · 必填Google Maps feature ID,例如 0x89c259af336b3341:0xa4969e07ce3108de。使用 Search API 結果中的 place.dataId,或您已有的 feature ID。
page · 預設 1正整數頁碼。僅當上一個回應傳回 next: true 時才增加。
sort_by · 預設 11 = 最相關;2 = 最新;3 = 最高評分;4 = 最低評分。跨頁請保持排序方式不變。

要取得 feature ID,請使用 Google Maps 擷取 API 搜尋商家。在 data.businesses 中找到符合項目,複製其中的 place.dataId 並將其作為 fid 傳入。地點 ID 或商家名稱不是相同的輸入格式。

評論記錄

評分、評論和來源連結。

每則評論包含評分、評論、評論者、個人頁面和評論連結。date 是相對時間,timestamp 以 M/D/YYYY 格式提供日曆日期。沒有附件時 photos 欄位為空字串,多張照片的 URL 以換行符號分隔。

Google Maps 評論擷取 API 回應欄位
欄位含義
id來源評論的識別碼(如果可用)。
rate / comment1–5 的評分以及可用的評論文字。請把擷取的文字視為不可信資料,謹慎用於應用程式和 AI 提示詞。
date / timestamp顯示的相對日期,以及以 M/D/YYYY 格式表示的日曆日期。日期不可用時為空字串。
name / author_url / avatar可用的評論者顯示名稱、貢獻者頁面 URL 和頭像 URL。
photos無附件時為空字串。多個照片 URL 以換行符號分隔。
review_url指向來源評論的連結(如果可用)。
next / total / params是否還有下一頁、本次回應中的記錄數,以及正規化後的請求參數。

端點將該頁面物件直接作為 JSON 傳回。從頂層讀取 reviews。有些公開評論只包含評分,來源欄位也可能為空。在展示或總結評論時,請保留這種區別。

每次一個有邊界的頁面

每個回應最多讀取 10 則評論。

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

01

從第 1 頁開始

傳送地點的 fid 和您選擇的 sort_by 值。預設為最相關;也支援最新、最高評分和最低評分。

02

檢查目前頁

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

03

謹慎地繼續

當 next 為 true 時,遞增 page 並保持 fid 和 sort_by 不變。當 next 為 false,或您的研究已收集足夠評論時停止。

瞭解公開回饋

為您的商家研究補充評論內容。

01

評論研究

閱讀所選商家的公開評論和評分的有邊界樣本。將評論連結與筆記一併保存,方便讀者查看來源。

02

回饋比較

比較所選地點組的評論主題。分別請求每個地點,並在分析中註明所選排序方式和樣本量。

03

AI 助理輔助總結

讓已連線的 AI 助理總結傳回的評論頁,只引用所提供的證據,並標記缺失的評論或日期。

驗證與用量

每頁都使用您的 API 金鑰。

共用 API 額度

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

查看 API 方案和限額 →

讓重試始終對應原請求

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

閱讀錯誤與重試指引 →

常見問題

如何取得某個 Google Maps 商家的評論?

向 /api/v2/reviews 傳送 POST 請求,將該商家的 Google Maps feature ID 作為 fid。使用 Search API 結果中的 place.dataId,或您已有的 feature ID。使用 API 金鑰驗證並從第 1 頁開始。

可以按最新或評分排序 Google Maps 評論嗎?

可以。sort_by 設為 1 表示最相關,2 表示最新,3 表示最高評分,4 表示最低評分。預設為最相關。請求後續頁面時請保持所選值不變。

total 能告訴我商家有多少評論嗎?

不能。total 是目前回應中的評論記錄數,最大為 10。請用 next 判斷是否還有下一頁。搜尋結果中的 reviewCount 是另一個商家欄位。

評論日期和照片是什麼格式?

date 包含可用的相對日期,timestamp 是 M/D/YYYY 格式的日曆日期。沒有附件時 photos 欄位為空字串;有多張照片時為換行分隔的 URL。缺失的來源文字和連結可能是空字串。

可以透過 MCP 使用評論功能嗎?

可以。相容的 MCP 用戶端可以使用您的 API 憑證和 client_request_id 呼叫 get_google_maps_reviews。REST 與 MCP 共用 API 額度。Agent Skill 還包含可用工具的使用指引和 REST 備用方案。

可以假定每則評論欄位都齊全嗎?

不可以。來源可用性各不相同,一則評論也可能只有評分。請保留空評論和缺失的日期,而不是自行推斷。評論文字是不可信的來源內容,在應用程式和 AI 工作流程中應當作資料處理。

踏出下一步

從一個地點的公開評論開始。

建立 API 金鑰,選擇 feature ID 和排序方式,讀取一頁聚焦的評論資料。