REST API 参考

Geovory 的 REST API 提供只读的程序化访问，返回的数据与仪表盘完全一致：评级、提及率、Prompt、AI 原始回答、被引用来源与引用缺口。

基础地址：https://geovory.com/api/v1

认证

每个请求都需要在 Authorization 请求头中携带 API 密钥：

``
Authorization: Bearer rk_你的API密钥
``

在 仪表盘 → 设置 → API 密钥 创建密钥。密钥绑定所在工作区，仅在创建时完整显示一次，服务器端只保存 SHA-256 哈希。不再使用的密钥请及时吊销——吊销立即生效。

端点

所有端点均为 GET，成功时返回带 ok: true 的 JSON。

| 端点 | 返回内容 |
| --- | --- |
| /api/v1/visibility | 可见度摘要：最新评级、提及率、引用漏斗、已采样平台、跟踪的竞品、与上周对比。 |
| /api/v1/history | 完整扫描历史：每次扫描的日期、评级、提及率与检测到的变化。 |
| /api/v1/prompts | 跟踪中的 Prompt（买家问题），含标签、意图、国家与启用状态。 |
| /api/v1/answers | 最近一次扫描的 AI 原始回答，含模型与是否提及标记。 |
| /api/v1/sources | 最近一次扫描中 AI 回答引用的域名，含次数与分类。 |
| /api/v1/urls | 最近一次扫描的 URL 级引用统计。 |
| /api/v1/gaps | 引用缺口：引用了竞品而没有你的品牌的 URL。 |

未携带密钥的 GET /api/v1 会以 JSON 返回这份端点索引。

示例

``bash
curl -s https://geovory.com/api/v1/visibility \
-H "Authorization: Bearer rk_你的API密钥"
``

返回：

``json
{
"ok": true,
"business": "Acme Dental",
"platforms": ["grok", "grok-mini", "grok-grounded"],
"latest": { "date": "2026-08-03", "grade": "B", "mention_rate": 41, "scan_id": "…" },
"previous": { "date": "2026-07-27", "grade": "C", "mention_rate": 33, "scan_id": "…" },
"scans_total": 12
}
``

速率限制

每个密钥每分钟最多 60 次请求。超出后返回 429，并带 Retry-After: 60 响应头。

错误码

| 状态码 | error | 含义 |
| --- | --- | --- |
| 401 | unauthorized | 缺少、格式错误或已吊销的 API 密钥。 |
| 404 | not_found | 未知的端点路径。 |
| 404 | project_not_found | 该密钥所在工作区尚无项目数据。 |
| 405 | method_not_allowed | /api/v1/* 仅支持 GET。 |
| 429 | rate_limited | 超出单密钥速率限制——60 秒后重试。 |

范围与诚实口径

API 按设计为只读——没有任何端点可以发起扫描、修改 Prompt 或更改设置。数据与你的仪表盘完全一致，包括其覆盖范围的诚实边界。

想在 Claude、Cursor 或其他 MCP 客户端里直接使用这些数据？请看 MCP 服务器指南。