GEOly Data API

GEOly Data API 给你的是 GEOly 背后的原始数据：提示词、AI 回答、引用、竞品、趋势、站点审计，以及（套餐包含时的）公开行业情报。GEOly 的每一个数据工具都是一个 HTTP 端点：你把工具参数作为 JSON 发过去，工具结果作为 JSON 返回——中间没有模型、没有 Agent、不需要 MCP 客户端。它是为你自己的脚本、BI 管线和后端服务准备的。

工具目录与 GEOly MCP 完全相同：同样的工具名、参数、指标口径和价格。如果你已经在 AI 客户端里用过 GEOly MCP，这里每个工具的用法一模一样。

与 Agent API、MCP 的关系

三者接受同一种 API 密钥，面对同样的品牌、权限和 credits。Data API 与 GEOly MCP 按调用收同样的价格；Agent API 按运行收费。

快速开始

1. 在 GEOly 进入 设置 → 开发者 → API 密钥，点击 创建密钥，选择品牌，复制密钥（以 geom_ 开头）。
2. 列出这把密钥能调的工具：

curl -sS https://app.geoly.ai/api/v1/tools \
  -H "Authorization: Bearer geom_…"

3. 调一个：

curl -sS https://app.geoly.ai/api/v1/tools/get_prompt_list \
  -H "Authorization: Bearer geom_…" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 20, "platform": "chatgpt"}'

响应是 { "data": …, "meta": … }，data 就是工具结果。没有别的要配置。

鉴权

每个请求都带一个 API 密钥：

Authorization: Bearer geom_…

密钥在 GEOly 的 设置 → 开发者 → API 密钥 中创建（仅组织所有者和管理员可见）。创建时需要选择：

• 品牌。 一把密钥只绑定一个品牌；多个品牌各建一把。
• 权限，按资源（品牌、提示词、引用、竞品、审计、公开行业数据……）逐项设 无 / 读 / 写。GET /api/v1/tools 返回的清单只包含这把密钥有权调用的工具。
• 有效期：永不过期，或 30 / 90 / 365 天。

完整密钥只显示一次，GEOly 只保存哈希；丢了就撤销重建。密钥在被撤销、到期、绑定的品牌被删除、或创建者离开组织时失效。同一把密钥也能用于 GEOly MCP 和 Agent API。

没有绑定品牌的凭证（旧版 token、CLI 登录）不被本接口接受，返回 403 API_KEY_BRAND_REQUIRED。

接口一览

Base URL：https://app.geoly.ai

版本策略与 Agent API 相同：版本号在路径里，每个版本持续可用，破坏性变更只会以新版本号发布。v1 内可能随时新增工具、新增可选参数和新增响应字段——请忽略不认识的字段。

列出工具

GET /api/v1/tools
Authorization: Bearer geom_…

{
  "data": {
    "tools": [
      {
        "name": "get_prompt_list",
        "description": "……返回什么、怎么用……",
        "input_schema": { "type": "object", "properties": { "page_size": { "type": "number" }, "…": {} }, "additionalProperties": false },
        "cost": { "tier": "standard", "base": 3, "unit": "call" },
        "timeout_ms": 45000
      }
    ]
  },
  "meta": { "request_id": "…", "duration_ms": 120 }
}

• input_schema 是 JSON Schema。additionalProperties: false 是真的：不认识的参数会被拒绝，而不是忽略。
• cost 是以 credits 计的价格（见Credits）；null 表示免费。
• timeout_ms 是单次调用的服务端上限；客户端超时请设得比它大。

清单随密钥而定：设为 无 的资源不出现，公开行业工具只在套餐包含时出现（Grow 及以上）。

调用工具

POST /api/v1/tools/get_prompt_list
Authorization: Bearer geom_…
Content-Type: application/json

{ "page_size": 20, "platform": "chatgpt", "time_range": "30d" }

• body 是工具参数组成的 JSON 对象，形状以 input_schema 为准。空 body 表示「不带参数」。
• 数字参数也接受数字字符串（"20"），query string 和表格里的值可以原样传。
• 不需要传 org_id 或 brand_id：密钥已经确定了它们。

成功返回 200：

{
  "data": {
    "_quota": { "cost": 3, "remaining": 2997, "resets_at": "2026-11-01T00:00:00.000Z" },
    "prompts": [ … ],
    "total": 128
  },
  "meta": { "request_id": "req_…", "tool": "get_prompt_list", "duration_ms": 812 }
}

data 是工具的原始结果，和 GEOly MCP 客户端收到的是同一个对象；里面的 _quota 回执告诉你这次花了多少、还剩多少。超大结果会在约 60,000 字符处截断，截断时会说明，并点名可以收窄的参数（page_size、limit、平台、时间范围）。

错误码

错误是带机器可读错误码的 JSON：

{
  "error": { "code": "QUOTA_EXCEEDED", "message": "…", "details": { } },
  "meta": { "request_id": "req_…", "tool": "get_prompt_list" }
}

程序按 error.code 分支，把 error.message 展示给人看。meta.request_id 标识这次调用，排查问题时带上它。

Credits

Data API 消耗组织的 MCP credits——与 GEOly MCP 同一个池、同样的价格和回执。

• 每个工具按调用固定计价（清单里的 cost.base：light 1、standard 3、deep 10 credits）。少数工具按返回数量计价，cost 里会写明。
• 导航类工具免费：get_quota、get_brand_context、get_topic_list、get_current_date 以及其他 cost 为 null 的工具。站点审计、你自己的 GA4 / Cloudflare 流量数据、信源总览工具同样免费。
• 执行前就被拒绝的调用（INVALID_ARGUMENT、TOOL_ERROR）以及返回 503 的调用（超时、过载、熔断、读失败）不扣费。
• POST /api/v1/tools/get_quota 随时返回余额；每个收费结果也都带 _quota。

频率与超时

• 每把密钥有每分钟请求上限（与 GEOly MCP 共用），以及同时在飞的调用数上限。超过任一都返回 429 和 Retry-After。
• 重工具按组织每分钟限频（GUARDED_RATE_LIMITED）。
• 单次调用最长 timeout_ms（按工具 20–45 秒）。HTTP 客户端超时至少设 60 秒。

示例：Python

import os
import requests

API = "https://app.geoly.ai/api/v1/tools"
HEADERS = {"Authorization": f"Bearer {os.environ['GEOLY_API_KEY']}"}

def call(tool: str, **args):
    r = requests.post(f"{API}/{tool}", json=args, headers=HEADERS, timeout=90)
    body = r.json()
    if r.status_code != 200:
        err = body["error"]
        raise RuntimeError(f"{tool}: {err['code']} — {err['message']}")
    return body["data"]

overview = call("get_brand_overview", time_range="30d")
prompts = call("get_prompt_list", page_size=50, platform="chatgpt")
print(overview["_quota"], len(prompts["prompts"]))

示例：用 OpenAPI 生成客户端

curl -sS https://app.geoly.ai/api/v1/openapi.json \
  -H "Authorization: Bearer geom_…" > geoly-openapi.json

npx openapi-typescript geoly-openapi.json -o geoly.d.ts

这份文档按你的工具清单生成，只包含密钥能调的工具。每个 operation 带 x-geoly-cost 和 x-geoly-timeout-ms。

接入建议

1. 每个品牌、每套系统各一把密钥，只给需要的权限；放进密钥管理服务，系统下线时撤销。
2. 从工具清单开始。 把工具接进任务前先读 input_schema 和 cost；说明里写了每个 view 返回什么。
3. 先筛选再翻页。 按平台、topic、时间范围筛选，比把所有数据翻一遍更便宜也更快。
4. 尊重 Retry-After：429 和 503 等够再试；400 不改请求就别重试。503 TOOL_TIMEOUT 多半是查询太宽，先收窄再重试。
5. 读 _quota，在组织 credits 用完之前告警。
6. 忽略不认识的字段，这样 v1 内的兼容加法永远不会弄坏你的解析。

边界与限制

• 范围以密钥为准。 一把密钥只能访问一个组织里的一个品牌，权限就是创建时选的那些。
• 写入工具（创建提示词、topic、竞品，打标签、归档、按需触发监测）只在密钥对该资源有 写 权限时可用。按需触发监测（trigger_prompt）扣监测 credits，与走 MCP 时相同。
• 套餐要求。 需要有效订阅；公开行业工具需要 Grow 及以上。
• 只有同步调用。 每次调用都在 timeout_ms 内返回；没有后台任务和 webhook。
• 指标口径（提及率、引用率、AIGVR、Share of Model）与 GEOly 应用和 GEOly MCP 一致；每个工具的定义见 GEOly MCP 使用指南。

相关文档

• GEOly MCP 使用指南——在 Claude、Cursor、Codex 等 AI 客户端里用同一批工具。
• GEOly Agent API——问一个问题，拿到完整结论而不是原始数据。
• GEOly CLI——geoly call 在终端里跑的就是这些工具。