开放平台 API 文档

X-API-Key: sk-714ff81f3b63b329bbd23651b36d511e857c4034

curl -X POST https://www.geocha.cn/v1/ask/check \
  -H "X-API-Key: sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"重庆小面培训哪家好","name":"doubao-web"}'

{
  "code": 200,
  "msg": "成功",
  "data": { "reqId": "ask_20261005_123456" }
}

curl "https://www.geocha.cn/v1/ask/result?reqId=ask_20261005_123456" \
  -H "X-API-Key: sk-xxxx"

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": "SUCCESS",
    "prompt": "重庆小面培训哪家好",
    "result": [
      {
        "context": "重庆小面培训推荐……（正文）",
        "quote": [
          { "url": "https://example.com/a", "title": "推荐A", "snippet": "" }
        ],
        "think": "",
        "search_word": ["重庆小面", "培训"],
        "suggestions": [],
        "rich_media_block": []
      }
    ]
  }
}

curl "https://www.geocha.cn/v1/account/quota" -H "X-API-Key: sk-xxxx"

{ "code": 200, "msg": "success", "data": { "used": 12, "total": 100, "window": "total" } }

# ① 提交监测（1 关键词 × 1 平台 × 1 采样 = 1 项）
curl -X POST https://www.geocha.cn/v1/monitor/submit \
  -H "X-API-Key: sk-xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"brand_name":"米途GEO","keywords":["重庆GEO哪家好"],"platforms":["doubao"],"mode":"cloud_phone","n":1,"judge":true}'
#    ↑ 末尾 "judge":true 即生成 P1 三字段（mention_rank / sentiment / competitors）
#      省略则不生成（P0 兼容，三字段为 null / []）—— 见「P1 三字段」章节

# ② 轮询（拿到 req_id 后；建议 3-5s 起指数退避）
curl https://www.geocha.cn/v1/monitor/geo_req_20261011_123456 -H "X-API-Key: sk-xxxxxxxx"

curl -X POST https://www.geocha.cn/v1/monitor/submit \
  -H "X-API-Key: sk-xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"brand_name":"米途GEO","keywords":["重庆GEO哪家好"],"platforms":["doubao"],"mode":"cloud_phone","n":1}'

{
  "req_id": "geo_req_20261011_123456",
  "status": "queued",
  "accepted_items": 1,
  "estimated_points": 1,
  "estimated_duration_sec": 90,
  "created_at": "2026-10-11T20:30:00+08:00"
}

// 400 参数错误（例：缺 keywords）
{ "code": "INVALID_PARAMS", "message": "keywords 非空数组必填" }

// 501 不支持的 mode（例：real_device）
{ "code": "NOT_IMPLEMENTED",
  "message": "mode=real_device（物理真机）我方无真机资源、P0 不交付；请改用 cloud_phone（MuMu 本地模拟器，同属 App 端，结果等价）" }

// 402 额度不足
{ "code": "QUOTA_EXCEEDED", "message": "额度不足：本次需 4 项，剩余 2 项" }

// 429 并发超限（该 Key 活跃 ≤5）
{ "code": "RATE_LIMITED", "message": "请求频繁：该 Key 并发任务过多（≥5），请退避后重试" }

curl https://www.geocha.cn/v1/monitor/geo_req_20261011_123456 -H "X-API-Key: sk-xxxxxxxx"

// 未完成
{ "req_id": "geo_req_20261011_123456", "status": "running",
  "created_at": "2026-10-11T20:30:00+08:00", "finished_at": null,
  "progress": { "done": 0, "total": 1 }, "results": [], "meta": {} }

// 完成
{
  "req_id": "geo_req_20261011_123456",
  "status": "done",
  "created_at": "2026-10-11T20:30:00+08:00",
  "finished_at": "2026-10-11T20:31:35+08:00",
  "progress": { "done": 1, "total": 1 },
  "results": [ /* 见「返回字段」章节的结果字段全表 */ ],
  "summary": { "total_items": 1, "succeeded": 1, "failed": 0, "total_cost_cny": 0.15 },
  "meta": {}
}

// 404 从未存在（或 kind 不符）
{ "code": "NOT_FOUND", "message": "req_id 不存在：geo_req_20261011_999999" }

// 410 曾存在但已超保留期（≥7 天，实际 8 天）
{ "code": "EXPIRED", "message": "req_id 已过期（结果保留 ≥7 天）：geo_req_20261001_000001" }

// 批级回收 / 全失败时 status=failed，带机器可读 error
{ "req_id": "geo_req_20261011_123456", "status": "failed",
  "created_at": "…", "finished_at": "…",
  "progress": { "done": 0, "total": 2 }, "results": [],
  "summary": { "total_items": 2, "succeeded": 0, "failed": 0, "total_cost_cny": 0 },
  "error": "BATCH_TIMEOUT",
  "error_detail": "批级超时（30 分钟无进展）：已完成 0/2 …" }

curl -X POST https://www.geocha.cn/v1/search/submit \
  -H "X-API-Key: sk-xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"query":"重庆GEO优化公司怎么选","top_k":5}'

{ "req_id": "geo_search_20261011_654321", "status": "queued",
  "accepted_items": 1, "estimated_points": 1,
  "estimated_duration_sec": 50, "created_at": "2026-10-11T20:32:00+08:00" }

// 400：带 -app 码
{ "code": "INVALID_PARAMS", "message": "/v1/search 仅支持 Web 端（references 依赖网页引用）；请改用 doubao-web 等" }

// 未完成
{ "req_id": "geo_search_…", "status": "running", "created_at": "…",
  "progress": { "done": 0, "total": 3 }, "results": null }

// 完成
{
  "req_id": "geo_search_20261011_654321",
  "status": "done",
  "created_at": "2026-10-11T20:32:00+08:00",
  "finished_at": "2026-10-11T20:33:10+08:00",
  "results": {
    "answer_text": "……联网检索摘要……",
    "references": [
      { "url": "https://…", "title": "…", "site_name": "…", "publish_time": "2026-01-15" }
    ],
    "platform": "doubao",
    "cost_cny": 0.05,
    "latency_ms": 6400
  }
}

// 失败
{ "req_id": "geo_search_…", "status": "failed", "created_at": "…", "finished_at": "…",
  "error": "CAPTCHA_BLOCKED", "error_detail": "…", "results": null }

"sentiment_axis": { "total": 1, "recommended": 1, "neutral": 0, "negative": 0 }

"competitors": [ { "name": "海星小象", "is_recommended": true, "rank": 2 } ]

{
  "req_id": "geo_req_20261013_362984",
  "status": "done",
  "results": [
    {
      "platform": "doubao",
      "mode": "cloud_phone",
      "status": "ok",
      "answer_text": "…米途GEO（探源者GEO）…",
      "structured": {
        "is_mentioned": true,
        "mention_rank": 1,
        "mention_quality": null,
        "context_type": null,
        "sentiment": "recommended",
        "competitors": [
          { "name": "海星小象", "is_recommended": true, "rank": 2 },
          { "name": "珍岛", "is_recommended": true, "rank": 3 },
          { "name": "派活鹿信息科技", "is_recommended": true, "rank": 4 }
        ],
        "cited_sources": [],
        "citations_status": "not_supported"
      },
      "cost_cny": 0.15
    }
  ],
  "sentiment_axis": { "total": 1, "recommended": 1, "neutral": 0, "negative": 0 }
}

curl "https://www.geocha.cn/v1/quota" -H "X-API-Key: sk-xxxxxxxx"

// 外部账号
{ "used": 3, "total": 500, "window": "total", "limits": { "max_inflight": 5 } }

// 内部账号（无余额概念，用量走「内部台账」）
{ "account_type": "internal", "account": "tanyuanzhe",
  "used": 0, "total": null, "window": "none", "limits": { "max_inflight": 5 } }

curl "https://www.geocha.cn/v1/internal/bill?month=2026-10" \
  -H "X-API-Key: sk-xxxxxxxx"

{
  "account": "tanyuanzhe",
  "month": "2026-10",
  "submitted_items": 16,
  "calls": 10,
  "succeeded_items": 11,
  "cost_cny": 1.05,
  "markup_cny": 0.11,
  "total_cny": 1.16,
  "failures": [ { "req_id": "geo_req_…", "platform": "wenxin", "error": "…" } ],
  "details": [ { "req_id": "geo_req_…", "kind": "monitor", "submitted_items": 2, "succeeded_items": 2, "cost_cny": 0.3, "status": "settled" } ]
}

{
  "status": "queued",
  "notice": "LOCAL_COLLECTOR_OFFLINE",
  "notice_text": "本批含 1 项「仅本机可执行」的平台任务（doubao）：…本机当前已离线约 2 分钟 → 任务保持排队（不失败、不计费、不代跑）；本机恢复后自动继续，无需重新提交。"
}