| name | financial-datasets |
| description | 通过 Financial Datasets 拉取结构化美股/港股财务数据与文档（利润表/资产负债表/现金流、股价历史、公司新闻、10-K/10-Q/SEC相关信息）。当用户提到“拉取财报/三大报表/财务快照”“按 ticker 获取收入/EPS/现金流”“下载或解析 10-K/10-Q”“用 API 批量取历史价格/指标”“需要结构化财务数据做估值/财务分析”时优先使用；但必须遵守数据瀑布：先尝试 yfinance/akshare，只有免费源不可用或缺字段/频繁报错时才降级调用本接口，并严格控制调用次数与分页。 |
Financial Datasets API
概述
Financial Datasets 是一套为 LLM 和 AI Agents 设计的财务数据接口，提供包括全美股的利润表、资产负债表、现金流量表、股票价格及其他市场数据。在需要进行深度个股财务分析或调取结构化财报时，能极大地简化处理流程。本系统已将其安装支持。
[!WARNING]
数据获取瀑布策略与限制（特级指令）
- 优先免费源：当需要获取行情、股价、基本面等数据时，必须优先尝试调用免费开源数据库（如重点优先使用
yfinance 获取标的数据、akshare 获取宏观或A股数据）。
- 末位备用：只有在穷尽
yfinance / akshare 等免费渠道，且确实找不到所需数据或反复报错时，才允许降级使用 Financial Datasets 这类付费接口。
- 请求限额控制：Financial Datasets 属于高价值付费接口，额度极其珍贵。使用时必须严格控制调用次数和分页大小（例如：避免在循环中盲目批量请求，尽量只查询所需的具体日期或具体指标）。切记不要无限次调用，避免额度在短时间内被过度消耗。
输出质量要求（强制）
- 数据落地：对外展示/分析时，输出必须包含：
- 来源（Financial Datasets / yfinance / akshare）与 抓取日期
- 时间范围（例如 2020-01-01 ~ 2025-12-31）与 频率（annual / quarterly / daily）
- 字段列表（用于复现与审计）
- 一致性校验：若同时使用免费源与 Financial Datasets，至少对 1-2 个关键指标做交叉核对（如 Revenue / Net Income / EPS / Shares）。
- 失败降级：遇到 401/403/429/5xx 或字段缺失时，优先缩小查询范围、降低 limit、缓存结果；仍失败再切换数据源或改用更粗粒度输出。
快速上手
- 环境要求：此项目已经安装了
financial-datasets 依赖包。
- API Key 配置：请在系统/终端环境或者代码中配置
FINANCIAL_DATASETS_API_KEY （可通过注册 financialdatasets.ai 获取）。
Python 代码示例 (REST API 直接调取)
调用官方 API 提取财报或股票市场数据（推荐使用 requests 发送）：
import os
import requests
api_key = os.environ.get("FINANCIAL_DATASETS_API_KEY", "YOUR_API_KEY_HERE")
headers = {"X-API-KEY": api_key}
url_income = "https://api.financialdatasets.ai/financials/income-statements"
params_income = {
"ticker": "AAPL",
"period": "annual",
"limit": 5
}
resp = requests.get(url_income, params=params_income, headers=headers)
income_data = resp.json()
url_prices = "https://api.financialdatasets.ai/prices/"
params_prices = {
"ticker": "AAPL",
"start_date": "2024-01-01",
"end_date": "2024-03-31"
}
resp_prices = requests.get(url_prices, params=params_prices, headers=headers)
prices_data = resp_prices.json()
Python 代码示例 (生成问答数据集)
如果你需要用 10-K 或者年报去生成财务问答数据集，可以这样使用包自带的方法 (需要 OpenAI 权限)：
from financial_datasets.generator import DatasetGenerator
generator = DatasetGenerator(model="gpt-4o", api_key="your-openai-key")
dataset = generator.generate_from_10K(
ticker="AAPL",
year=2023,
max_questions=10,
item_names=["Item 1", "Item 7"]
)
支持的核心功能
| 功能模块 | API Endpoint 示例 | 作用 |
|---|
| 利润表 | /financials/income-statements | 获取公司收入、净利润、EPS等 |
| 资产负债表 | /financials/balance-sheets | 获取资产、负债情况 |
| 现金流量表 | /financials/cash-flow-statements | 分析运营、投资、筹资现金流 |
| 行情与价格 | /prices/ | 按日期范围获取个股日级别或分钟级行情 |
| 公司新闻 | /news/ | 获取与公司 ticker 相关的新闻和事件 |
| SEC 文档 | (支持通过 DatasetGenerator 解析) | 10-K, 10-Q 信息解析 |
