Wanying API 文档

1. 文档索引

2. 服务定位

Wanying API 是唯一服务于 wanying-quant skill DataEngine 的只读数据通道：把 26 个实体以「面板加载友好」的 REST API 暴露出来。

• 只做查询，不做计算：因子、回测、筛选、诊断均在客户端（wanying-quant 引擎）完成，本服务只返回原始实体数据与完整性信息。
• 只读：无任何写路径。
• 不实时补抓：数据缺口经 gaps 端点显式暴露，兜底由客户端执行。

3. 快速开始

import requests

BASE = "https://api.wanying.iovp.com"
TOKEN = "tr_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

resp = requests.get(
    f"{BASE}/api/v1/entities/daily",
    params={"start_date": "20240101", "end_date": "20241231",
            "fields": "ts_code,trade_date,close", "limit": 100},
    headers={"Authorization": f"Bearer {TOKEN}"},
    timeout=60,
)
data = resp.json()
print(data["entity"], data["count"], data["columns"], data["rows"][0])

4. 鉴权方式

所有 /api/v1/* 端点均需携带有效 token。有效 token 即可访问全部 26 实体，无套餐、无配额、无计量。

两种携带方式（任选其一）：

1. HTTP 请求头（推荐）：Authorization: Bearer <token>
2. 查询参数：?token=<token>

# 方式一：请求头
requests.get(f"{BASE}/api/v1/meta", headers={"Authorization": f"Bearer {TOKEN}"})

# 方式二：查询参数
requests.get(f"{BASE}/api/v1/meta", params={"token": TOKEN})

token 无效、缺失或已禁用时，返回 401 invalid_token。

5. 通用请求协议

所有实体共用同一资源化端点：

GET /api/v1/entities/{entity}

其中 {entity} 为 26 个实体名之一（见各实体页）。

5.1 通用参数

参数	类型	说明
start_date / end_date	YYYYMMDD	时间区间过滤，作用于各实体的主日期列（见各实体页的「主日期列」）。可只传其一。
ts_code	逗号分隔字符串	单票或多票，如 000001.SZ,600000.SH；不传 = 全市场。指数类实体对应指数代码。
fields	逗号分隔字符串	列投影，只取需要的列；不传 = 该实体全部业务字段。
as_of	YYYYMMDD	point-in-time 锚点（仅财务类、research_report、anns_d、index_member 有效）：只返回 公告日 <= as_of 的行，防未来函数。
period	YYYYMMDD	报告期筛选（仅财务类有效，作用于 end_date 列）。
limit	int	本次返回行数上限。默认：json 10000 / arrow·parquet 100000；硬上限：json 50000 / 二进制 500000。
cursor	string	分页游标（上一响应 next_cursor 原样回传）。
format	enum	json（默认）/ arrow（Arrow Feather v2，zstd）/ parquet。

5.2 JSON 响应结构

{
  "entity": "daily",
  "data_version": "2026-08-14T22:50:21+00:00",
  "columns": [
    {"name": "ts_code", "dtype": "string"},
    {"name": "trade_date", "dtype": "string"},
    {"name": "close", "dtype": "float64"}
  ],
  "rows": [
    ["000001.SZ", "20240102", 10.30],
    ["000002.SZ", "20240102", 8.12]
  ],
  "count": 2,
  "truncated": false,
  "next_cursor": null
}

字段	类型	说明
entity	string	实体名。
data_version	string	数据版本（ISO-8601 时间戳），研究快照存此值可实现可复现。
columns	array	列元信息：name（列名）+ dtype（string / float64 / int64）。
rows	array	数据行，二维数组，列顺序与 columns 一致。
count	int	本页返回行数。
truncated	bool	是否还有更多数据（true 表示需用 next_cursor 续取）。
next_cursor	string|null	下一页游标；为 null 表示已到末尾。

5.3 二进制格式（arrow / parquet）

format=arrow 时响应体为 Feather v2（Arrow IPC file，zstd 压缩），可被 pandas.read_feather 与 polars.read_ipc 直接零拷贝加载；format=parquet 为 Parquet（zstd）。元信息经响应头传递：

响应头	说明
X-Entity	实体名。
X-Data-Version	数据版本。
X-Truncated	true / false，是否有下一页。
X-Next-Cursor	下一页游标（无则缺省）。

import io, pandas as pd, requests

resp = requests.get(f"{BASE}/api/v1/entities/daily",
                    params={"format": "arrow", "limit": 100000},
                    headers={"Authorization": f"Bearer {TOKEN}"})
df = pd.read_feather(io.BytesIO(resp.content))  # 零拷贝进 pandas
print(df.shape)

5.4 分页（游标）

服务端执行一律 LIMIT 上限+1，返回超界时 truncated:true + next_cursor。游标为 keyset 分页（按实体主键序，稳定高效），客户端循环续取直到 truncated=false：

import io, pandas as pd, requests

def load_panel(entity, **params):
    """一次性面板加载：自动循环游标分页，返回合并后的 DataFrame。"""
    params.setdefault("format", "arrow")
    cursor, frames = None, []
    while True:
        p = dict(params)
        if cursor:
            p["cursor"] = cursor
        r = requests.get(f"{BASE}/api/v1/entities/{entity}",
                         params=p, headers={"Authorization": f"Bearer {TOKEN}"})
        r.raise_for_status()
        frames.append(pd.read_feather(io.BytesIO(r.content)))
        if r.headers.get("X-Truncated") == "true":
            cursor = r.headers["X-Next-Cursor"]
        else:
            break
    return pd.concat(frames, ignore_index=True)

df = load_panel("daily", start_date="20240101", end_date="20241231",
                fields="ts_code,trade_date,close")

6. 错误响应

统一 JSON 结构：

{"error": {"code": "invalid_params", "message": "参数格式错误", "details": {"start_date": "..."}}}

code	HTTP	含义
invalid_token	401	token 缺失 / 无效 / 已禁用。
invalid_params	400	参数格式错误、未知参数。
entity_not_found	404	{entity} 不在 26 实体清单（含被移除的舆情/互动/分钟类）。
entity_unavailable	404	实体在基线内但数据尚未落库 / 回补未完成。
request_too_large	413	ts_code/fields 数量超限，或响应超过字节上限。
limit_exceeded	400	limit 超上限 / cursor 无效或过期。
query_timeout	504	单查询超时被终止。
rate_limited	429	触发并发 / 频率保护（每 token 30 req/s）。
internal_error	500	查询异常。
datastore_unavailable	503	数据服务暂不可用 / 被锁定。

原则：数据缺口显式报错并给范围，不静默返回空数据。

7. 字段类型与格式约定

• dtype 取值：string / float64 / int64。日期列以 string 形式返回（YYYYMMDD），数值缺失记为 null。
• 财务类实体主日期列为 ann_date（公告日）；as_of 默认过滤 ann_date <= as_of，杜绝未来函数。
• trade_cal 是所有时间对齐的基准日历（is_open：1 开市 / 0 休市）。
• 所有响应携带 data_version，研究快照存此值可追溯到数据状态。