Google Maps 数据 / Agent Skill

为您的智能体提供可复用的数据工作流。

一个可移植的技能,用于查找商户、阅读公开评价和查看地点相册。将说明、参考资料和 REST 辅助工具一起安装。

Node.js 24本地技能目录已配置的 MCP 或 REST安装无需密钥

01 / 安装完整包

一次小型安装,为每个请求提供有用的上下文。

使用 Node.js 24 和能从本地目录加载技能的智能体运行时。选择您的运行时支持的技能位置。

  1. 01

    下载并检查

    将安装器保存到本地。运行命令前,请先阅读安装器、技能说明和清单文件。

  2. 02

    选择一个新目录

    将示例路径替换为您的运行时的技能目录。安装器会获取完整包并校验 SHA-256 校验和;它不会覆盖已有安装。

  3. 03

    启用技能并连接

    在您的智能体运行时中加载已安装的文件夹。优先使用您已配置的 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 个正式请求单位。

询问您的智能体
使用 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
面向兼容运行时的智能体元数据。

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 / 保持可用

一次完整安装,一次有意识的更新。

使用清单文件和返回的错误来检查包和您的连接。

更新而不覆盖。

安装到新目录,检查新的说明和参考资料,然后按您的运行时的技能管理流程替换旧包。安装器会拒绝已存在的目标目录。

让本地配置与包保持分离。清单记录了版本和校验和,便于您检查所安装的内容。

查看当前清单
技能没有出现
确认您的运行时支持本地技能,加载已安装的文件夹,并保持其脚本、参考资料和智能体元数据在一起。
安装失败
检查 Node.js 24、网络访问以及可写的新目标目录。如果校验和验证失败,请停止并重新获取安装器和清单,而不是绕过验证。
辅助工具报告 missing_api_key
让运行辅助工具的进程能够读取 GMSCRAPER_API_KEY。安装包并不会配置您的 API 凭据。
请求被拒绝或超时
阅读错误并在权限范围、权益、配额或能力失败时停止。对可重试的超时,保留原始请求 ID 和输入;开始新尝试前遵循终止性错误指引。

常见问题

技能和 MCP 服务器有什么区别?

MCP 将您的客户端连接到远程工具。技能提供可复用的说明、操作参考、结果 schema 和 REST 备用辅助工具。当配置的 MCP 连接可用时请优先使用;技能本身不会创建连接,也不包含密钥。

安装需要什么?

需要 Node.js 24、用于下载包的网络访问,以及支持从本地目录加载技能的智能体运行时。下载和安装不需要 API 密钥。运行数据请求需要您的 API 工作区凭据和相应访问权限。

只下载 SKILL.md 就够了吗?

请保留完整包。SKILL.md 链接到操作参考和 REST 辅助工具,兼容的运行时还可能使用内置的智能体元数据。安装器会获取完整文件列表并对照清单验证。

技能能获取评价和照片吗?

可以。使用所选商户的 place.dataId 作为 fid。请求一页最多 10 条公开评价或 20 条相册记录。评价支持相关性、最新、最高评分和最低评分排序。每个成功的正式页消耗一个 API 请求单位。

技能包含 API 订阅或额外额度吗?

包中包含的是说明和辅助文件。数据请求使用您的 API 工作区密钥、权限范围和权益。REST 与 MCP 共享您的 API 额度,而在线抓取工具和浏览器扩展有独立额度。测试凭据返回模拟数据,消耗 0 个请求单位。

如何更新已有安装?

安装到一个全新目录,检查新包,然后按您的运行时的技能管理流程替换旧版本。安装器不会覆盖已有目录。

迈出下一步

连接技能背后的工具。

设置远程 MCP 服务器,将您的 API 凭据保存在客户端的私密设置中,并运行一个聚焦的工作流。