# FinData 金融数据 API / MCP

用同一套只读接口查询美股行情、公司财报、盈利预期、机构评级、SEC 披露和研究快照。可以由程序通过 REST 接入，也可以由 AI 通过 MCP 调用。

> **样例方案 · 数据尚未补全**：本服务用于体验数据查询与系统接入，目前仅提供部分股票、期间及字段的已保存数据，不代表全市场覆盖，也不是实时行情。样例可查询不等于数据质量已全部验收。

首次体验请保留调试页预填的股票代码，不填日期、财期等可选筛选，先取得第一份返回结果，再按实际覆盖调整参数。默认样例只影响文档调试，不会将客户明确请求的股票替换成其他股票。未收录或无匹配的数据如实返回空数组，不自动补零或换股。

数据目录提供 `sample_query`（可直接使用的样例参数）和 `sample_status`。调用 `GET /v1/datasets` 或 MCP `discover_datasets()` 查看当前开放的接口。客户目录、调试文档及 MCP 工具列表仅展示已有记录的数据集；尚未形成样例的数据能力作为内部后续建设项，不对外列为可用接口。

例如补充财务指标接口当前覆盖 DAL、JPM、KO、META、NVDA、PLD、WMT，默认演示 DAL；BRK.B 在此接口暂无记录，不能据此推断其他接口也没有 BRK.B。机构共识演示 AAPL，首次查询不要额外填写 `period_type=annual`。覆盖以当前数据目录为准。

[在线 API 调试](/docs) · [完整数据字典](/data-reference) · [OpenAPI 契约](/openapi.json) · [本页 Markdown](/guide.md) · [AI 索引](/llms.txt)

## 1. 五分钟完成第一次查询

准备服务地址和独立提供的访问密钥。在 [API 调试](/docs) 顶部确认当前服务地址，粘贴密钥并点击 **验证并连接**。看到“已连接：密钥验证成功”后，再展开接口，点击 **Try it out → Execute**。查询自动携带授权，不用手动拼接 `Bearer`。

密钥只保存在当前标签页的会话中，刷新后自动重新验证；点击 **清除授权** 可立即移除。浏览器禁止会话存储时，页面会提示刷新后重新输入。**本地测试与服务器使用不同密钥**，必须与页面显示的服务地址对应。验证成功只证明访问权限有效，不代表数据准确性已验收。

也可直接使用以下命令。示例为 Bash；Windows 请使用 `curl.exe` 并按终端语法设置环境变量。不要将密钥写进 URL、公开代码或 AI 提示词。

```bash
export FINDATA_BASE_URL="https://43.167.212.164"
# FINDATA_API_KEY 设置为服务方单独提供的密钥。

# 第一步：哪些机构数据现在有记录？
curl "$FINDATA_BASE_URL/v1/datasets?domain=analysts&available_only=true" \
  -H "Authorization: Bearer $FINDATA_API_KEY"

# 第二步：它有哪些股票、字段，日期筛选针对哪个日期？
curl "$FINDATA_BASE_URL/v1/datasets/analysts/ratings" \
  -H "Authorization: Bearer $FINDATA_API_KEY"

# 第三步：读取 AAPL 的一条机构评级事件。
curl "$FINDATA_BASE_URL/v1/analysts/ratings?ticker=AAPL&limit=1" \
  -H "Authorization: Bearer $FINDATA_API_KEY"
```

返回 `200` 表示查询成功；`data: []` 表示当前筛选无匹配，不表示请求失败。

## 2. 按业务问题选择接口

以下是常用入口，不是全部能力；所有数据集都保留在目录和 [字段参考](/data-reference) 中。

| 我想知道什么 | 应使用的接口 | 关键区别 |
|---|---|---|
| 股票每天的价格和成交量 | `/v1/market/daily` | 原始 OHLCV |
| 长期行情、复权收盘价、分红及拆股 | `/v1/market/daily-adjusted` | 仅 adjusted_close 为复权收盘价，其他 OHLC 未整体复权 |
| 公司利润、资产负债和现金流 | `/v1/financials/income-statements`、`balance-sheets`、`cash-flows` | 按报告财期；三种报表在同一前缀下 |
| 市场预计公司未来赚多少钱、预期是否上调 | `/v1/estimates/earnings` | EPS / 营收聚合预期及修订指标；不是逐家券商预测 |
| 多少分析师看多、目标价共识是什么 | `/v1/analysts/consensus` | 评级、目标价摘要；人数口径不同，目标价可能缺失 |
| 具体哪家机构调整了评级或目标价 | `/v1/analysts/ratings` | 逐机构事件；不是完整研报，也不是逐机构 EPS 预测 |
| 带财期、单位和会计口径的盈利预测 | `/v1/analysts/estimates` | 指标级结构化预测；覆盖与 earnings 接口不同，不能直接拼接统计人数 |
| 找披露文件及其正文 | `/v1/sec/filings`、`/v1/sec/documents`、`/v1/sec/document-chunks` | 申报目录、已解析文档和正文片段是不同资源 |
| 某机构披露了哪些持仓 | `/v1/sec/13f/positions` | 申报持仓；有披露时滞，保留修订稿 |
| 内部人交易或基金持仓 | `/v1/sec/insiders/transactions`、`/v1/sec/funds/positions` | 内部人记录也包含非交易持有记录 |
| 看已有因子、特征和组合结果 | `/v1/research/` 下的具体数据集 | 已保存的研究批次，不是实时信号 |

`/v1/companies/` 提供公司概况。预测历史表格保留在 `/v1/analysts/tables` 和 `/v1/analysts/detail-tables`，优先使用结构化接口，再用表格补充。

## 3. 覆盖、日期和一行的含义

`GET /v1/datasets` 返回简短目录，可按 `domain`、`available_only` 筛选。`GET /v1/datasets/{dataset_id}` 返回单个数据集详情。例如 `dataset_id=analysts/ratings`。

| 详情字段 | 如何使用 |
|---|---|
| purpose / record_grain | 这个接口做什么、一行代表什么；不要把观测版本当成独立事件 |
| count / availability | 整个数据集的记录数及是否有记录；不是本次筛选总数 |
| symbols | 已登记标的；未列出清单不表示覆盖全市场，某些披露需按 CIK / CUSIP 查询 |
| filters / fields | 支持哪些筛选条件、各响应字段的类型和意义 |
| time_basis | start/end 实际筛选哪个日期字段 |
| observed_at_max | 数据集已知最新保存观测时间；不是首次公开时间 |
| start / end | 数据日期覆盖范围；预测的 end 可能在未来，不能当作更新日期 |
| usage_notes | 聚合、修订、会计口径及解释边界 |

日期筛选采用 `YYYY-MM-DD`，包含起止两端。例如评级事件的 `start/end` 当前筛选 **observed_at**，事件本身的日期是 **data.event_date**。财期、交易日、申报日和观测时间不是同一概念。

所有筛选条件都是精确匹配，股票代码大小写不敏感。CIK 保留前导零，股票股类标点按目录填写，例如 `BRK.B`。仅使用对应接口声明的筛选字段，不支持 SQL、模糊搜索或任意排序。

## 4. 看懂返回结果

所有业务分类查询都返回 `data`、`meta`、`pagination`。下面是保存快照中的评级记录**节选**，省略部分字段，仅用于理解结构，不代表当前评级或投资建议。

```json
{
  "data": [{
    "ticker": "AAPL",
    "currency": "USD",
    "observed_at": "2026-09-21T03:17:49.217000+00:00",
    "quality_status": "checked",
    "data": {
      "institution": "Evercore ISI",
      "analyst": "Amit Daryanani",
      "event_date": "2026-09-15",
      "action": "Maintains",
      "rating": "buy",
      "target": 365.0,
      "target_previous": null
    }
  }],
  "meta": {
    "dataset": "analysts/ratings",
    "time_basis": "observed_at",
    "strict_pit_certified": false
  },
  "pagination": {"limit": 1, "offset": 0, "returned": 1, "next_offset": 1}
}
```

金额和精确小数可能用字符串表示，数字字符串应按字段语义转换为 Decimal，不要把所有字符串转成数字。币种、单位、GAAP / non-GAAP 和股类需一起解读；缺失币种不能默认美元。`null`、字段缺失及历史文本 `None` 都不能擅自补成零。

`checked` 表示记录核对，`unverified` 表示未核验，`quarantined` 表示疑问值隔离。质量备注和隔离状态必须保留。`strict_pit_certified=false` 表示尚未通过严格时点认证，不能直接宣称可做无前视偏差回测。

## 5. Python 查询与分页

安装 `httpx`，设置 `FINDATA_BASE_URL` 和 `FINDATA_API_KEY` 后运行。下面会按页输出 IBM 的盈利预期。实际覆盖先查目录。

```python
import os
import time
import httpx

with httpx.Client(
    base_url=os.environ["FINDATA_BASE_URL"].rstrip("/"),
    headers={"Authorization": "Bearer " + os.environ["FINDATA_API_KEY"]},
    timeout=60,
) as client:
    offset, release = 0, None
    while True:
        for attempt in range(4):
            response = client.get("/v1/estimates/earnings", params={
                "ticker": "IBM", "limit": 100, "offset": offset})
            if response.status_code != 429 or attempt == 3:
                break
            time.sleep(int(response.headers.get("Retry-After", "60")))
        response.raise_for_status()
        page = response.json()
        if release is not None and release != page["meta"]["built_at"]:
            raise RuntimeError("数据版本已切换，请重新开始分页")
        release = page["meta"]["built_at"]
        for row in page["data"]:
            print(row)
        offset = page["pagination"]["next_offset"]
        if offset is None:
            break
```

默认每页100条，最大500条；没有10000条总量上限。固定快照内顺序稳定，但**不保证按日期排序**。只能按 `next_offset` 继续，不能将返回数组第一条自动当作最新值。`returned` 是本页条数，服务不提供昂贵的实时筛选总数。

## 6. 让 AI 通过 MCP 接入

MCP 地址为服务地址下的 `/mcp`，传输方式是 **Streamable HTTP**，使用同一个 Bearer 密钥。客户端需支持自定义 Authorization 头；不同 AI 产品的配置格式不同，请将密钥保存在客户端的凭据配置中。

推荐工具调用顺序：

1. `discover_datasets(domain="analysts", available_only=true)`：先查看简短目录。
2. `describe_dataset(dataset_id="analysts/ratings")`：读取覆盖、字段和日期口径。
3. `query_analysts_ratings(filters={"ticker":"AAPL"}, limit=10)`：查询已选资源。
4. 结果不为空时，结合 quality_status 和日期解读；需要下一页时使用 next_offset。

每个 `query_...` 工具提供具体筛选字段的 inputSchema 和嵌套响应的 outputSchema。工具名与 REST operationId 一致，数据结果相同。未知筛选字段会被拒绝。

可以对 AI 这样表达需求：“先检查数据覆盖，再查询 AAPL 已保存的机构评级事件。说明事件日期、观测日期和质量状态；不要把它描述为当前评级，也不要把共识预测写成某家券商的 EPS 预测。”

```python
import asyncio
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client(
        os.environ["FINDATA_BASE_URL"].rstrip("/") + "/mcp",
        headers={"Authorization": "Bearer " + os.environ["FINDATA_API_KEY"]},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            contract = await session.call_tool("describe_dataset", {
                "dataset_id": "analysts/ratings"})
            if contract.isError:
                raise RuntimeError(contract.content)
            result = await session.call_tool("query_analysts_ratings", {
                "filters": {"ticker": "AAPL"}, "limit": 10})
            if result.isError:
                raise RuntimeError(result.content)
            print(result.structuredContent)

asyncio.run(main())
```

MCP 中工具执行错误表现为 `isError=true`；参数结构不符合 schema 时可能是协议错误。传输层鉴权与限流仍返回 HTTP 401 / 429，不要只检查 JSON 中有没有 data。

## 7. 错误、限额和排查

| HTTP | 错误码 | 下一步 |
|---|---|---|
| 400 | invalid_parameters | 按接口契约检查参数、日期和分页边界；不要直接重试同一参数 |
| 401 | unauthorized | 调试页顶部重新验证当前服务的密钥；程序调用检查 Authorization: Bearer 请求头。不要混用本地与服务器密钥，也不要把密钥放进 URL |
| 403 / 421 | invalid_origin / invalid_host | 使用分配的服务入口；浏览器跨域接入需由服务方配置 |
| 404 | unknown_dataset | 从 /v1/datasets 选择准确的数据集 id |
| 408 / 413 | request_timeout / body_too_large | 请求体读取超时或超过32 KiB；减少输入体积 |
| 429 | rate_limited / busy | 按响应头 Retry-After 的秒数等待，限制重试次数 |
| 503 | data_unavailable | 稍后重试；持续失败请提供 request_id |

REST 错误体示例：

```json
{"error":{"code":"invalid_parameters","message":"Unknown filters: symbol","request_id":"示意请求标识"}}
```

当前试用配额：**最多2个在途请求、每分钟120次认证请求**，MCP 握手也计入。密钥持有者共用额度。大型披露表优先筛选 ticker、CIK、CUSIP 或 accession_number。请求失败时保留 request_id、请求路径和时间；不要把密钥附在反馈中。

## 8. URL 规范与兼容性

采用 `GET /v1/{业务域}/{资源}`：小写英文、复数资源名、复合词用短横线；股票、日期和分页放在查询参数。SEC 的 13F、N-PORT 等表格保留监管领域含义。路径描述数据内容，不包含供应商、采集文件名或数据库表名。

`/v1/datasets` 是数据发现入口；`/v1/catalog` 继续提供完整目录。已有业务 URL 和 `query_...` 工具名保持有效，不因文案优化而改名。研究批次接口也继续保留，但不作为初次接入的默认入口。

`/v1/{dataset}` 下的旧有限快照接口及旧 `get_...` 工具仅用于兼容，新接入使用本指南的业务分类接口。新字段会以兼容方式增加，客户端应容忍未知响应字段；删除字段、改变字段含义或类型需要新的主版本。API 文档的软件版本与 URL 中的数据契约主版本是两回事。

服务会显示数据截至时间；更新发生在新快照发布后。13F / N-PORT 保留申报版本及修订稿，用 accession_number 关联申报与明细。13F reported_value 需结合 value_scale，value_usd 已换算美元。不同层、不同观测与研究批次可能重复，不可直接相加。