___ _ ___ ___ ___ ___ | \ __ _| |_ __ _| __|__ _ _ / __| __/ _ \ | |) / _` | _/ _` | _/ _ \ '_| (_ | _| (_) | |___/\__,_|\__\__,_|_|\___/_| \___|___\___/ api v1 · 草稿
所有接口用一个请求头认证：x-api-key。请求和响应都是 JSON，时间一律用 ISO 8601（UTC）。
| 项 | 说明 |
|---|---|
| Base URL | https://api.dataforgeo.dev |
| 认证 | x-api-key 在控制台创建 API key；Pro 可建 5 个，Scale 和 Enterprise 不限 |
| 免费额度 | 100 credits 注册即送，可跑 100 次标准引擎调用 |
$ curl https://api.dataforgeo.dev/v1/geo/answer \ -H "x-api-key: YOUR_API_KEY" \ -H "content-type: application/json" \ -d '{ "prompt": "东京有哪些适合家庭入住的民宿？", "engines": [ "chatgpt" ], "brand": "晓宅", "location": "JP", "language": "zh-CN" }'
HTTP/1.1: 200 OK x-credits-used: 1 x-credits-remaining: 99 x-cache: miss { "request_id": "req_8f2c1a", "prompt": "东京有哪些适合家庭入住的民宿？", "credits_used": 1, "answers": [ { "engine": "chatgpt", "sample": 1, "status": "ok", "cached": false, "generated_at": "2026-11-02T00:31:12Z", "text": "……", "brand": { "mentioned": true, "mention_count": 2, "first_position": 3, "sentiment": "positive" }, "entities": [ { "name": "晓宅", "type": "brand", "position": 3, "is_competitor": false }, { "name": "Example Stay", "type": "brand", "position": 1, "is_competitor": true } ], "citations": [ { "url": "https://example.com/guide", "domain": "example.com", "position": 1, "is_brand_domain": false } ] } ] }
# answers[].text 渲染后：
只对实际返回的答案扣费；请求开始时按「prompt × 引擎 × 采样数」预占 credits，结束后多退少补。credits 一次性购买、永不过期。
| 调用 | 每条答案扣费 |
|---|---|
| GEO 数据，标准引擎（chatgpt、perplexity、grok、google-aio） | 1 |
| GEO 数据，高成本引擎（gemini、claude） | 2 |
| Index 分析（/v1/geo/index 在答案上计算 KPI） | +1 |
| 缓存命中 | 0 |
| 引擎超时、失败或无答案 | 0 |
| /v1/geo/index/summary、/v1/jobs、/v1/account | 0 |
| 响应头 | 含义 |
|---|---|
| x-credits-used | 本次请求实际扣除的 credits |
| x-credits-remaining | 扣除后的余额 |
| x-cache | hit、miss 或 partial（多条答案中部分命中） |
缓存键为 prompt + 引擎 + 地区 + 语言 + 采样序号，有效期 24 小时，跨账户共享。传 fresh: true 跳过缓存，按正常价格扣费。
# 预占 = prompt × 引擎 × 采样数；结束后按实际答案多退少补 $ dfg estimate --engines chatgpt,perplexity,gemini --samples 2 --index chatgpt 1 × 2 = 2 perplexity 1 × 2 = 2 gemini 2 × 2 = 4 index +1 × 6 = 6 ────────────────────── held 14 credits
engines 参数接受下面 6 个 id，一次请求可传多个；每个引擎单独计费、单独返回。
| 引擎 id | 平台 | 每条答案扣费 | 典型耗时 |
|---|---|---|---|
| chatgpt | ChatGPT | 1 | 待实测 |
| perplexity | Perplexity | 1 | 待实测 |
| grok | Grok | 1 | 待实测 |
| google-aio | Google AI Overview | 1 | 待实测 |
| gemini | Gemini | 2 | 待实测 |
| claude | Claude | 2 | 待实测 |
POST /v1/geo/answer [all plans]
拿一个 prompt 在多个引擎上的 AI 答案，并标出品牌提及、引用来源和竞品实体。所有档位可用。
* = 必填
$ curl https://api.dataforgeo.dev/v1/geo/answer \ -H "x-api-key: YOUR_API_KEY" \ -H "content-type: application/json" \ -d '{ "prompt": "东京有哪些适合家庭入住的民宿？", "engines": [ "chatgpt" ], "brand": "晓宅", "location": "JP", "language": "zh-CN" }'
{ "request_id": "req_8f2c1a", "prompt": "东京有哪些适合家庭入住的民宿？", "credits_used": 1, "answers": [ { "engine": "chatgpt", "sample": 1, "status": "ok", "cached": false, "generated_at": "2026-11-02T00:31:12Z", "text": "……", "brand": { "mentioned": true, "mention_count": 2, "first_position": 3, "sentiment": "positive" }, "entities": [ { "name": "晓宅", "type": "brand", "position": 3, "is_competitor": false }, { "name": "Example Stay", "type": "brand", "position": 1, "is_competitor": true } ], "citations": [ { "url": "https://example.com/guide", "domain": "example.com", "position": 1, "is_brand_domain": false } ] } ] }
POST /v1/geo/index [pro|scale|enterprise]
在 /v1/geo/answer 的结果上计算 GEO Index 的 KPI。Pro、Scale、Enterprise 可用；Starter 调用返回 403 plan_not_allowed。
参数与 /v1/geo/answer 相同，brand 改为必填，另加：
* = 必填
$ curl https://api.dataforgeo.dev/v1/geo/index \ -H "x-api-key: YOUR_API_KEY" \ -H "content-type: application/json" \ -d '{ "prompt": "大阪带孩子住哪里方便？", "engines": [ "chatgpt", "perplexity", "grok" ], "brand": "晓宅", "tag": "osaka-family-q4", "intent": "recommend", "persona": "带孩子的家庭", "location": "JP", "language": "zh-CN" }'
x-credits-used: 6 { "request_id": "req_91d0b3", "brand": "晓宅", "tag": "osaka-family-q4", "credits_used": 6, "answers": [ "…与 /v1/geo/answer 相同…" ], "kpis": { "visibility": { "value": 0.667, "numerator": 2, "denominator": 3, "samples": 3 }, "share_of_voice": { "value": 0.25, "numerator": 2, "denominator": 8, "samples": 3 }, "top_rate": { "value": 0, "numerator": 0, "denominator": 3, "samples": 3 }, "competitor_gap": { "value": -1.33, "samples": 3 }, "positive_ratio": { "value": 1, "numerator": 2, "denominator": 2, "samples": 3 } }, "kpi_tier": "pro" }
GET /v1/geo/index/summary [pro|scale|enterprise]
把账户里已经跑过的 /v1/geo/index 结果按时间窗口汇总成 KPI 和趋势，不产生新的 AI 调用，不扣费。Pro 可看总体与趋势；按维度拆分（group_by）仅 Scale 与 Enterprise。
* = 必填
$ curl "https://api.dataforgeo.dev/v1/geo/index/summary?brand=晓宅&tag=osaka-family-q4&interval=week&group_by=engine" \ -H "x-api-key: YOUR_API_KEY"
x-credits-used: 0 { "brand": "晓宅", "window": { "from": "2026-10-03T00:00:00Z", "to": "2026-11-02T00:00:00Z" }, "answers_counted": 498, "kpis": { "findability": { "value": 42.1 }, "visibility": { "value": 0.262, "numerator": 130, "denominator": 498 } }, "series": [ { "period": "2026-10-05", "visibility": 0.255, "share_of_voice": 0.018 }, { "period": "2026-10-12", "visibility": 0.263, "share_of_voice": 0.026 } ], "groups": [ { "key": "chatgpt", "answers_counted": 166, "kpis": { "visibility": { "value": 0.301 } } }, { "key": "gemini", "answers_counted": 166, "kpis": { "visibility": { "value": 0.241 } } } ] }
多引擎、多采样的请求可能要等一两分钟，建议传 async: true：接口立即返回 job_id，结果用轮询或 webhook 取回。同步请求超过 120 秒会自动转为异步，并返回 202。
| 接口 | 说明 | credits |
|---|---|---|
| GET /v1/jobs/{job_id} | 查询任务状态和结果 | 0 |
| GET /v1/account | 查询余额、档位、本月用量 | 0 |
$ curl ... -d '{"async": true, ...}' { "job_id": "job_3b7e90", "status": "queued", "credits_held": 9 } $ watch -n 5 curl https://api.dataforgeo.dev/v1/jobs/job_3b7e90 queued → running → completed
{ "plan": "scale", "credits_remaining": 10422, "credits_used_this_month": 1578 }
Pro 返回 11 个核心 KPI，Scale 与 Enterprise 另加 8 个高阶 KPI。这里只给公开定义，不公开计算方法。
| 字段 | 名称 | 定义 | 单位 | 档位 | 返回位置 |
|---|---|---|---|---|---|
| findability | 综合可发现度 | 品牌在 AI 答案中被发现、被推荐程度的综合分 | 分 | pro | 单次与汇总 |
| visibility | 可见度 | 出现品牌的答案占比 | 比例 | pro | 单次与汇总 |
| own_mentions | 自有提及数 | 平均每条答案提到品牌的次数 | 次 | pro | 单次与汇总 |
| citations | 引用数 | 平均每条答案引用的来源数 | 次 | pro | 单次与汇总 |
| citation_rate | 引用率 | 引用了品牌自有来源的答案占比 | 比例 | pro | 单次与汇总 |
| 声量份额 | 品牌提及占品牌加竞品提及的比例 | 比例 | pro | 单次与汇总 | |
| competitor_mentions | 竞品提及数 | 平均每条答案提到竞品的次数 | 次 | pro | 单次与汇总 |
| competitor_gap | 竞品差距 | 自有提及数减竞品提及数 | 次 | pro | 单次与汇总 |
| top_rate | 首推率 | 品牌排在推荐第一位的答案占比 | 比例 | pro | 单次与汇总 |
| positive_ratio | 正面比例 | 品牌提及中正面评价的占比 | 比例 | pro | 单次与汇总 |
| tone | 语气得分 | 提及品牌时的整体语气，-1 到 1 | 分 | pro | 单次与汇总 |
| 加权份额 | 按提及位置加权后的声量份额 | 比例 | scale | 仅汇总 | |
| rank_gap | 排名差距 | 与每个竞品的推荐位次差，按竞品分别返回 | 位 | scale | 单次与汇总 |
| recommendation_position | 推荐位次指数 | 品牌在推荐列表中位置的得分 | 分 | scale | 单次与汇总 |
| purchase_intent_rate | 购买意向推荐率 | 购买意向类问题中品牌被推荐的比例 | 比例 | scale | 单次与汇总 |
| conclusion_bias | 结论推荐倾向 | 答案结论是推荐还是劝退品牌，-1 到 1 | 分 | scale | 单次与汇总 |
| category_capture_gap | 品类捕获差 | 品牌在所属品类问题中的捕获差距 | 分 | scale | 仅汇总 |
| knowledge_half_life | AI 知识半衰期 | AI 对品牌认知的衰减周期 | 周 | scale | 仅汇总 |
| features | 特征提及 | 答案中提到的品牌卖点列表 | 列表 | scale | 单次与汇总 |
出错时返回统一结构，且不扣费。单个引擎失败不会让整个请求报错：该条答案的 status 为 timeout 或 failed，不扣费，其余引擎照常返回。
| HTTP | code | 含义 |
|---|---|---|
| 400 | invalid_request | 参数缺失或格式错误，message 指出具体字段 |
| 400 | unsupported_engine | engines 里有不认识的引擎 id |
| 401 | invalid_api_key | API key 缺失、错误或已停用 |
| 402 | insufficient_credits | 余额不够预占本次请求 |
| 403 | plan_not_allowed | 当前档位不能用该接口或参数，例如 Starter 调用 index、Pro 使用 group_by |
| 404 | not_found | job_id 不存在或已过期 |
| 500 | internal_error | 服务端错误，可用 request_id 联系支持 |
{ "error": { "code": "insufficient_credits", "message": "本次请求需预占 9 credits，余额 4", "request_id": "req_7a11c2" } }
EOF