商家識別與位置
使用商家名稱、類別、格式化地址、座標和 Maps URL 來組織本地商家資料集。
完整的介面約定請參閱 API 文件。
curl https://gmapscrawl.com/api/v1/search \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seattle-coffee-search-001" \
-d '{"q":"coffee shops in Seattle","page":1,"extra":false}'範例為空回應。正式搜尋會傳回可用的商家。請將 API 金鑰保存在伺服器端;為新任務使用新的冪等鍵,並在原請求不變的重試中保留同一冪等鍵。
{
"data": {
"total": 0,
"params": {
"q": "coffee shops in Seattle",
"page": 1,
"hl": "en",
"extra": false
},
"businesses": []
},
"request_id": "req_example",
"schema_version": "2026-09-22"
}API 在同一回應中傳回 JSON。逾時後,請使用相同的 Idempotency-Key 以不變的請求主體重試。測試憑證傳回模擬資料,不消耗您的正式額度。
結構化商家資料
從回應中讀取 data.businesses。每個商家將其清單欄位歸入 place 之下;欄位可用性取決於來源。
使用商家名稱、類別、格式化地址、座標和 Maps URL 來組織本地商家資料集。
讀取可用的電話號碼、網站、評分和評論數。啟用 extra 後,可請求電子郵件和社群聯絡方式補全。
保留 place.dataId 以查詢評論和照片。檢查 place.observedAt 和 contactsCheckedAt,瞭解資料的觀測時間。
不可用欄位可能為 null 或空值,資訊補全也可能回報 not_found 或 failed。某筆記錄並不保證對應的電子郵件或網站存在。Maps 詳情可以在保留原始觀測時間戳記的情況下重複使用最多 730 天;使用記錄前請評估其新鮮度。
瞭解資料新鮮度 →一個聚焦的請求
在 Authorization 標頭中攜帶伺服器端 API 金鑰,傳送 JSON 請求主體。只有 q 是必填的。
| 參數 | 要求 | 用途 |
|---|---|---|
| q | 必填 | 商家關鍵字和地點,例如「西雅圖的咖啡店」。長度為 2–200 個字元。 |
| page | 預設:1 | 1 到 10 之間的頁碼。每次請求最多傳回 20 家商家。 |
| ll | 可選 | 形如 @47.6062,-122.3321,12z 的 Maps 可視區域,用於引導搜尋位置。 |
| hl | 預設:en | 搜尋使用的語言代碼。 |
| gl | 可選 | 用於限定查詢的兩位國家/地區代碼,不是嚴格的地理篩選器。 |
| extra | 預設:false | 設為 true 以請求可用的電子郵件和社群聯絡方式補全。這可能會更耗時。 |
回應會在 data.params 中回顯正規化後的參數。data.total 統計的是本次回應中的商家數,而不是 Google Maps 上的商家總數。當您的工作流程需要更多結果時,請明確選擇其他頁碼。
建立您的第一個整合
Search API 是同步的:直接從 HTTP 回應中讀取結果。
在 API 工作區建立具有 scrapes:write 權限的金鑰。將金鑰存放在伺服器環境中,並在請求中傳送 Authorization: Bearer。
開啟 API 金鑰選擇一個類別和地點,請求第 1 頁,並檢查傳回的清單欄位。做市場比較時,針對要比較的各個區域分別發出搜尋。
將符合商家的 place.dataId 作為 fid,取得評論頁或相簿頁。這些是獨立的請求,各自傳回記錄。
探索 Reviews API為真實請求做規劃
每個成功的正式搜尋頁消耗一個 API 請求單位,包括空結果。REST 和 MCP 共用 API 額度。線上擷取工具和瀏覽器擴充功能的訂閱有獨立額度。速率限制、憑證、服務容量和來源可用性仍然適用。
比較 API 方案 →請在 HTTP 用戶端中允許最多 180 秒。逾時可能留下正在處理且已預留請求單位的任務。使用完全相同的請求主體和 Idempotency-Key 重試該請求。在開始新嘗試前,請先查看錯誤詳情和可重試性。
瞭解重試機制 →傳回一個 JSON 封裝,包含 data.businesses、data.total、正規化後的 data.params、request_id 和 schema_version。商家記錄包含可用的清單欄位,如名稱、地址、類別、聯絡資訊、評分和 Maps 識別碼。
可以。端點接受標準的 HTTP POST 請求,使用 JSON 和 Bearer 驗證。上方的範例使用了 Python 標準函式庫和伺服器端 JavaScript fetch。任何能傳送這些請求標頭和主體的 HTTP 用戶端都可以整合。
一個搜尋頁傳回 0 到 20 家商家。page 參數接受 1 到 10。每個成功的正式頁(包括空白頁)消耗一個 API 請求單位;一次搜尋並不保證每頁都有 20 家商家。
可以。從商家記錄中複製 place.dataId,並將其作為 fid 傳給獨立的 Reviews 或 Photos API。這些端點每次請求傳回一個有邊界的頁面。API 總覽頁連結了每個端點的欄位、範例和分頁規則。
不是。將 extra 設為 true 以請求可用的聯絡方式補全。網站、電子郵件和社群頁面都可能缺失。請檢查 enrichmentState 和 fieldStates,並在您的應用程式中明確標記不可用資料。
如果您有測試憑證,其回應是模擬的,不消耗正式 API 額度。請將這些結果標記為模擬資料。正式金鑰需要有效的 API 權益和可用的服務容量,成功的正式呼叫會消耗請求單位。