# data-hub API

> version: 0.14.0 · capabilities: macro, metals, news, opinion, policy, yc

面向 AI agent 的结构化数据查询 API。六个数据集:
- **news** CCTV《新闻联播》(2016 至今,每日更新,中文全文检索)
- **yc** Y Combinator 公开公司目录(全部批次的公司与创始人,定期更新,英文全文检索)
- **policy** 国务院政策文件库(国发/国办发等中央政策原文,每日更新,中文全文检索)
- **opinion** 人民日报评论语料(人民时评/人民论坛/评论员观察等,2023 至今,每日更新;
  申论素材场景:输出提要金句+摘要+出处链接,不含全文)
- **macro** 国家统计局宏观经济时间序列(GDP/CPI/PPI/M2/失业率/人口 … 数值序列,
  全国+分省,月/季/年频率,按月更新;数字+时间+地区三维可查可聚合)
- **metals** 中国黄金/白银价格时间序列(SGE 上海金交所现货 2016 至今 + SHFE 上期所期货主连
  黄金 2008/白银 2012 至今,日 OHLC,按日更新;金价/银价/金银比走势可查可聚合)

Base URL: https://api.lumina-core.cn

## 认证
所有 /v1/* 请求在 HTTP 头携带:
    X-API-Key: <你的 key>
缺失或无效 → 401。两类 429(都带 Retry-After 响应头,单位秒):
- 限流:瞬时请求过快(默认 60 次/分,按 key),稍候重试;
- 日配额:免费额度用尽(自助 key 默认 1000 次/天,北京时间次日 0 点重置)。
自助拿 key:https://console.lumina-core.cn/register(注册→邮箱验证→控制台生成,免费)。

## 30 秒上手
请求:
    curl -H "X-API-Key: <key>" "https://api.lumina-core.cn/v1/news?q=新能源&limit=3"
响应(带 q 检索时,默认返回命中片段 snippet 而非整段正文,省上下文):
    {"total": 1277, "limit": 3, "offset": 0,
     "items": [{"id":1,"news_date":"2026-06-04","title":"...","url":"...",
                "snippet":"…大力发展【新能源】汽车产业…"}, ...]}

## 端点
- GET  /v1/news                        简单查询(可贴链接,见下方参数)
- GET  /v1/news?group_by=year          按时间聚合计数(画趋势曲线)
- POST /v1/news/search                 结构化查询:多词 AND/OR/精确短语(见下)
- GET  /v1/news/{id}                   取单条(始终含完整正文)
- GET  /v1/news/stats/daily?date=YYYY-MM-DD   某天条数(等价于 group_by=day 限定单日)
- GET  /health                         健康检查(免认证)

## GET /v1/news 查询参数(全部可选,可组合)
- q          全文检索(标题+正文)。**整体作为一个精确短语**,空格按字面,不拆词。
             ≥3 字走全文索引,更短回退模糊匹配。要"多词都命中/任一命中"用 POST /v1/news/search。
             ★ 带 q 时,每条默认返回 snippet(命中片段,关键词【】高亮),并隐藏整段 content
               以省上下文;要整段正文请在 fields 里显式带上 content。
- group_by   按时间粒度聚合计数: year | month | day。给定时返回 {group_by,total,buckets},
             buckets 按时间键升序(适合直接画曲线);此时忽略 fields/排序/分页。
             例:?q=人工智能&group_by=year 得逐年提及曲线。
- title      仅按标题模糊匹配
- start_date / end_date   按日期闭区间过滤,格式 YYYY-MM-DD
- fields     字段投影,逗号分隔。可选: id,news_date,title,url,content,created_at,updated_at
             —— 不需要正文时传 fields=news_date,title,url 可大幅减小响应;
               带 q 时想要整段正文,把 content 加进来即可(snippet 仍会附带)。
- order_by   排序字段: news_date(默认) | created_at | id
- order_dir  asc | desc(默认 desc)
- limit      每页 1-500(默认 50) / offset 偏移量(默认 0)

## POST /v1/news/search 结构化查询(JSON body)
多词检索用三个独立字段表达,彻底避开"空格当 AND"的歧义;每个词/短语都是独立单元、可含空格。
其余过滤/聚合/分页字段与 GET 相同(title/start_date/end_date/fields/group_by/order_*/limit/offset)。
    curl -X POST -H "X-API-Key: <key>" -H "Content-Type: application/json"       -d '{"all":["新能源","汽车产业"],"group_by":"year"}'       https://api.lumina-core.cn/v1/news/search
- all     list,**都要命中(AND)**
- any     list,**任一命中(OR)**
- phrase  string,**整体精确短语**(空格按字面)
返回形状与 GET 一致(列表或带 group_by 的聚合);带文本检索时同样默认返回 snippet。

## yc:Y Combinator 公司目录
数据口径:YC 公开发布的 launched 公司(不含 stealth 在投),含创始人。scope: yc:read。
- GET  /v1/yc/companies                 轻量查询(可贴链接);过滤 + group_by + 分页
- POST /v1/yc/companies/search          复杂筛选 / 二维聚合 / 多词文本(body 表达力强)
- GET  /v1/yc/companies/{slug}          单个公司全字段 + 创始人内嵌(slug 如 "stripe")
- GET  /v1/yc/founders?q=…              创始人检索(姓名/bio 全文 + 公司维度过滤)

GET /v1/yc/companies 参数:q(精确短语)、batch(全名如 "Winter 2025",也接受缩写 W25/S25/X25/F25)、
status(Active|Acquired|Inactive|Public)、
industry、tag(如 AI)、batch_year_from/to、is_hiring、top_company、group_by、fields、order_*、limit/offset。
    curl -H "X-API-Key: <key>" "https://api.lumina-core.cn/v1/yc/companies?tag=AI&group_by=batch_year"

聚合维度 group_by(≤2 维交叉,逗号分隔):
  batch_year batch status industry subindustry country group_partner tag region
  例:group_by=batch_year,status → 各批次的存活结局交叉(嵌套 buckets,外层带 sub 子分布)。
POST /v1/yc/companies/search 额外支持:all/any/phrase 文本、subindustry/country/stage/region 过滤、
  team_size_min/max、nonprofit,以及 group_by 传数组(["batch_year","status"])。
玩法示例:AI 公司逐年趋势(tag=AI&group_by=batch_year)、某批次十年存活率(batch_year_from/to + group_by=status)、
  在招聘的赛道分布(is_hiring=true&group_by=industry)、连续创业者(GET /v1/yc/founders 搜 bio)。

## policy:国务院政策文件库
数据口径:gov.cn 政策文件库的国务院文件(国发/国办发/国函/国办函等,1996 至今,
正文全文)。官方下架的文件不进列表/聚合,按 id 直取仍可见(withdrawn=1)。scope: policy:read。
- GET  /v1/policy                       轻量查询(可贴链接);检索 + 过滤 + group_by + 分页
- POST /v1/policy/search                结构化查询:多词 AND/OR/精确短语 + 复杂筛选/聚合
- GET  /v1/policy/{id}                  单条全文(始终含完整正文)

GET /v1/policy 参数:q(精确短语,带 q 默认返回 snippet 同 news)、title、
pcode(发文字号精确,如 国发〔2026〕15号)、doctype(国发|国办发|国函|国办函)、
org(发文机关)、theme(主题分类顶层,如 综合政务)、start_date/end_date(发布日期)、
fields、group_by、order_by(pub_date|write_date|id)、order_dir、limit/offset。
    curl -H "X-API-Key: <key>" "https://api.lumina-core.cn/v1/policy?q=人工智能&limit=3"

聚合维度 group_by(≤2 维交叉,逗号分隔): year month doctype org theme
  例:group_by=year,doctype → 逐年发文的文种构成;?q=数字经济&group_by=year → 主题政策热度曲线。
POST /v1/policy/search 同 news 风格:all/any/phrase 三单元文本 + 上述全部过滤,group_by 传数组。
玩法示例:新闻联播查到政策名 → /v1/policy?title=… 拿原文全文;
  某主题政策时间线(q + group_by=year);某年国办发文清单(doctype=国办发&start_date=…)。

## opinion:人民日报评论语料(考公申论素材)
数据口径:人民日报电子版(paper.people.com.cn)按栏目白名单收录的评论文章
(人民时评/人民论坛/评论员观察/今日谈/现场评论/钟声/和音等,2023-01 至今,每日更新)。
**版权口径:API 不输出全文**——对外为 元数据 + digest(官方提要/金句) + excerpt(首段摘要)
+ 检索命中 snippet + url(电子版原文链接);全文仅内部索引用。scope: opinion:read。
- GET  /v1/opinion                      轻量查询(可贴链接);检索 + 主题 + 过滤 + group_by + 分页
- GET  /v1/opinion/topics               申论主题目录(~25 主题词表 + 各主题命中篇数)
- POST /v1/opinion/search               结构化查询:多词 AND/OR/精确短语 + 复杂筛选/聚合
- GET  /v1/opinion/{id}                 单条(元数据+提要+摘要+原文链接,不含全文)

GET /v1/opinion 参数:q(精确短语,命中返回 snippet)、topic(申论主题,slug 或中文名,
服务端展开为同义词 OR 检索,可与 q 叠加 AND 收窄)、title、column(栏目基名,如 人民时评)、
author(作者)、page_name(版面名,如 评论)、start_date/end_date(见报日期)、
fields(默认精简,提要/摘要请带 digest,excerpt)、group_by、
order_by(pub_date|id|relevance —— relevance=bm25 相关度,标题/提要命中加权,
压制"正文顺带提及";需文本/主题检索且词 >=3 字)、order_dir、limit/offset。
    curl -H "X-API-Key: <key>" "https://api.lumina-core.cn/v1/opinion?topic=基层治理&order_by=relevance&fields=title,digest,excerpt,url&limit=5"

聚合维度 group_by(≤2 维交叉,逗号分隔): year month day column author
  例:group_by=column → 各栏目体量;?topic=乡村振兴&group_by=year → 主题热度曲线。
POST /v1/opinion/search 同 news 风格:all/any/phrase 三单元文本 + topic + 上述全部过滤,group_by 传数组。
玩法示例:申论按主题找素材(topic=粮食安全&order_by=relevance&fields=title,digest,excerpt,url
  → 金句+出处直接可引,相关度排序);主题目录先看 /v1/opinion/topics(带各主题篇数);
  某栏目近一年盘点(column=人民时评&start_date=…);作者文风集(author=…)。
注意:digest(官方提要)覆盖率约一半且按栏目双峰(人民观点/评论员观察 ≈100%,
人民论坛/思想纵横 ≈0%,版面本就无提要段),digest 为 null 属正常,可退 excerpt。

## macro:国家统计局宏观经济时间序列
数据口径:国家统计局「国家数据」公开宏观指标(GDP/CPI/PPI/规上工业增加值/固定资产投资/
社会消费品零售总额/进出口/M2/城镇调查失业率/人口 …),全国+分省,月/季/年按指标自然频率。
一行 = 一个(指标 × 地区 × 频率 × 期)的数值点;只收录官方原值(同比/环比等派生列后续迭代)。
scope: macro:read。
- GET  /v1/macro                        轻量查询(可贴链接);指标+地区+频率+区间 → 序列点
- GET  /v1/macro?group_by=year          按维度聚合(条数/覆盖统计)
- GET  /v1/macro/indicators             指标目录(可用指标 + 覆盖:条数/地区数/最新期)
- POST /v1/macro/search                 结构化查询:多指标/多地区/区间 + 二维聚合
- GET  /v1/macro/{id}                   单个序列点(全字段)

GET /v1/macro 参数:indicator(NBS 码精确如 A01010101,或指标名模糊如 居民消费价格)、
region(地区码或地区名,全国=全国 或 000000,分省如 广东)、category(顶层归类:价格|GDP|金融|…)、
freq(monthly|quarterly|annual)、start_date/end_date(按 period_date 区间)、
fields、group_by、order_by(period_date|value|id)、order_dir、limit/offset。
    curl -H "X-API-Key: <key>" "https://api.lumina-core.cn/v1/macro?indicator=居民消费价格&freq=monthly&start_date=2016-01-01"
序列点形如 {indicator_code,indicator_name,region,freq,period,period_date,value,unit};
period 是规范期串(2025-05 / 2025Q1 / 2025),value 缺测为 null。

聚合维度 group_by(≤2 维交叉,逗号分隔,条数/覆盖语义): indicator code category region freq year month
POST /v1/macro/search 额外支持:indicators(多指标 OR)、regions(多地区 OR)、group_by 传数组。
玩法示例:近十年 CPI 走势(indicator=居民消费价格&freq=monthly,按 period_date 排序直接画曲线);
  分省 GDP 横向对比(indicator=…&group_by=region);先看 /v1/macro/indicators 拿可用指标与覆盖。

## metals:中国黄金/白银价格时间序列
数据口径:上海黄金交易所(SGE)现货日行情(Au99.99/Au(T+D)/mAu(T+D)/Ag(T+D),2016-12 至今)
+ 上期所(SHFE)黄金/白银期货主力连续(AU0/AG0,经 Sina;黄金 2008、白银 2012 至今)。
一行 = 一个(品种 × 来源 × 交易日)的价格点(日 OHLC);期货另带成交量/持仓,现货无。
只收官方原值(均价/涨跌幅等派生列后续迭代;结算价 v1 未收)。单位:黄金元/克、白银元/千克。
scope: metals:read。
- GET  /v1/metals                       轻量查询(可贴链接);品种+区间 → 价格点
- GET  /v1/metals?group_by=year         按维度聚合(条数/覆盖统计)
- GET  /v1/metals/symbols               品种目录(可用品种 + 覆盖:条数/最早/最新交易日)
- POST /v1/metals/search                结构化查询:多品种/区间 + 二维聚合
- GET  /v1/metals/{id}                  单个价格点(全字段)

GET /v1/metals 参数:symbol(品种码精确如 Au99.99/AU0,或品种名模糊如 黄金)、
metal(gold|silver)、venue(SGE|SHFE)、source(sge_spot 现货|shfe_futures 期货主连)、
start_date/end_date(按 trade_date 区间)、fields、group_by、
order_by(trade_date|close|id)、order_dir、limit/offset。
    curl -H "X-API-Key: <key>" "https://api.lumina-core.cn/v1/metals?symbol=Au99.99&start_date=2024-01-01"
价格点形如 {metal,symbol,symbol_name,venue,trade_date,open,high,low,close,unit};
某价缺测为 null。期货想要量仓在 fields 里带上 volume,open_interest。

聚合维度 group_by(≤2 维交叉,逗号分隔,条数/覆盖语义): metal symbol venue source year month
POST /v1/metals/search 额外支持:symbols(多品种 OR)、group_by 传数组。
玩法示例:近十年金价走势(symbol=AU0,按 trade_date 排序直接画曲线,期货历史最长);
  今天上海金现货价(symbol=Au99.99&order_by=trade_date&limit=1);
  金银比(分别拉 symbol=Au(T+D) 与 Ag(T+D) 两序列,按 trade_date 对齐相除);
  先看 /v1/metals/symbols 拿可用品种与各自起止/单位。

## 返回与错误
- 列表统一形状: {total, limit, offset, items: [...]}
- 聚合形状(带 group_by): {group_by, total, buckets: [{key, count}, ...]}
  二维交叉时每个 bucket 多一层 sub: {key, count, sub: [{key, count}, ...]}
- 错误统一形状: {"error": {"code": <http状态码>, "message": "<说明>"}}

## 往下钻(需要精确契约时)
- 完整机器可读 API 契约 (OpenAPI 3.1): https://api.lumina-core.cn/openapi.json
- 交互式文档 (给人看): https://api.lumina-core.cn/docs

## 使用建议(给 agent)
- 单词/短语检索直接 GET ?q=…(可贴链接);要多词 AND/OR 组合用 POST /v1/news/search。
- 默认 snippet 已是"刚好够用"的上下文,不必拉整段正文;要精读再加 content。
- 要趋势/统计(某词逐年热度、某地出镜分布)用 group_by,一次拿到曲线,别把全量拉回本地自己数。
- 命中条数看 total;大范围逐条浏览用 limit/offset 分页,不要一次拉全量。
- 偶发 502/504 或连接超时为边缘网关到源站的瞬时抖动(非数据错误):退避 2-5 秒重试,通常 1-2 次内恢复;429 则按 Retry-After 等待。

## 缓存与同步(给做了本地快照的 agent)
如果你把本文档固化成了本地技能 / 记忆 / 系统提示,它会随平台更新而过时。自检协议:
1. 使用前(或每次会话首次调用前)GET https://api.lumina-core.cn/ —— 免认证,
   返回 {"version": "...", "capabilities": [...]},约 170 字节。
2. 与你快照中记录的 version / capabilities 比对;**不一致 → 重新读取本文档**
   (https://api.lumina-core.cn/llms.txt),据此更新你的本地快照,再继续任务。
3. 调用收到 404(未知端点)同样应触发重读 —— 端点可能已演进。
能力清单只增不减;已发布端点的请求/响应形状保持向后兼容。