Vibe-Trading 接入 Tushare 美股财务指标接口us_fina_indicator 数据字典与实战调用指南【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading导读本文以 Vibe-Trading 仓库内 Tushare 技能文档 美股财务指标数据 为核心系统讲解us_fina_indicator接口的权限要求、5 个输入参数、69 个输出指标字段的完整含义并结合仓库源码给出可直接复制运行的 Python 调用示例、分页/循环取数策略以及面向量化研究与智能体数据管道的实战方案。读完本文你将能够独立完成美股上市公司财务指标收入、毛利、净利润、ROE、资产负债率、周转率等的抓取、字段裁剪、历史全量提取与入库。接口概述美股财务指标数据的定位与约束us_fina_indicator是 Tushare 提供的美股上市公司财务指标接口在 Tushare 技能说明 的数据接口列表中登记为 ID 393归类于「美股数据」专题。使用该接口前必须明确三点事实约束覆盖范围目前只覆盖主要美股和中概股并非全市场全量标的。请求限量为避免服务器压力现阶段每次请求最多返回 200 条记录可通过设置日期区间多次请求获取更多数据。历史深度当前接口按单只股票获取其历史数据单次请求最大返回 10000 行数据可循环提取。此外还需满足权限门槛需单独开通权限或账户积分达到 15000 积分具体以 Tushare 官方权限列表为准对应文档中的「权限列表」说明。这与仓库内 美股利润表、美股资产负债表 等姊妹接口的权限要求一致。输入参数详解五种查询维度名称类型必选描述ts_codestrY股票代码美股代码如 NVDA、AAPLperiodstrN报告期格式YYYYMMDD每个季度最后一天的日期如 20241231report_typestrN报告期类型Q1 一季报 / Q2 半年报 / Q3 三季报 / Q4 年报start_datestrN报告期开始时间格式YYYYMMDDend_datestrN报告结束时间格式YYYYMMDD其中ts_code为必填参数其余均为可选用于缩小查询窗口按单期查询使用period例如period20241231精确取 2024 年末报告期。按报告期类型查询使用report_type例如report_typeQ4提取历年所有年报数据。按时间区间查询组合start_date/end_date配合「每次最多 200 条」的限制可逐段拉取全历史。需要注意美股财年与自然年往往不一致。从数据样例可见 NVDA 的financial_date年结日为1-26、2-1等格式表示其财年截止日并非 12 月 31 日因此period应按财报对应的实际季度末日填写而不应机械使用自然年 3/6/9/12 月末。输出参数详解69 个指标的分类速查该接口返回的 DataFrame 包含 69 个字段可按业务含义分为六大类。下表完整收录全部字段1. 标识与报告属性基本信息字段类型描述ts_codestr股票代码end_datestr报告期ind_typestr报告类型Q1 一季报 / Q2 中报 / Q3 三季报 / Q4 年报security_name_abbrstr股票名称accounting_standardsstr会计准则如美国会计准则notice_datestr公告日期start_datestr报告期开始时间std_report_datestr标准报告期financial_datestr年结日currencystr币种date_typestr报告期类型单季报 / 年报 / 累计季报report_typestr报告类型如 2025/Q1、2024/FY、2024/Q62. 收入与盈利指标字段类型描述operate_incomefloat收入operate_income_yoyfloat收入增长gross_profitfloat毛利gross_profit_yoyfloat毛利增长parent_holder_netprofitfloat归母净利润parent_holder_netprofit_yoyfloat归母净利润增长basic_epsfloat基本每股收益diluted_epsfloat稀释每股收益gross_profit_ratiofloat销售毛利率net_profit_ratiofloat销售净利率total_incomefloat收入总额total_income_yoyfloat收入总额同比增长3. 运营效率与周转指标字段类型描述accounts_rece_trfloat应收账款周转率次inventory_trfloat存货周转率次total_assets_trfloat总资产周转率次accounts_rece_tdaysfloat应收账款周转天数inventory_tdaysfloat存货周转天数total_assets_tdaysfloat总资产周转天数4. 盈利质量与偿债杠杆指标字段类型描述roe_avgfloat净资产收益率roafloat总资产净利率current_ratiofloat流动比率倍speed_ratiofloat速动比率倍ocf_liqdebtfloat经营业务现金净额 / 流动负债debt_asset_ratiofloat资产负债率equity_ratiofloat产权比率roefloat净资产收益率debt_ratiofloat资产负债率5. 同比增速指标YoY字段类型描述basic_eps_yoyfloat基本每股收益同比增长gross_profit_ratio_yoyfloat毛利率同比增长%net_profit_ratio_yoyfloat净利率同比增长%roe_avg_yoyfloat平均净资产收益率同比增长%roa_yoyfloat总资产净利率同比增长%debt_asset_ratio_yoyfloat资产负债率同比增长%current_ratio_yoyfloat流动比率同比增长%speed_ratio_yoyfloat速动比率同比增长%roe_yoyfloat净资产收益率同比增长debt_ratio_yoyfloat资产负债率同比增长6. 金融行业专属指标该组字段主要面向银行、保险类金融股中概股中尤为常见普通非金融公司通常为空字段类型描述premium_incomefloat保费收入premium_income_yoyfloat保费收入同比payout_ratiofloat保费收入 / 赔付支出capitial_ratiofloat总资产周转率net_interest_incomefloat净利息收入net_interest_income_yoyfloat净利息收入增长loan_loss_provisionfloat贷款损失准备loan_loss_provision_yoyfloat贷款损失准备增长loan_depositfloat贷款 / 存款loan_equityfloat贷款 / 股东权益倍loan_assetsfloat贷款 / 总资产deposit_equityfloat存款 / 股东权益倍deposit_assetsfloat存款 / 总资产rolfloat贷款回报率rodfloat存款回报率currency_abbrstr币种basic_eps_csfloat基本每股收益basic_eps_cs_yoyfloat基本每股收益同比增长diluted_eps_csfloat稀释每股收益diluted_eps_cs_yoyfloat稀释每股收益增长说明basic_eps/diluted_eps与basic_eps_cs/diluted_eps_cs两组字段名称相似文档中均标注为「基本/稀释每股收益」实际应用时建议先比对同一股票两者差异再决定以哪组作为标准化口径。fields 参数按需裁剪输出列文档特别提示输出指标太多时可在接口fields参数中设定需要的指标。例如# 只取股票代码与每股收益等少量字段注意按实际输出参数名填写 df pro.us_fina_indicator(ts_codeNVDA, report_typeQ4, fieldsts_code,end_date,basic_eps,diluted_eps,roe,debt_asset_ratio)这一机制与 股票数据获取示例脚本 中stock_basic(fieldsts_code,symbol,name,area,industry,list_date)的用法一致可显著减少单次请求的响应体积降低对服务器与本地内存的压力。接口用法官方示例与增强版实战代码官方基础用法pro ts.pro_api() # 获取美股英伟达 NVDA 股票 2024 年度的财务指标数据 df pro.us_fina_indicator(ts_codeNVDA, period20241231) # 获取美股英伟达 NVDA 股票历年年报财务指标数据 df pro.us_fina_indicator(ts_codeNVDA, report_typeQ4)ts.pro_api()未传 token 时会自动读取本地配置仓库内的标准做法是显式传入 token。参照 股票数据获取示例脚本import os import tushare as ts from src.config.accessor import get_env_config # 优先读取仓库环境配置中的 tushare_token否则回退到 tushare 本地缓存的 token token get_env_config().data.tushare_token or ts.get_token() # 初始化 pro 接口实例 pro ts.pro_api(token)增强版循环提取完整历史推荐考虑到「每次请求最多返回 200 条」与「单次最大 10000 行」的双重限制推荐按年度切片循环提取再统一拼接import tushare as ts pro ts.pro_api() def fetch_us_fina_history(ts_code: str, start_year: int, end_year: int) - pd.DataFrame: 按年份分片提取单只美股全量财务指标历史。 美股财年与自然年错位因此使用 start_date/end_date 年份窗口 年内分片双重保险。 import pandas as pd frames [] for year in range(start_year, end_year 1): df pro.us_fina_indicator( ts_codets_code, start_datef{year}0101, end_datef{year}1231, ) if df is not None and not df.empty: frames.append(df) return pd.concat(frames, ignore_indexTrue).drop_duplicates() # 提取 NVDA 近五年财务指标历史 history fetch_us_fina_history(NVDA, 2021, 2025) print(history.shape)该写法同时规避了两类边界问题财年跨自然年导致period错位、以及超过单次限量导致数据被截断。若单年内记录仍可能超过 200 条可进一步将切片粒度缩小到季度按 0331 / 0630 / 0930 / 1231 分段。数据样例解读从 NVDA 返回值理解美股财年语义文档给出的数据样例以英伟达 NVDA 为例直观展示了美股财务数据与 A 股的差异ts_codeend_dateind_typesecurity_name_abbraccounting_standardsfinancial_datecurrencydate_typereport_typeoperate_incomeoperate_income_yoyNVDA20250427Q1英伟达美国会计准则2-1美元单季报2025/Q14.4062e1069.1829NVDA20250126Q4英伟达美国会计准则1-26美元年报2024/FY1.30497e11114.2034NVDA20241027Q3英伟达美国会计准则1-26美元累计季报2024/Q99.1166e10134.8489NVDA20240128Q4英伟达美国会计准则1-28美元年报2023/FY6.0922e10125.8545关键解读点财年错位NVDA 的financial_date落在 1 月下旬至 2 月初如1-26、2-1其 2024 财年报告期end_date为 20250126说明美股公司财年截止日由公司自行定义不能按自然年对齐。三种 date_type单季报如 2025/Q1、年报如 2024/FY、累计季报如 2024/Q6、2024/Q9。累计季报是 YTD 口径report_type中Q6表示上半年累计、Q9表示前三季度累计在计算同比与环比时必须先统一口径。金额单位operate_income采用科学计数法如1.304970e11即美元计价横向比较时应换算为统一货币。在 Vibe-Trading 中的接入与数据管道落地Token 配置与前置检查仓库通过环境变量统一管理 Tushare 凭据对应字段定义在 环境变量配置tushare_token: str Field(aliasTUSHARE_TOKEN, default)启动前可通过设置环境变量完成配置对应 SKILL.md 的快速上手说明export TUSHARE_TOKENyour_token仓库的 preflight 启动检查 会在初始化阶段校验TUSHARE_TOKEN是否已配置、tushare库是否可导入未通过时给出提示确保数据管道在运行前即暴露配置问题。同时tushare 兜底工具 展示了仓库在实际取数路径中如何读取该 token可作为接入参考。与美股财务数据系列的配合使用us_fina_indicator是指标层数据比率、增速要还原完整财务画像可与其姊妹接口配合美股利润表us_income按科目返回利润表明细如ind_name营业额可跨期提取单一科目美股资产负债表us_balancesheet按科目返回资产负债表明细美股现金流量表us_cashflow现金流量表明细美股基础信息us_basic获取美股代码清单、上市/退市日期可用于构建标的池后循环调用us_fina_indicator。四个接口共享同一套权限门槛与「按单只股票取历史」的数据形态可以封装为一个统一的「美股财务三表 指标」抓取器先us_basic拿标的池再对每只股票分别调用指标与三表接口按(ts_code, end_date)为主键入库即可支撑盈利能力、偿债能力、运营效率三类因子的量化研究。面向智能体的技能化封装在 Vibe-Trading 的 Agent 体系中Tushare 以skill形式挂载见 Tushare 技能说明其description明确声明覆盖股票、基金、期货、数字货币行情及公司财务、基金经理等基本面数据并通过标准化 API 统一对外服务。这意味着us_fina_indicator不只是一个 Python 函数而是 Agent 可直接感知和调用的数据能力入口研究型任务需要美股财务指标时Agent 依据 SKILL.md 中的接口清单ID 393定位到本文档按输入参数构造调用即可在对话链路中完成「按代码取指标 → 裁剪字段 → 返回 DataFrame」的闭环。常见问题与避坑清单积分不足接口需单独开通权限或 15000 积分否则会报权限错误务必先在官方数据工具中验证 token 与积分状态文档注明可用官方数据工具调试查看数据。200 条上限批量提取多只股票或多个报告期时按日期切片多次请求避免一次请求被截断。财年错位美股end_date不一定落在自然季度末按period精确取值前先用us_basic或financial_date字段确认财年结构。口径混用单季报 / 累计季报 / 年报三套口径不可直接比较计算同比需对齐report_type如 2024/Q6 对 2023/Q6。字段冗余非金融公司可主动用fields剔除保费收入、净利息收入等金融专属字段减小响应体积。去重入库循环提取后建议按(ts_code, end_date)去重防止跨年切片边界产生重复记录。通过上述参数组合、循环策略与字段裁剪技巧即可在 Vibe-Trading 中稳定、完整地获取美股上市公司财务指标数据为跨市场基本面研究提供数据底座。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考