南瓜 GEO API

1. 认证 (API Key)

登录 dashboard 后进 /dashboard/keys 创建 key,格式 nangua_<24 hex>。所有需要认证的 endpoint 用:

bash
curl -H "Authorization: Bearer nangua_xxx" https://nanguageo.com/api/me

2. 速率限制

超限返回 429 · Retry-After header 给重试秒数

服务健康检查

外部 uptime 监控用 · 30s 内缓存。

bash
curl https://nanguageo.com/api/health

响应示例 (HTTP 200):

json
{
  "status": "ok",
  "service": "nangua-geo",
  "version": "d7c90ca",
  "env": "production",
  "region": "iad1",
  "timestamp": "2026-05-14T17:30:00.000Z",
  "checks": { "db": { "ok": true, "latency_ms": 25 } },
  "took_ms": 25
}

8 LLM + DB 实时状态

详细状态 · 并发 ping 8 LLM API + DB · 60s 缓存。

bash
curl https://nanguageo.com/api/status

响应 (节选):

json
{
  "status": "operational",
  "db": { "ok": true, "latency_ms": 25 },
  "llms": {
    "up": 7, "total": 8, "up_rate": 0.875,
    "platforms": [
      { "platform": "deepseek", "zh": "DeepSeek", "ok": true, "latency_ms": 4123 },
      { "platform": "kimi", "zh": "Kimi", "ok": true, "latency_ms": 5234 },
      ...
    ]
  }
}

30 秒免费体检

3 中文 LLM 真扫(DeepSeek / Kimi / 豆包)· 看你品牌在 AI 答案里的可见度。

bash
curl -X POST https://nanguageo.com/api/check/run \
  -H "Content-Type: application/json" \
  -d '{
    "brand_name": "海底捞",
    "industry": "餐饮 - 火锅",
    "competitors": ["呷哺呷哺", "巴奴"]
  }'

响应 (节选):

json
{
  "runId": "839d8479-427c-459e-a670-569cc5875074",
  "platforms": ["deepseek", "kimi", "doubao"],
  "summary": [
    { "platform": "deepseek", "total": 2, "mentions": 2, "positive": 1 },
    { "platform": "kimi",     "total": 2, "mentions": 1, "positive": 1 },
    { "platform": "doubao",   "total": 2, "mentions": 2, "positive": 2 }
  ],
  "rateLimitRemaining": 4
}

完整 8 LLM 查询

登录后 / API key 用 · 8 LLM 全扫(DeepSeek/Kimi/智谱/通义/豆包/ChatGPT/Gemini/Perplexity)· 真扣费 · 写入 DB。

bash
# 用 API key
curl -X POST https://nanguageo.com/api/query?mode=all \
  -H "Authorization: Bearer nangua_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "海底捞",
    "category": "餐饮 - 火锅",
    "platforms": ["deepseek", "kimi", "zhipu", "qwen", "doubao", "chatgpt", "gemini", "perplexity"]
  }'

Node.js SDK 示例:

javascript
async function queryAi(brand, category) {
  const r = await fetch('https://nanguageo.com/api/query?mode=all', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.NANGUA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ brand, category }),
  });
  return r.json();
}

const result = await queryAi('海底捞', '餐饮 - 火锅');
console.log(result.runs[0].results[0].text);  // DeepSeek's answer
console.log(result.runs[0].results[0].analysis.mentioned);  // true / false
console.log(result.runs[0].results[0].analysis.position);   // char position

AEO 倒金字塔改写

把客户原文重写为「倒金字塔」结构 + JSON-LD,显著提高 AI 引用率。

bash
curl -X POST https://nanguageo.com/api/aeo/rewrite \
  -H "Authorization: Bearer nangua_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "海底捞是中国知名的川式火锅连锁,主打服务体验...",
    "brand": "海底捞",
    "audience": "上海家庭聚餐"
  }'

响应:

json
{
  "headline": "海底捞 · 中国川式火锅连锁",
  "section_1_answer": "海底捞是中国最大的川式火锅连锁品牌,全国 1400+ 门店...",
  "section_2_evidence": ["全国 1400+ 直营门店", "服务力榜单 5 年第一", ...],
  "section_3_context": "川式火锅市场中,海底捞与呷哺呷哺、湊湊、巴奴...",
  "section_4_faq": [
    { "q": "海底捞人均多少钱?", "a": "人均 100-150 元..." },
    ...
  ],
  "score_aviv": 78,
  "source": "deepseek",
  "latency_ms": 8234,
  "cost_usd": 0.00091,
  "jsonld": "{...}"
}

8. /api/dashboard/* 仪表板数据 API

所有 dashboard 数据都有对应 JSON API · 拉去做 BI/导出/自动化。

9. Webhooks

进 /dashboard/webhooks 配 URL · 勾选订阅事件 · 我们 POST 到你的服务器。

5 个事件类型

• wiki.page.created · Wiki 页创建
• wiki.page.updated · Wiki 页更新
• lint.issue.detected · Lint 问题发现
• aeo.batch.completed · AEO 批改写完成
• citation.gap.alert · 引用缺口告警

payload 格式

json
{
  "event": "aeo.batch.completed",
  "brandId": "42cdf804-045f-4b4e-bc99-aa288765aaa0",
  "timestamp": "2026-05-14T17:30:00.000Z",
  "data": { "batchId": "xxx", "successCount": 10, "failureCount": 0 }
}

签名验证

请求头带 X-Nangua-Signature: t=<ts>,v1=<hmac> · 用 secret 做 HMAC-SHA256:

javascript
import crypto from 'node:crypto';

function verifyWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  );
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1)
  );
}

10. 错误码表