摘要
股息数据 API 应把现金或股票形式的分配转换为结构化记录，并能分别回答三个问题：发行人公告了什么、权益从哪一天发生变化、现金或股份何时交付。每条事件至少应尽量包含稳定的证券标识、分红类型、每股金额或送股比例、币种、宣告日、除息日、登记日、派息日、事件状态、来源时间和修订记录。
历史派息、未来分红日历、过去十二个月股息合计和股息率彼此相关，但不是同一种数据。股息率属于派生指标，其结果会随价格时点、统计窗口、特别分红处理方式以及税前或税后金额而变化。更稳妥的做法是选择能返回底层分红事件的接口，再由应用按照明确口径计算并标注指标。
一个有足够历史范围、市场覆盖、请求额度和适用许可的股票分红数据接口。
除息日、宣告日、股权登记日、派息日、金额、币种、频率、复权状态和收益率定义。
调用次数、标的数量、交易所、历史深度、延迟和商业用途都可能受限。
QVeris 帮助 Agent 发现和检查供应商支持的金融能力，但实际覆盖与条款仍由供应商决定。
股息数据 API 的使用场景
应先明确数据需要支持哪项决策，再确认免费额度能否覆盖目标证券、日期和更新频率。投资组合收入看板更关心已确认的派息日和币种；除息日历需要已公告的未来事件及其修订；总回报回测则需要按历史时点可知的事件、退市证券和可复现的复权口径。
历史分红与未来事件不是同一类数据
历史分红接口通常返回已经发生的记录，股息日历接口更关注已宣告或即将发生的事件，不能默认两者覆盖完全相同。
为什么日期字段必须分清
宣告日、除息日、股权登记日和派息日代表不同环节。能返回除息日的 API 不一定同时返回派息日。
普通分红、特别分红与股票股利必须明确分类
按季度重复发放的普通现金股息不能与一次性特别分红直接混算。股票股利使用股份比例而非现金金额，基金分配还可能包含收入分配、资本利得或资本返还。接口应保留供应商原始分类，并提供足够条款供业务建立自己的统一分类。
股息金额和股息率必须说明计算口径
应确认金额是否按每股计、属于税前还是扣缴后的净额、使用证券交易币种还是发行人派息币种，以及是否因后续拆股而调整。如果接口直接返回股息率，还必须说明它是过去十二个月、预期、指示性口径，还是把最近一次派息年化后的结果。
如何比较免费股票分红数据 API
| 检查项 | 为什么重要 | 验证方法 |
|---|---|---|
| 市场覆盖 | 是否仅美股，还是覆盖全球股票、ETF 或基金。 | 用两个不同市场的已知标的测试。 |
| 历史深度 | 免费历史分红数据范围可能短于付费方案。 | 明确指定起止日期请求。 |
| 字段 | 日期、金额、币种、频率、收益率和复权标记并不统一。 | 检查 JSON 键与空值处理。 |
| 派息口径 | 普通、特别、股票股利或基金分配；每股金额；税前或税后；现金金额或股份比例。 | 分别测试普通分红、特别分红和非现金分配。 |
| 生命周期与修订 | 公告状态、来源时间、金额或日期修订及取消。 | 重抓一笔已发生修订的事件并比较版本。 |
| 时点化证券身份 | 稳定 ID、代码有效期、退市证券、股份类别和上市地点。 | 查询一只更名或退市证券，并跨越变更日期核对。 |
| 免费限制 | 每日调用、积分、标的数量和商业权利决定能否使用。 | 同日核对价格页、文档和许可。 |
可以优先测试的股息 API
下面几家均公开了股息相关端点，但覆盖范围和免费权限都可能变化。可把这张表作为评估清单，正式选择前仍要在官方页面核实当前套餐、市场范围、历史深度和许可。
| 供应商 | 适合从哪里开始 | 更适合 | 重点核实 |
|---|---|---|---|
| Alpha Vantage | 为支持的股票提供有文档的股息函数，可通过常见 API 方式获取带日期的派息历史。 | 主要需要历史分红事件的 Notebook、收入看板和原型。 | 日期范围、证券与市场覆盖、原始或拆股调整金额、事件状态、未来事件及当前端点权限。 |
| Massive | 在股票数据平台内提供结构化分红参考端点，支持筛选、标识符、事件日期、现金金额和分页。 | 已经使用同一供应商行情，并希望把分红历史与证券参考数据连接的应用。 | 现金与调整后金额口径、频率标签、状态或更正字段、市场覆盖、套餐权限和再分发条款。 |
| Financial Modeling Prep | 在公司概况、价格、财报等接口之外提供分红历史和日历类数据。 | 希望在更广泛的公司数据结构中使用分红事件，并可能需要未来日历的产品。 | 当前端点与套餐、日历状态、公告日与除息日筛选、历史深度、来源出处和修订机制。 |
| 发行人或交易所公告 | 特定发行人或市场的一手事件公告与详细条款。 | 核验特别分红、股票股利、取消事件、币种或特殊支付条款。 | 发布时间、修订链、文档格式、自动化使用权、稳定标识符以及是否存在历史归档。 |
不要只因为接口直接返回“股息率”就选择它。如果供应商能可靠返回事件级金额和日期，应用可以透明地计算过去十二个月、预期或组合收入指标；反之，一个没有价格日期、派息窗口和特别股息政策的现成股息率很难验证。
股息率与收入日历计算实例
为什么同一只股票会有多个“正确”的股息率
假设某股票现价为 50 美元，过去十二个月支付了四次每股 0.40 美元的普通股息，并额外支付一次 1.00 美元特别股息。若过去十二个月股息率包含全部现金分配，则为 $(4 × 0.40 + 1.00) ÷ 50 = 5.2%$；若排除不可持续的特别股息，则为 3.2%。如果最近一次普通股息已提高到 0.50 美元，并预计继续按季度支付，预期股息率则为 $(4 × 0.50) ÷ 50 = 4.0%$。
这三个结果在算术上都可能正确，但回答的是不同问题。结果旁边必须保存统计窗口、纳入的分红类型、价格及其时间、币种、年化规则和税前或税后口径。发生拆股后，价格和股息序列必须采用一致的调整方式；只调整其中一边会制造虚假的股息率跳变。
除息日与派息日回答不同的组合问题
假设某笔股息在 3 月 1 日宣告，3 月 14 日除息，3 月 15 日登记，3 月 29 日支付。权益归属与价格行为主要关联除息日，预期现金流则应归入派息日。若收入日历在 3 月 14 日就记入现金，会提前确认；若到 3 月 29 日才发送除息提醒，又已经太晚。两种日期都要保留，并明确日历采用哪种模式。
用于投资组合收入看板
使用已确认的派息日、币种、每股金额、符合条件的持股数、预扣税口径和支付状态。预期现金与实际到账要分开保存，避免延迟或修订事件静默改写已实现收入。
用于未来除息日历
使用公告状态、除息日、宣告日、来源时间和修订时间。已公告事件要持续刷新直至完成或取消，并区分预计日期与发行人已经确认的日期。
用于总回报研究
使用时点一致的事件记录、退市证券、普通与特别分红分类，以及一套公开且固定的复权方法。更正金额正式公布之前，回测不能提前使用它。
用于 AI Agent
结果应返回事件类型、金额、币种、相关生命周期日期、状态、来源和修订时间。用户询问股息率时，还要说明价格日期、派息窗口、特别股息处理方式，以及指标属于历史还是预期口径。
测试股票分红数据接口的 JSON 响应
安全的 Python 请求方式
import requests
response = requests.get(
"https://provider.example/v1/dividends",
params={"symbol": "AAPL", "start_date": "2024-01-01"},
headers={"Authorization": "Bearer YOUR_API_KEY"},
timeout=20,
)
response.raise_for_status()
records = response.json()
这是供应商中立的示例，并非真实 QVeris 接口。请替换成所选供应商文档中的 URL 与鉴权方式，不要把 API Key 暴露在前端代码里。
入库前完成字段验证
- 确认状态码、分页、限流响应头和重试规则，并弄清日期筛选依据的是公告日、除息日还是派息日。
- 在字段标准化或计算股息率前，保存原始响应、供应商事件 ID、来源时间和采集时间。
- 验证金额单位、币种、分红类型、税前或税后口径，以及历史金额是否因后续拆股而调整。
- 应依据稳定的事件链去重，不能只看证券代码和除息日，因为两笔不同分配可能共用同一个除息日。
- 定期复查已公告的未来事件和近期完成的派息，因为日期、金额与状态都可能变化。
- 测试样本应包含普通分红、特别分红、拆股调整后的历史、取消事件、派息日为空以及证券更名等情况。
用 QVeris 发现股息数据能力
QVeris 是能力路由层，并非每条股息记录的原始发布方。打开 QVeris 工具详情即可查看匹配的股息能力；调用前还应检查市场覆盖、证券标识参数、事件日期筛选、返回字段、分页方式和供应商限制。结果仍需经过来源级校验和许可控制，因为名称相近的股息工具也可能覆盖不同生命周期阶段，并采用不同复权口径。
如需更宽泛的供应商选择，可继续阅读 QVeris 的金融数据 API 对比和金融数据 MCP Server 指南。
FAQ
有，但免费访问可能是长期免费层、试用、延迟数据、受限历史或仅限非商业用途。采用前应测试目标市场，并核对最新条款。
最好包含证券与事件 ID、分红类型、金额或股份比例、币种、宣告日、除息日、登记日、派息日、状态、来源时间和修订时间。
按照文档在服务端携带凭据调用接口，验证状态与分页，解析响应，并在入库前检查日期、单位、币种、空值和事件身份。
部分股息日历或公司行动接口会返回已公告的未来事件。由于发行人可能修订或取消事件，这些数据应视为初步信息并定期刷新。
供应商可能采用不同价格、派息窗口、年化方式、特别分红处理、币种或税前税后金额。需要一致口径时，应基于底层事件自行重算。
这取决于分析目的。应保留原始公告金额和复权输入，再生成单独设有版本的派生序列，以便复现所选口径。