Us cashflow

查询美股现金流量表（长表 EAV）

接口说明

项目	说明
接口名称	对外接口-查询美股现金流量表
匹配键	us-cashflow
外部接口	GET /api/v1/market/data/us/us-cashflow
请求方式	GET
适用场景	查询美股上市公司现金流量表（经营/投资/筹资活动现金流净额、折旧摊销、资本支出等），按财年 + 报告期组合查询。数据来源 ClickHouse basedata.usstk_cashflow。

请求参数

参数名	类型	是否必填	描述	取值示例	备注
stock_code	string	是	美股代码（纯代码，不带后缀）	NVDA	必填
period	int	否	财年（fiscal year）	2024	匹配 stmt_year，非自然年
report_type	string	否	报告期类型	Q4	Q1/Q2/Q3/Q4/H1（半年报），大小写不敏感
start_date	int	否	报告期下界（含）	20240101	YYYYMMDD
end_date	int	否	报告期上界（含）	20241231	YYYYMMDD
page	int	否	页码	1	默认 1
page_size	int	否	每页报告期数	50	默认 50，最大 500

模式	必填参数	说明
单股财年单期	stock_code + period + report_type	最常用
单股全部历史	stock_code	全部报告期，按 end_date 倒序
单股日期区间	stock_code + start_date + end_date	按报告期范围

执行方式

# NVDA 2024 财年年报现金流量表
python scripts/handler.py --stock_code NVDA --period 2024 --report_type Q4
# AAPL 2024 财年年报现金流量表
python scripts/handler.py --stock_code AAPL --period 2024 --report_type Q4
# NVDA 全部历史现金流量表
python scripts/handler.py --stock_code NVDA

响应结构（长表 EAV，每行一个科目）

{
  "items": [
    { "stock_code": "NVDA", "end_date": "2024-01-28", "ind_type": "Q4", "name": "英伟达",
      "ind_name": "net_operacashflow", "ind_value": "...", "report_type": "年报" },
    { "stock_code": "NVDA", "end_date": "2024-01-28", "ind_type": "Q4", "name": "英伟达",
      "ind_name": "net_investcashflow", "ind_value": "...", "report_type": "年报" }
  ],
  "total_pages": 1,
  "total_items": 2
}

字段说明（每行 EAV）

字段名	类型	说明
stock_code / end_date / ind_type / name / report_type	—	同 us-income
ind_name	string	科目名（英文），如 net_operacashflow
ind_value	string	科目值（字符串，投资/筹资常为负，带 -）

主要科目（ind_name）

类别	科目
经营	depr_amort 折旧摊销、working_cap_chg 营运资金变动、net_operacashflow 经营活动现金流净额
投资	capex 资本性支出、invest_purs 投资支付、net_investcashflow 投资活动现金流净额
筹资	stock_issue 发行股票、stock_repur 回购、dividend_paid 分红、net_finacashflow 筹资活动现金流净额
汇总	net_incr_cashequiva 现金净增加额、cashequiva_bp/cashequiva_ep 期初/期末现金

注意事项

• 长表 EAV、按报告期分页、Q4/Q3 返回累计 + 单季两套、美股财年非自然年：均同 us-income。
• 现金流科目较少（16 个），一个报告期约展开 1016 行；total_items 是报告期数。
• 数值为字符串；投资/筹资流出常为负；只输出非 0 科目。
• 错误处理：v1 层吞错成 HTTP 500 + "获取美股现金流量表无数据"（无原因）；查无数据返回 200 + 空 items。排查打 v0 /api/v0/us/us-cashflow。
• 覆盖主要美股与中概股，约 5000+ 只。