POST /api/v1/search

Google Maps 擷取 API

按關鍵字和地點尋找商家。在同一個 JSON 回應中接收最多 20 筆結構化商家記錄,可直接用於您的應用程式或研究工作流程。

請求範例

完整的介面約定請參閱 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 金鑰保存在伺服器端;為新任務使用新的冪等鍵,並在原請求不變的重試中保留同一冪等鍵。

回應

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

結構化商家資料

從 Maps 搜尋到可用記錄。

從回應中讀取 data.businesses。每個商家將其清單欄位歸入 place 之下;欄位可用性取決於來源。

01

商家識別與位置

使用商家名稱、類別、格式化地址、座標和 Maps URL 來組織本地商家資料集。

02

聯絡方式與聲譽

讀取可用的電話號碼、網站、評分和評論數。啟用 extra 後,可請求電子郵件和社群聯絡方式補全。

03

識別碼與觀測日期

保留 place.dataId 以查詢評論和照片。檢查 place.observedAt 和 contactsCheckedAt,瞭解資料的觀測時間。

讓缺失和較舊的資料保持可見

不可用欄位可能為 null 或空值,資訊補全也可能回報 not_found 或 failed。某筆記錄並不保證對應的電子郵件或網站存在。Maps 詳情可以在保留原始觀測時間戳記的情況下重複使用最多 730 天;使用記錄前請評估其新鮮度。

瞭解資料新鮮度 →

一個聚焦的請求

選擇查詢、頁碼和補全選項。

在 Authorization 標頭中攜帶伺服器端 API 金鑰,傳送 JSON 請求主體。只有 q 是必填的。

Google Maps Search API 參數
參數要求用途
q必填商家關鍵字和地點,例如「西雅圖的咖啡店」。長度為 2–200 個字元。
page預設:11 到 10 之間的頁碼。每次請求最多傳回 20 家商家。
ll可選形如 @47.6062,-122.3321,12z 的 Maps 可視區域,用於引導搜尋位置。
hl預設:en搜尋使用的語言代碼。
gl可選用於限定查詢的兩位國家/地區代碼,不是嚴格的地理篩選器。
extra預設:false設為 true 以請求可用的電子郵件和社群聯絡方式補全。這可能會更耗時。

回應會在 data.params 中回顯正規化後的參數。data.total 統計的是本次回應中的商家數,而不是 Google Maps 上的商家總數。當您的工作流程需要更多結果時,請明確選擇其他頁碼。

建立您的第一個整合

一個請求,一個有用的下一步。

Search API 是同步的:直接從 HTTP 回應中讀取結果。

01

建立您的 API 金鑰

在 API 工作區建立具有 scrapes:write 權限的金鑰。將金鑰存放在伺服器環境中,並在請求中傳送 Authorization: Bearer。

開啟 API 金鑰
02

搜尋一個有邊界的區域

選擇一個類別和地點,請求第 1 頁,並檢查傳回的清單欄位。做市場比較時,針對要比較的各個區域分別發出搜尋。

03

跟隨地點識別碼

將符合商家的 place.dataId 作為 fid,取得評論頁或相簿頁。這些是獨立的請求,各自傳回記錄。

探索 Reviews API

為真實請求做規劃

頁面可預測,限額明確。

用量與可用性

每個成功的正式搜尋頁消耗一個 API 請求單位,包括空結果。REST 和 MCP 共用 API 額度。線上擷取工具和瀏覽器擴充功能的訂閱有獨立額度。速率限制、憑證、服務容量和來源可用性仍然適用。

比較 API 方案 →

逾時與重試

請在 HTTP 用戶端中允許最多 180 秒。逾時可能留下正在處理且已預留請求單位的任務。使用完全相同的請求主體和 Idempotency-Key 重試該請求。在開始新嘗試前,請先查看錯誤詳情和可重試性。

瞭解重試機制 →

繼續您的工作流程

使用同一批商家資料的更多方式。

01

評論與相簿資料

使用地點的 feature ID 取得公開評論或照片和影片中繼資料。

探索相簿資料
02

連接 MCP 用戶端

讓相容的 AI 用戶端使用您的 API 憑證探索搜尋、評論和照片工具。

設定 MCP
03

安裝 Agent Skill

為您的 AI 助理提供工作流程說明、操作參考和用於 Google Maps 研究的 REST 備用方案。

探索此技能

常見問題

Google Maps 擷取 API 傳回什麼?

傳回一個 JSON 封裝,包含 data.businesses、data.total、正規化後的 data.params、request_id 和 schema_version。商家記錄包含可用的清單欄位,如名稱、地址、類別、聯絡資訊、評分和 Maps 識別碼。

我可以在 Python 或 JavaScript 中使用此 API 嗎?

可以。端點接受標準的 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 權益和可用的服務容量,成功的正式呼叫會消耗請求單位。

踏出下一步

建立您的第一次 Google Maps 搜尋。

建立 API 金鑰,選擇一個查詢和地點,並在同一回應中讀取結構化商家資料。