Google Maps 資料 / Agent Skill

為您的 AI 助理提供可重複使用的資料工作流程。

一個可攜式技能,用於尋找商家、閱讀公開評論和檢視地點相簿。將說明、參考資料和 REST 輔助程式一起安裝。

Node.js 24本機技能目錄已設定的 MCP 或 REST安裝無需金鑰

01 / 安裝完整套件

一次小型安裝,為每個請求提供有用的內容。

使用 Node.js 24 和能從本機目錄載入技能的 AI 助理執行環境。選擇您的執行環境支援的技能位置。

  1. 01

    下載並檢查

    將安裝程式儲存到本機。執行指令前,請先閱讀安裝程式、技能說明和資訊清單。

  2. 02

    選擇一個新目錄

    將範例路徑替換為您的執行環境的技能目錄。安裝程式會取得完整套件並驗證 SHA-256 總和檢查碼;它不會覆寫現有安裝。

  3. 03

    啟用技能並連線

    在您的 AI 助理執行環境中載入已安裝的資料夾。優先使用您已設定的 MCP 連線;如需 REST 備用方案,請透過私密執行環境提供 GMSCRAPER_API_KEY。

安裝不需要 API 金鑰。資料請求仍需要 API 工作區金鑰、相應權限範圍,以及允許所請求介面的 API 方案。

終端機 · 安裝

將 /path/to/skills 替換為您的執行環境的技能目錄。在執行 node 指令前先檢查下載的指令碼。

curl --fail --silent --show-error \
  https://gmapscrawl.com/skills/google-maps-data/scripts/install.mjs \
  --output /tmp/install-google-maps-data.mjs

# Review the installer, then install into a NEW directory:
node /tmp/install-google-maps-data.mjs \
  /path/to/skills/google-maps-data

02 / 您的第一個工作流程

從一個問題開始,以傳回的資料結束。

啟用技能,並使用您的測試憑證嘗試一次搜尋。測試回應是模擬資料,消耗 0 個正式請求單位。

詢問您的 AI 助理
使用 Google Maps Data 技能和我設定的測試憑證。
搜尋一頁西雅圖的咖啡店,extra 為 false。
顯示回應中的名稱、網站、評分和評論數。
保留缺失值和來源觀測日期。
將所有測試資料標記為模擬資料。完成這一次請求後停止。

工作流程預覽

一次聚焦的搜尋,有明確的限制。

  1. 01選擇操作

    技能會透過 MCP 選擇 search_google_maps,或在 REST 輔助程式中選擇 places.search。

  2. 02發出一次請求

    第 1 頁、extra 為 false,以及一個新的 client_request_id。新任務使用新 ID;同一重試保留其輸入和 ID。

  3. 03讀取並解釋

    使用傳回的 businesses、params 和 total。展示可用欄位,並將結果標記為模擬資料。

正式搜尋每頁最多傳回 20 家商家。回應直接到達,無需任務輪詢。

03 / 套件內有什麼

工具負責連線,技能提供操作手冊。

請保持整個資料夾完整。SKILL.md 連結到補全工作流程所需的操作參考和輔助指令碼。

01

選擇正確的操作

用商家搜尋做發掘,用評論取得公開回饋,用照片取得相簿記錄。從商家切換到其媒體內容時,從 place.dataId 取得 feature ID。

02

尊重任務邊界

只請求所需的頁數,為不確定的重試保留請求 ID,並在驗證、校驗、配額或功能錯誤處停止。

03

準確解釋資料

保留缺失欄位和來源時間戳記。將擷取的描述、評論和 URL 視為資料;將模擬回應標記為固定測試資料。

google-maps-data/

SKILL.md
工作流程說明和工具選擇指引。
references/operations.json
機器可讀的操作輸入、端點和約束。
references/operations.md
搜尋、評論和照片請求範例。
references/result-schema.md
結果欄位、限制和來源出處。
scripts/gmapscraper-request.mjs
用於請求文件的零相依 REST 備用方案。
scripts/install.mjs + manifest.json
完整套件下載和 SHA-256 驗證。
agents/openai.yaml
面向相容執行環境的 AI 助理中繼資料。

04 / 讓技能發揮作用

可重複使用的工作流程,有明確的停止點。

這些範例提示詞描述了要發出的請求和要產生的結果。實際可用性和傳回欄位由服務決定。

研究本地市場

“使用 Google Maps Data 技能和我設定的憑證。搜尋波特蘭獨立書店的第 1 頁,extra 為 false。顯示傳回的名稱、網站、評分和評論數。保留缺失值和觀測日期。完成一個搜尋頁後停止。”

預期結果

一張最多 20 家傳回商家的表格,保留來源查詢和明確的缺失值。

1 個成功的正式頁

Search API

檢視客戶回饋

“對於我選定的商家,將 place.dataId 作為 fid,取得評論第 1 頁,sort_by 為 2。總結傳回評論的主題並註明日期和評分。說明這只是一頁,而非全部評論。不要取得另一頁。”

預期結果

一份基於最多 10 則傳回評論的總結,以及傳回的 next 分頁狀態。

1 個成功的正式評論頁

Reviews API

準備地點研究簡報

“對提供的 feature ID,僅取得 sort_by 為 1 的評論第 1 頁和照片第 1 頁。回報評論主題,並列出傳回的 photoUrl 和可選 videoUrl 值。保留缺失欄位,不下載媒體,完成這兩個請求後停止。”

預期結果

一份有限的簡報,使用同一地點最多 10 則評論和 20 筆相簿記錄。

2 個成功的正式頁

Photos API

每個成功的正式頁消耗一個 API 請求單位,包括空白頁。僅當任務需要且傳回的 next 允許時才請求另一媒體頁。測試請求消耗 0 個單位。

05 / REST 備用方案

當 MCP 不可用時,使用同一工作流程。

內建的輔助程式讀取本機 JSON 請求文件並呼叫標準 REST 端點。它只使用 Node.js 標準函式庫。

儲存一個請求,執行輔助程式。

  • 在您的私密環境中提供 GMSCRAPER_API_KEY。
  • 將某個範例儲存為已安裝技能目錄中的 request.json。
  • 為每個新操作產生新的 16–128 字元 client_request_id。
  • 重試不確定的請求時,保持相同 ID 和相同輸入。
node scripts/gmapscraper-request.mjs request.json

輔助程式將 client_request_id 對應到 REST 的 Idempotency-Key。搜尋使用 /api/v1/search;評論和照片使用 /api/v2/reviews 和 /api/v2/photos。

探索 REST API
request.json · 選擇一個操作

一個搜尋頁。測試金鑰傳回模擬資料;正式請求使用您的 API 額度。

{
  "operation": "places.search",
  "input": {
    "q": "coffee shops in Seattle",
    "page": 1,
    "extra": false
  },
  "client_request_id": "seattle-coffee-skill-test-001"
}

06 / 保持可用

一次完整安裝,一次謹慎的更新。

使用資訊清單和傳回的錯誤來檢查套件和您的連線。

更新而不覆寫。

安裝到新目錄,檢查新的說明和參考資料,然後按您的執行環境的技能管理流程取代舊套件。安裝程式會拒絕已存在的目標目錄。

讓本機設定與套件保持分離。資訊清單記錄了版本和總和檢查碼,便於您檢查所安裝的內容。

檢視目前資訊清單
技能沒有出現
確認您的執行環境支援本機技能,載入已安裝的資料夾,並保持其指令碼、參考資料和 AI 助理中繼資料在一起。
安裝失敗
檢查 Node.js 24、網路存取以及可寫入的新目標目錄。如果總和檢查碼驗證失敗,請停止並重新取得安裝程式和資訊清單,而不是略過驗證。
輔助程式回報 missing_api_key
讓執行輔助程式的程序能夠讀取 GMSCRAPER_API_KEY。安裝套件並不會設定您的 API 憑證。
請求被拒絕或逾時
閱讀錯誤並在權限範圍、權益、配額或功能失敗時停止。對可重試的逾時,保留原始請求 ID 和輸入;開始新嘗試前遵循終止性錯誤指引。

常見問題

技能和 MCP 伺服器有什麼差異?

MCP 將您的用戶端連接到遠端工具。技能提供可重複使用說明、操作參考、結果 schema 和 REST 備用輔助程式。當設定的 MCP 連線可用時請優先使用;技能本身不會建立連線,也不包含金鑰。

安裝需要什麼?

需要 Node.js 24、用於下載套件的網路存取,以及支援從本機目錄載入技能的 AI 助理執行環境。下載和安裝不需要 API 金鑰。執行資料請求需要您的 API 工作區憑證和相應存取權限。

只下載 SKILL.md 就夠了嗎?

請保留完整套件。SKILL.md 連結到操作參考和 REST 輔助程式,相容的執行環境還可能使用內建的 AI 助理中繼資料。安裝程式會取得完整檔案清單並對照資訊清單驗證。

技能能取得評論和照片嗎?

可以。使用所選商家的 place.dataId 作為 fid。請求一頁最多 10 則公開評論或 20 筆相簿記錄。評論支援相關性、最新、最高評分和最低評分排序。每個成功的正式頁消耗一個 API 請求單位。

技能包含 API 訂閱或額外額度嗎?

套件中包含的是說明和輔助檔案。資料請求使用您的 API 工作區金鑰、權限範圍和權益。REST 與 MCP 共用您的 API 額度,而線上擷取工具和瀏覽器擴充功能有獨立額度。測試憑證傳回模擬資料,消耗 0 個請求單位。

如何更新現有安裝?

安裝到一個全新目錄,檢查新套件,然後按您的執行環境的技能管理流程取代舊版本。安裝程式不會覆寫現有目錄。

踏出下一步

連接技能背後的工具。

設定遠端 MCP 伺服器,將您的 API 憑證儲存在用戶端的私密設定中,並執行一個聚焦的工作流程。