快速开始

最近更新 · 2026/06/24

独角兽GEO - OpenAPI

面向接入方的对外接口文档。当前版本聚焦四大数据的只读查询能力：品牌数据、口碑洞察、引用来源、竞品分析,并补充采集录屏(可回放) 查询。所有接口均为 GET,不提供任何写操作。

1. 基本信息

项目	说明
Base URL	`https://geo.yueyuezi.com/open-api/v1`
协议	HTTPS
鉴权	API Key(在「左下角个人中心 → API Key 管理」生成)
限流	单密钥 1 QPS,超出返回 `429 rate_limited`,响应头带 `Retry-After`
数据更新频率	天级(每日定时采集)
字符编码	UTF-8
时间格式	ISO 8601 (RFC3339);日期参数统一 `YYYY-MM-DD`

该 API Key 等价于持有人本人的账号权限,可读品牌、话题等于该账号名下完全一致的范围,请勿外泄。删除密钥后立即失效。

2. 鉴权

请求头任选一种方式传入密钥:

X-API-Key: <your-api-key>

或

Authorization: Bearer <your-api-key>

密钥本体是 32 位十六进制字符串(在「左下角个人中心 → API Key 管理」生成)。

未携带或密钥无效,返回:

{ "error": { "code": "missing_api_key", "message": "缺少 API Key..." } }
{ "error": { "code": "invalid_api_key", "message": "API Key 无效或已被删除" } }

2.1 切换工作区(可选)

如果你在多个工作区中(自己持有 + 受邀加入),默认按"自己的工作区" 访问。要查看受邀工作区下的品牌数据,请额外传:

X-Active-Workspace: <workspace_owner_public_id>

workspace_owner_public_id 是被邀请工作区所有者的 8 位数字 ID(即「个人中心」页面显示的 ID,如 12345678)。也兼容传入 UUID 格式。校验失败返回 403 workspace_forbidden。

3. 通用响应格式

成功:

{
  "data": <object | array>
}

失败:

{
  "error": {
    "code": "<machine_readable_code>",
    "message": "<human_readable_zh>"
  }
}

常见错误码:

HTTP	code	说明
401	missing_api_key	请求未带密钥
401	invalid_api_key	密钥无效或已被删除
403	workspace_forbidden	当前密钥无权访问 X-Active-Workspace 指定的工作区
403	brand_forbidden	品牌不属于当前工作区
404	brand_not_found	品牌不存在或已被软删
429	rate_limited	触发限流,见 `Retry-After` 头
500	internal_error	服务端异常

4. 通用查询参数

涉及时间维度的接口共享以下查询参数(具体接口的支持情况见各章节; 采集录屏按「日」查询,不使用本组参数,见 5.16):

参数	类型	默认	说明
`days`	int	7	最近 N 天(含今天);超出当前套餐上限一律 clamp 到上限
`from`	string	—	起始日期 `YYYY-MM-DD`(UTC,包含当日)
`to`	string	—	截止日期 `YYYY-MM-DD`(UTC,包含当日);`from`–`to` 跨度同样受套餐上限约束,超出会自动收紧为 `[to-(上限-1)d, to]`
`platform`	string	—	平台过滤,逗号分隔,如 `deepseek,doubao`(未传则按工作区套餐覆盖的全部平台)

查询窗口按套餐分级:免费版 7 天、基础版 180 天、专业版不限。平台数据天级更新,窗口越长 SQL 聚合开销越高,因此按套餐分级而非无限回溯。 days 与 from/to 二选一:同时传时以 from/to 为准;两者均缺省时按最近 7 天。

支持的 platform 取值:deepseek、doubao、wenxin、kimi、qianwen、yuanbao。

5. 接口列表

接口按四大数据 + 采集录屏分组。所有 :id 均为品牌 ID(UUID)。

品牌数据

5.1 品牌列表

GET /brands

返回当前工作区下的所有品牌(包含已冻结的,以 is_active=false 区分)。

示例响应

{
  "data": [
    {
      "id": "f6c5f69c-1234-4abc-9d77-2b1c0c5fdc8a",
      "name": "示例品牌",
      "website": "https://example.com",
      "description": "做云端数据库的公司",
      "is_active": true,
      "created_at": "2025-09-01T03:21:11Z",
      "updated_at": "2025-12-08T07:02:43Z"
    }
  ]
}

字段说明:

字段	类型	说明
id	string (UUID)	品牌 ID,用于其它接口的 `:id`
name	string	品牌展示名
website	string?	品牌官网,可空(空则字段缺省)
description	string?	品牌描述,可空(空则字段缺省)
is_active	bool	`false` 表示已冻结,数据停更
created_at / updated_at	string	RFC3339 时间戳

5.2 品牌详情

GET /brands/{brand_id}

返回单个品牌的基础信息(字段集合与 5.1 中的元素一致)。

5.3 话题列表

GET /brands/{brand_id}/topics

示例响应

{
  "data": [
    {
      "id": "9f4c...e1",
      "keyword": "云端数据库 推荐",
      "topic_type": "industry",
      "is_active": true,
      "created_at": "2025-09-01T03:25:00Z"
    }
  ]
}

字段	说明
keyword	用户在 AI 平台模拟搜索的话题词
topic_type	`brand`(品牌词) / `industry`(行业词)
is_active	`false` 时该话题暂停采集

5.4 排名概览(按话题)

GET /brands/{brand_id}/overview?days=30

返回过去 N 天该品牌每个话题的滚动统计。与平台前端「品牌数据」页分话题表的口径对齐。

示例响应

{
  "data": {
    "brand_id": "f6c5f69c-...",
    "topics": [
      {
        "topic_id": "9f4c...e1",
        "keyword": "云端数据库 推荐",
        "topic_type": "industry",
        "snapshot_count": 36,
        "platforms_covered": 6,
        "last_snapshot_date": "2025-12-08T03:48:50+08:00",
        "mention_rate_pct": 78.5,
        "first_place_rate_pct": 12.7,
        "avg_rank_score": 64.3
      }
    ]
  }
}

字段	说明
snapshot_count	窗口内该话题的快照数
platforms_covered	窗口内出现过的 AI 平台数
mention_rate_pct	我方品牌出现率(0–100)
first_place_rate_pct	排在首位的快照占比(0–100)
avg_rank_score	加权排名分(0–100,越大越好;0 表示无样本)
last_snapshot_date	窗口内最后一次采集时间(RFC3339,Shanghai 时区;窗口内无快照则为 null)

5.5 品牌整体趋势

GET /brands/{brand_id}/trend?days=30

按 (日期 × 平台) 聚合的时间序列,适合画趋势图。

示例响应

{
  "data": [
    {
      "date": "2025-12-07",
      "platform": "deepseek",
      "mention_rate_pct": 75.0,
      "first_place_rate_pct": 12.5,
      "top3_rate_pct": 25.0,
      "avg_rank_score": 62.1,
      "snapshot_count": 8,
      "top3_count": 2
    }
  ]
}

字段	说明
mention_rate_pct	当日该平台我方品牌提及率(0–100)
first_place_rate_pct	当日排首位占比(0–100)
top3_rate_pct	当日进入前 3 占比(0–100)
avg_rank_score	当日加权排名分(无样本时字段缺省)
snapshot_count	当日该平台快照数
top3_count	当日进入前 3 的快照数

5.6 每日排名位置

GET /brands/{brand_id}/rank-positions?days=30

按 (话题 × 平台 × 日期) 给出当日具体排名,粒度比 5.5 更细。

示例响应

{
  "data": [
    {
      "topic_id": "9f4c...e1",
      "keyword": "云端数据库 推荐",
      "topic_type": "industry",
      "date": "2025-12-07",
      "platform": "deepseek",
      "brand_rank": 2,
      "brand_mentioned": true,
      "rank_score": 75.0,
      "total_entities": 10
    }
  ]
}

字段	说明
brand_rank	当日实际位次;仅在被提及时返回,未提及时字段缺省
brand_mentioned	是否提到我方品牌
rank_score	当日该 (话题, 平台) 的加权得分(无样本时字段缺省)
total_entities	当日该 (话题, 平台) 回答里出现的实体总数(分母)

口碑洞察

5.7 口碑概览

GET /brands/{brand_id}/sentiment-overview?days=30

口碑洞察的总览。返回窗口内 AI 回答提及该品牌时的正/中/负分布、口碑健康分、环比、趋势曲线、分平台/分话题分布、(话题×平台)热力图、负面 Top 与近期评价节选、印象词云。与平台前端「口碑洞察」页概览同源。

示例响应

{
  "data": {
    "filter": { "from": "", "to": "", "days": 30 },
    "total": { "positive": 42, "neutral": 18, "negative": 6, "total": 66 },
    "positive_ratio": 63.64,
    "neutral_ratio": 27.27,
    "negative_ratio": 9.09,
    "health_score": 76.52,
    "health_label": "口碑良好",
    "prev_compare": {
      "prev_total": 58,
      "prev_health_score": 71.03,
      "health_score_delta": 5.49,
      "positive_ratio_delta": 4.12,
      "negative_ratio_delta": -2.07,
      "negative_count_delta": -3,
      "total_delta": 8,
      "period_from": "2025-11-05",
      "period_to": "2025-11-19"
    },
    "trend": [
      { "date": "2025-12-07", "positive": 3, "neutral": 1, "negative": 0, "total": 4, "health_score": 87.5 }
    ],
    "by_platform": [
      { "platform": "deepseek", "avg_score": 0.62, "positive": 20, "neutral": 8, "negative": 3, "total": 31 }
    ],
    "by_topic": [
      { "topic_id": "9f4c...e1", "keyword": "示例品牌 口碑怎么样", "avg_score": 0.71, "positive": 12, "neutral": 5, "negative": 2, "total": 19 }
    ],
    "heatmap": {
      "topics": [ { "topic_id": "9f4c...e1", "keyword": "示例品牌 口碑怎么样" } ],
      "platforms": [ "deepseek", "doubao" ],
      "cells": [
        { "topic_id": "9f4c...e1", "platform": "deepseek", "positive": 6, "neutral": 3, "negative": 1, "total": 10, "avg_score": 0.65, "health_score": 82.5 }
      ]
    },
    "negative_top": [
      { "entity_name": "示例品牌", "platform": "deepseek", "topic_id": "9f4c...e1", "topic_keyword": "示例品牌 口碑怎么样", "sentiment": "negative", "context_snippet": "……回答中提到该品牌在售后响应上较慢……", "snapshot_date": "2025-12-07" }
    ],
    "recent_mentions": [
      { "entity_name": "示例品牌", "platform": "doubao", "topic_id": "9f4c...e1", "topic_keyword": "示例品牌 怎么样", "sentiment": "positive", "context_snippet": "……综合体验反馈不错……", "snapshot_date": "2025-12-08" }
    ],
    "keyword_cloud": [
      { "word": "性价比", "weight": 18, "sentiment": "positive" },
      { "word": "客服慢", "weight": 7, "sentiment": "negative" }
    ]
  }
}

字段	说明
filter	回显本次查询条件;`days` 模式下 `from`/`to` 为空串、回 `days`,`from`/`to` 模式下回 `from`+`to`(`days` 缺省);`platforms` 仅在传了 `platform` 时出现
total	窗口内正/中/负及总提及数
positive_ratio / neutral_ratio / negative_ratio	三类占比(0–100)
health_score	口碑健康分:`(positive×100 + neutral×50) / total`,无样本时为 50
health_label	`口碑健康`(≥80) / `口碑良好`(≥60) / `口碑一般`(≥40) / `需要关注`(<40)
prev_compare	与上一段等长窗口的环比;仅当窗口可锚定(传了 `days` 或 `from`/`to`)时返回,全量无窗口时为 null
trend	按日(或按周分桶)的正/中/负序列,每点带当日 health_score
by_platform / by_topic	分平台 / 分话题的正/中/负与平均分
heatmap	(话题 × 平台)矩阵;`topics` 为行、`platforms` 为列、`cells` 为单元格
negative_top	负面评价节选(最多 8 条)
recent_mentions	近期评价节选(最多 30 条)
keyword_cloud	印象词云;`weight` 为词频权重,`sentiment` 为该词的总体情感倾向

口碑健康分把中性按 50 分折算,因此「正多中多负少」的品牌会拿到高分, 负面集中时迅速下滑。prev_compare 的 period_from/period_to 是上一段窗口的实际起止日期,便于接入方自己画环比箭头。

5.8 评价节选

GET /brands/{brand_id}/sentiment-mentions?sentiment=negative&q=售后&page=1&page_size=20

口碑洞察的评价明细。分页返回 AI 回答里提到该品牌的片段(带情感标签与上下文)。在通用 days/from/to/platform 之上另支持:

参数	类型	默认	说明
`topic_id`	string	—	按话题过滤(UUID)
`sentiment`	string	—	`positive` / `neutral` / `negative`
`q`	string	—	对 `context_snippet` 做大小写不敏感子串模糊
`page`	int	1	页码,从 1 起
`page_size`	int	20	每页条数,上限 100

示例响应

{
  "data": {
    "items": [
      {
        "entity_name": "示例品牌",
        "platform": "deepseek",
        "topic_id": "9f4c...e1",
        "topic_keyword": "示例品牌 口碑怎么样",
        "sentiment": "negative",
        "context_snippet": "……回答中提到该品牌在售后响应上较慢……",
        "snapshot_date": "2025-12-07"
      }
    ],
    "total": 6,
    "page": 1,
    "size": 20
  }
}

字段	说明
entity_name	该评价节选里被识别出的实体名(通常即品牌本身)
context_snippet	AI 回答中提及该品牌的上下文片段
snapshot_date	该回答的采集日期(`YYYY-MM-DD`)
total / page / size	总条数 / 当前页 / 当前页条数(分页元信息)

引用来源

5.9 引用来源列表

GET /brands/{brand_id}/citations?days=30

返回 AI 回答里引用到的外部页面统计(支持 from/to/platform)。

示例响应

{
  "data": [
    {
      "source_name": "知乎",
      "source_url": "https://zhuanlan.zhihu.com/p/xxxxx",
      "source_domain": "zhuanlan.zhihu.com",
      "cite_count": 5,
      "keyword": "云端数据库 推荐",
      "platform": "deepseek",
      "is_my_source": false,
      "source_origin": "",
      "source_title": "2025 云端数据库深度横评",
      "source_article_title": "2025 云端数据库深度横评",
      "source_sitename": "知乎",
      "source_match_key": "2025 云端数据库深度横评"
    }
  ]
}

字段	说明
source_name	后台维护的中文展示名(如 `mp.weixin.qq.com → 微信公众号`),没维护时回落为域名
source_url / source_domain	引用页 URL 与域名
cite_count	该来源在窗口内被引用次数
keyword / platform	该引用所属话题词与采集平台
is_my_source	是否命中当前品牌的「我的信源」(URL 精确匹配优先)
source_origin	命中信源的来源类型:`""`(非我的信源) / `manual` / `press_auto`
source_title	网页原始标题
source_article_title	提取后的文章标题(展示用)
source_sitename	原生平台名
source_match_key	规范化匹配键(取消标记时的兜底定位键)

5.10 引用来源汇总

GET /brands/{brand_id}/citations/overview

无时间参数,返回该品牌所有时间累计的引用统计:

{
  "data": {
    "total_count": 1325,
    "source_count": 482,
    "domain_count": 113,
    "topic_count": 14
  }
}

字段	说明
total_count	累计引用总次数
source_count	累计去重来源(URL)数
domain_count	累计去重域名数
topic_count	涉及话题数

5.11 引用来源趋势

GET /brands/{brand_id}/citations/trend?days=30

按 (日期 × 来源展示名) 给出引用计数时间序列,适合画「各引用源随时间的占比」堆叠图(支持 from/to/platform)。

示例响应

{
  "data": [
    { "date": "2025-12-07", "source_name": "知乎", "count": 4 },
    { "date": "2025-12-07", "source_name": "百家号", "count": 2 }
  ]
}

字段	说明
source_name	来源展示名(与 5.9 同口径)
count	该来源当日被引用次数

竞品分析

5.12 发现的竞品

GET /brands/{brand_id}/competitors?days=30

聚合 AI 回答里与我方品牌共同出现过的非自有实体,作为隐式竞品候选。

示例响应

{
  "data": [
    {
      "entity_name": "某竞品 A",
      "mention_count": 28,
      "platform_count": 5,
      "first_seen_date": "2025-09-04",
      "mention_rate_pct": 26.62,
      "avg_rank_score": 14.46,
      "first_position_rate": 4.63,
      "is_our_brand": false,
      "recent_mentions": 9,
      "previous_mentions": 5,
      "previous_window_days": 7,
      "platform_mentions": { "deepseek": 12, "doubao": 8 },
      "daily_trend": [
        {
          "date": "2025-12-07",
          "count": 2,
          "rank_score": 72.0,
          "first_position_rate": 3.7,
          "platform_counts": { "deepseek": 1, "doubao": 1 }
        }
      ]
    }
  ]
}

字段	说明
mention_count	窗口内该竞品被提及总次数
platform_count	窗口内出现的平台数
first_seen_date	首次被采集到的日期
mention_rate_pct	该竞品在全部有效非品牌话题快照中的出现率(0–100)
avg_rank_score	话题口径下的加权排名分(0–100)
first_position_rate	占据首位的快照占比(0–100)
is_our_brand	是否为「我方品牌」(含我方品牌视图时为 true)
recent_mentions / previous_mentions	固定 7 天滚动窗口的提及数(最近 7 天 / 其前的 7 天),用于「上升中」提示;与 `days` 参数无关
previous_window_days	上一段 7 天窗口内实际有采集数据的天数(≤7,取决于采集情况,非请求窗口长度)
platform_mentions	各平台分项(可空对象)
daily_trend	最近 14 天的按日时间序列;`platform_counts` 为当日平台细分

5.13 竞品汇总

GET /brands/{brand_id}/competitors/summary?days=30

窗口内的竞品总数与总提及数(KPI 口径,不受 5.12 的 Top-N 列表截断影响; 支持 days/from/to/platform)。

{
  "data": {
    "total_competitors": 42,
    "total_mentions": 1280
  }
}

字段	说明
total_competitors	窗口内去重竞品数
total_mentions	窗口内竞品被提及总次数

5.14 竞品分平台

GET /brands/{brand_id}/competitors/by-platform?days=30

每个平台下的竞品提及次数与加权排名分(支持 days/from/to/platform)。

示例响应

{
  "data": [
    {
      "platform": "deepseek",
      "entity_name": "某竞品 A",
      "mention_count": 12,
      "avg_rank_score": 15.3,
      "is_our_brand": false
    }
  ]
}

字段	说明
mention_count	该平台下该竞品提及次数
avg_rank_score	该平台下的加权排名分(0–100)
is_our_brand	是否为「我方品牌」

5.15 竞品全量累计

GET /brands/{brand_id}/competitors/overview

无时间参数,返回该品牌所有时间累计的竞品统计:

{
  "data": {
    "total_competitors": 120,
    "total_mentions": 8420,
    "max_platform_count": 6
  }
}

字段	说明
total_competitors	累计去重竞品数
total_mentions	累计竞品提及总次数
max_platform_count	单个竞品覆盖过的最大平台数

采集录屏

5.16 采集录屏(可回放)

GET /brands/{brand_id}/crawl-replays?date=2025-12-08

返回指定日期(默认今天,Asia/Shanghai)按话题分组、每平台一条快照 + 录屏 URL 的列表。用于「真实采集 · 可回放」核验:每条 AI 回答都能回放采集过程。

参数	类型	默认	说明
`date`	string	今天	`YYYY-MM-DD`(Asia/Shanghai);超出近 7 天范围返回空 `topics`

示例响应

{
  "data": {
    "brand_id": "f6c5f69c-...",
    "date": "2025-12-08",
    "retention_days": 7,
    "topics": [
      {
        "topic_id": "9f4c...e1",
        "topic_keyword": "云端数据库 推荐",
        "search_prompt": "云端数据库 推荐 2025",
        "snapshots": [
          {
            "snapshot_id": "a1b2...c3",
            "platform": "deepseek",
            "video_url": "https://oss.example.com/replay/...?Expires=...&Signature=...",
            "video_preview_url": "https://oss.example.com/replay/...-preview.mp4?...",
            "video_thumb_url": "https://oss.example.com/replay/...-thumb.jpg?...",
            "video_duration_ms": 18420
          }
        ]
      }
    ]
  }
}

字段	说明
date	实际生效的日期(传空时服务端按今天补齐后回传)
retention_days	可回放天数(固定 7)
topic_keyword / search_prompt	话题词 / 采集时下发的搜索提示词
snapshot_id	快照 ID
platform	采集平台
video_url	录屏可播放地址(OSS 签名 URL,1 小时有效)
video_preview_url / video_thumb_url	预览视频 / 缩略图地址(签名 URL,同样 1 小时)
video_duration_ms	录屏时长(毫秒)

6. 调用示例

curl

curl -H "X-API-Key: $API_KEY" \
  "https://geo.yueyuezi.com/open-api/v1/brands"

curl -H "X-API-Key: $API_KEY" \
  "https://geo.yueyuezi.com/open-api/v1/brands/<brand_id>/trend?days=14"

curl -H "X-API-Key: $API_KEY" \
  "https://geo.yueyuezi.com/open-api/v1/brands/<brand_id>/sentiment-mentions?sentiment=negative&page_size=50"

curl -H "X-API-Key: $API_KEY" \
  "https://geo.yueyuezi.com/open-api/v1/brands/<brand_id>/crawl-replays?date=2025-12-08"

Python

import os, requests, time

API_KEY = os.environ["API_KEY"]
BASE = "https://geo.yueyuezi.com/open-api/v1"
H = {"X-API-Key": API_KEY}

def get(path, **params):
    url = f"{BASE}{path}"
    while True:
        r = requests.get(url, headers=H, params=params or None, timeout=10)
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()["data"]
        time.sleep(int(r.headers.get("Retry-After", "1")))

brands = get("/brands")
brand_id = brands[0]["id"]

trend = get(f"/brands/{brand_id}/trend", days=14)
sentiment = get(f"/brands/{brand_id}/sentiment-overview", days=30)
replays = get(f"/brands/{brand_id}/crawl-replays", date="2025-12-08")

限流处理

单密钥 1 QPS,超限返回 429 rate_limited 并带 Retry-After 头(秒)。推荐对每次请求都做 429 重试(见上方 Python 示例的 get 封装)。

独角兽GEO - OpenAPI

#1. 基本信息

#2. 鉴权

#2.1 切换工作区(可选)

#3. 通用响应格式

#4. 通用查询参数

#5. 接口列表

#品牌数据

#5.1 品牌列表

#5.2 品牌详情

#5.3 话题列表

#5.4 排名概览(按话题)

#5.5 品牌整体趋势

#5.6 每日排名位置

#口碑洞察

#5.7 口碑概览

#5.8 评价节选

#引用来源

#5.9 引用来源列表

#5.10 引用来源汇总

#5.11 引用来源趋势

#竞品分析

#5.12 发现的竞品

#5.13 竞品汇总

#5.14 竞品分平台

#5.15 竞品全量累计

#采集录屏

#5.16 采集录屏(可回放)

#6. 调用示例

#curl

#Python

#限流处理

1. 基本信息

2. 鉴权

2.1 切换工作区(可选)

3. 通用响应格式

4. 通用查询参数

5. 接口列表

品牌数据

5.1 品牌列表

5.2 品牌详情

5.3 话题列表

5.4 排名概览(按话题)

5.5 品牌整体趋势

5.6 每日排名位置

口碑洞察

5.7 口碑概览

5.8 评价节选

引用来源

5.9 引用来源列表

5.10 引用来源汇总

5.11 引用来源趋势

竞品分析

5.12 发现的竞品

5.13 竞品汇总

5.14 竞品分平台

5.15 竞品全量累计

采集录屏

5.16 采集录屏(可回放)

6. 调用示例

curl

Python

限流处理