企业官网建设流程全解析

Vibe-Trading 美股基本面数据实战：用 Tushare us_balancesheet 接口获取美股资产负债表

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading

导读

本文以 Vibe-Trading 仓库内置的 Tushare 数据源技能文档（美股资产负债表）为核心，系统讲解 Tushareus_balancesheet接口的权限要求、输入输出参数、调用方式与返回数据形态，并结合仓库中同系列美股财务接口（利润表、现金流量表、财务指标）与财报分析技能，说明如何在美股研究场景中把资产负债表数据用于财务质量评估与量化因子构建。读完本文，你将掌握单只美股资产负债表情数据的完整提取链路、字段语义、分批循环拉取技巧，以及将科目数据与财报分析方法论结合的基本范式。

接口总览：us_balancesheet 是什么

us_balancesheet是 Tushare 提供的美股上市公司资产负债表数据接口，用于获取主要美股与中概股的资产负债表科目数据。在 Vibe-Trading 仓库中，该接口文档被收录于 agent/src/skills/tushare/references/美股数据/ 目录，与美股日线行情、复权因子、利润表、现金流量表、财务指标等接口文档并列，共同构成该技能的美股数据能力面。

该接口的关键定位如下：

• 覆盖范围：目前只覆盖主要美股和中概股（如 NVDA、AAPL 等大型上市公司），并非全市场；
• 数据粒度：按单只股票返回其全部历史报告期数据，支持按报告期类型、日期区间、科目名过滤；
• 返回规模：单次请求最大返回 10000 行数据，可循环提取全部历史；
• 权限门槛：需单独开通权限或账户拥有 15000 积分，具体权限分级以 Tushare 官方权限列表为准。

从仓库的技能列表（agent/src/skills/tushare/SKILL.md）可以看到，us_balancesheet对应 ID 395，与其同族的美股财务接口还包括：

三张报表（资产负债表、利润表、现金流量表）加上财务指标接口，正好构成美股基本面的完整数据闭环，可与仓库中 agent/src/skills/financial-statement/SKILL.md 的"三表解读"方法论直接配套使用。

环境准备与权限要求

1. 安装 Tushare 并配置 Token

根据 agent/src/skills/tushare/SKILL.md 的快速上手说明，使用该接口前需要完成三步准备：

# 1. 安装 tushare（推荐 Python 3.7+，可从清华 PyPI 镜像安装） pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple # 2. 注册 Tushare 账户并获取 token，配置为环境变量 export TUSHARE_TOKEN=your_token

仓库中的示例脚本 agent/src/skills/tushare/scripts/stock_data_example.py 展示了 Vibe-Trading 项目内的标准初始化方式——优先从项目配置读取 token，再回退到 tushare 本地缓存的 token：

import tushare as ts from src.config.accessor import get_env_config token = get_env_config().data.tushare_token or ts.get_token() pro = ts.pro_api(token)

初始化pro接口实例后，即可调用us_balancesheet。

2. 权限说明

原文档明确标注：该接口需单独开权限或有 15000 积分。这一点与同族的us_income、us_cashflow完全一致，而与us_basic（美股列表，120 积分可试用、5000 积分有正式权限）不同——三张美股报表接口的权限门槛明显更高，实测调用前请先确认账户积分或权限状态，否则会收到权限不足的报错。

输入参数详解

us_balancesheet共支持 5 个输入参数，其中仅ts_code为必填：

几个实用要点：

• ts_code是唯一必选参数，且按单只股票维度取数，不支持一次传入多只股票；
• period与start_date/end_date的区别：前者精确指定某个报告期（如20241231表示 2024 年年报报告期），后者用于拉取一个时间区间内的多个报告期；
• report_type的取值语义：Q1 对应一季报、Q2 对应半年报（中报）、Q3 对应三季报、Q4 对应年报。注意原文档样例中，report_type='Q4'返回的ind_type为Q4、report_type列显示为"年报"，两列含义有细微差异；
• ind_name支持按科目名精确过滤，例如只取"应收帐款"一个科目的历年数据，非常适合做单科目的时间序列分析。

输出字段说明

接口返回的是 pandas DataFrame，包含 7 个输出字段：

最重要的结构特征：该接口是"长表"（long format）而非"宽表"。每一行代表"某只股票在某报告期下的某一个财务科目及金额"，同一报告期的全部资产负债表科目分布在多行中。这与 A 股balancesheet接口的"一列一科目"宽表结构截然不同，做数据处理时需注意：

• 想得到"某报告期所有科目"的宽表，需对ind_name做pivot透视；
• 想绘制"某科目随时间的变动曲线"，直接按ind_name过滤即可；
• ind_value为 float 型，样例中以科学计数法展示（如1.252540e+11表示 1252.54 亿美元）。

接口用法与代码示例

原文档给出两个最典型的调用示例，直接可用于实战：

import tushare as ts pro = ts.pro_api() # 获取美股英伟达 NVDA 股票 Q4（年报）的资产负债表数据 df = pro.us_balancesheet(ts_code='NVDA', report_type='Q4') # 获取美股英伟达 NVDA 股票历年应收帐款指标数据 df = pro.us_balancesheet(ts_code='NVDA', ind_name='应收帐款')

基于前面梳理的参数语义，可以进一步扩展出以下高频调用模式：

# 1. 获取指定报告期的资产负债表（如 2024 年年报） df = pro.us_balancesheet(ts_code='NVDA', period='20241231') # 2. 获取一个时间区间内的全部报告期 df = pro.us_balancesheet(ts_code='NVDA', start_date='20200101', end_date='20241231') # 3. 按报告期类型 + 科目双重过滤（如历年三季报的存货） df = pro.us_balancesheet(ts_code='NVDA', report_type='Q3', ind_name='存货') # 4. 循环分批提取全部历史（单次上限 10000 行） all_parts = [] start, end = '20000101', '20241231' step_start = start while step_start <= end: part = pro.us_balancesheet(ts_code='NVDA', start_date=step_start, end_date=end) if part is None or part.empty: break all_parts.append(part) # 依据返回数据的 end_date 最大者推进窗口，避免重复请求 last_end = part['end_date'].max() step_start = f"{int(last_end[:4]) + 1}0101" df_all = pd.concat(all_parts, ignore_index=True)

说明：单次请求最大返回 10000 行，超出后需要以报告期窗口推进的方式循环提取（原文档"可循环提取"即指此意）。上面第 4 个示例给出了按年份推进窗口的循环骨架，实际使用时可根据返回的最大end_date动态推进，保证不重不漏。

数据样例解读

以原文档提供的 NVDA 资产负债表样例为参照（end_date=20250427，Q1）：

ts_code end_date ind_type name ind_name ind_value report_type 0 NVDA 20250427 Q1 英伟达 负债及股东权益合计 1.252540e+11 一季报 1 NVDA 20250427 Q1 英伟达 股东权益合计 8.384300e+10 一季报 2 NVDA 20250427 Q1 英伟达 归属于母公司股东权益 8.384300e+10 一季报 3 NVDA 20250427 Q1 英伟达 其他综合收益 1.860000e+08 一季报 4 NVDA 20250427 Q1 英伟达 股本溢价 1.147500e+10 一季报 ... ... ... ... ... ... ... ... 2459 NVDA 20060129 Q4 英伟达 预付款项(流动) 2.438700e+07 年报 2460 NVDA 20060129 Q4 英伟达 递延所得税资产(流动) 2.682000e+06 年报 2461 NVDA 20060129 Q4 英伟达 存货 2.548700e+08 年报 2462 NVDA 20060129 Q4 英伟达 应收账款 3.181860e+08 年报 2463 NVDA 20060129 Q4 英伟达 现金及现金等价物 5.517560e+08 年报

样例揭示的信息值得注意：

1. 历史深度：NVDA 单只股票的资产负债表数据从 2006 年延伸到 2025 年，跨度近 20 年、累计超过 2400 行，充分体现了"按单只股票获取其历史数据"的能力；
2. 科目中文化：ind_name使用中文科目名（如"应收账款""存货""现金及现金等价物"），与美股的英文原始科目做了本地化映射，便于中文研究者直接使用；
3. 单季报 vs 累计值：从ind_type与report_type的组合可以看出，同一报告期的科目值可能是单季值或累计值，做同比、环比分析时需留意字段语义；
4. 金额单位：ind_value为原始数值（美元），从样例看 NVDA 2025Q1 负债及股东权益合计约 1252.54 亿美元，与实际体量吻合，可作为金额口径的参照。

三张报表联动：构建美股基本面分析闭环

1. 与同族接口的横向对照

us_balancesheet的参数体系与 美股利润表（us_income）、美股现金流量表（us_cashflow）完全一致：同为 5 个输入参数（ts_code必填）、同为 7 列长表输出结构、同为单次 10000 行上限。这意味着掌握了资产负债表接口的调用范式，就能无缝迁移到另外两张报表，学习成本极低。

三个接口的典型组合用法：

# 同一报告期下，拉取 NVDA 的资产负债表 + 利润表 + 现金流量表 bs = pro.us_balancesheet(ts_code='NVDA', period='20241231') is_ = pro.us_income(ts_code='NVDA', period='20241231') cf = pro.us_cashflow(ts_code='NVDA', period='20241231')

而 美股财务指标数据（us_fina_indicator）则是宽表结构，直接给出roe_avg、roa、current_ratio、speed_ratio、debt_asset_ratio、gross_profit_ratio等几十个预计算指标，并标注了accounting_standards（如"美国会计准则"US GAAP）与currency字段，适合作为报表科目数据的交叉验证来源。

2. 结合财报分析技能的实战路径

Vibe-Trading 仓库内置了 agent/src/skills/financial-statement/SKILL.md（财报三表深度解读技能），其中对资产负债表的使用提出了明确的关注点，可直接应用于us_balancesheet取到的数据：

• 资产端重点科目：货币资金（是否受限、是否"存贷双高"）、应收账款（增速是否超过营收）、存货（是否积压）、商誉（并购溢价与减值风险）、在建工程（是否长期不转固）；
• 负债端重点科目：有息负债（短期借款 + 长期借款 + 应付债券）、应付账款（对上游议价权）、预收/合同负债（对下游议价权）；
• 关键比率口径：资产负债率 = 负债/资产（健康区间 40%-60%，非金融企业）、流动比率 = 流动资产/流动负债（1.5-2.5）、速动比率 = (流动资产-存货)/流动负债（>1.0）。

对应的取数与计算示例：

import pandas as pd # 拉取 NVDA 历年年报资产负债表 bs = pro.us_balancesheet(ts_code='NVDA', report_type='Q4') # 透视出关键科目 pivot = bs.pivot_table( index='end_date', columns='ind_name', values='ind_value', aggfunc='first' ).reset_index() # 计算资产负债率（单位：美元，保持一致） if {'总资产', '负债合计'}.issubset(pivot.columns): pivot['资产负债率'] = pivot['负债合计'] / pivot['总资产'] # 计算流动比率 if {'流动资产合计', '流动负债合计'}.issubset(pivot.columns): pivot['流动比率'] = pivot['流动资产合计'] / pivot['流动负债合计'] print(pivot[['end_date', '现金及现金等价物', '应收账款', '存货', '资产负债率']].tail())

技能文档同时强调，美股使用 US GAAP 会计准则，与 A 股的中国会计准则、港股/欧股的 IFRS 存在科目口径差异，做跨市场横向比较前必须做口径调整，这与us_fina_indicator返回的accounting_standards字段形成印证。

3. 量化研究中的典型用法

从源码与技能体系推断，us_balancesheet在量化场景中至少有三种典型应用：

• 财务健康度因子：用资产负债率、流动比率等指标构造选股因子，作为美股多因子模型的基本面维度输入；
• 盈利质量交叉验证：将资产负债表中的应收、存货变动与利润表的营收、现金流量表的经营现金流结合，识别"应收暴增""存贷双高"等盈利质量红旗（对应 financial-statement 技能 中 12 个造假红旗指标的检测方法）；
• 历史财务序列分析：利用该接口近 20 年的历史数据，构建科目时间序列，支撑长周期财务趋势与财务危机预警研究。

注意事项与边界

1. 覆盖范围有限：接口只覆盖主要美股和中概股，中小市值美股可能查不到数据，使用前建议先通过 美股基础信息（us_basic）确认目标代码存在；
2. 权限门槛较高：15000 积分或单独开通权限是硬性前置条件，与us_basic等低权限接口不同；
3. 长表结构需透视：返回的是科目-金额长表，进行横截面或面板分析时需要pivot_table转换；
4. 单次 10000 行上限：单只股票多年份全科目数据容易触及上限，需按报告期窗口循环提取；
5. 金额与会计口径：ind_value为原始美元数值，科目名为中文本地化映射，跨市场比较需注意 US GAAP 与 IFRS/中国会计准则的差异；
6. 报告类型语义：report_type参数（Q1-Q4）与返回列中的ind_type、report_type字段含义并不完全等同，分析时建议以返回字段为准。

总结

us_balancesheet是 Vibe-Trading Tushare 技能中美股基本面数据体系的核心接口之一。它以"单股、长表、全历史"的形态提供美股上市公司的资产负债表科目数据，与us_income、us_cashflow、us_fina_indicator共同构成覆盖"资产-利润-现金流-指标"的完整取数矩阵。通过本文梳理的参数语义、调用范式、长表透视方法与循环提取骨架，你可以直接在 Vibe-Trading 项目中接入该接口，并结合 financial-statement 技能 的科目关注点与比率口径，将原始科目数据转化为可用的财务质量评估与量化因子，为美股研究提供扎实的数据底座。

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading