如图所示，美股的财报每天都会有日历跟踪，假设我有个信号触发列表，我希望列表中新增一列，来获取当前的财报发布时间，已发布的给出 高于预期还是低于预期的判断，还没发布的给出时间 比如5 12 盘前或5 12 盘后， 主要是需要这个数据接口 来集成到我的信号触发程序中， 哪些开源接口可用?

Key findings

• 首选：OpenBB

  • 适合 Python 程序直接集成，因为文档给出了 Python 调用示例。
  • obb.equity.calendar.earnings() 可获取历史和未来公司财报发布日历。
  • 支持按日期区间查询，例如 start_date、end_date。
  • 文档说明该接口包含 EPS 和 revenue 数据。

• 适合判断“高于/低于预期”：AInvest

  • Earnings calendar 接口返回 ticker、period_name、eps_actual、eps_forecast、eps_surprise 等字段。
  • 这些字段可以直接用于判断 EPS 实际值相对预期值的结果。
    • eps_actual > eps_forecast：高于预期
    • eps_actual < eps_forecast：低于预期
    • eps_actual == eps_forecast：符合预期

• 适合做已发布后的 surprise 检查：Bigdata

  • Earnings Surprises 接口返回 reporting_date、eps_actual、eps_estimated、revenue_actual 等字段。
  • 它更适合用来查询“最新财报是否超预期”，而不是单独作为未来财报日历源，因为该接口文档描述的是 latest surprise 数据，并展示了 actual / estimated 字段。

• 其他可评估接口

  • API Ninjas 的 Earnings Calendar API 提供过去财报结果和未来财报日期，并覆盖主要公司。
  • StockFit 文档提到有 upcoming earnings calendar、单个 symbol 的 earnings date lookup、earnings snapshot、EPS history 等能力。

Confirmed facts

What remains inference

你要的最终字段可以设计成类似这样：

ticker | signal_time | earnings_status | earnings_date | earnings_session | eps_actual | eps_estimate | surprise_result

其中：

• earnings_status

  • reported
  • upcoming
  • unknown

• surprise_result

  • beat：实际 EPS 高于预期
  • miss：实际 EPS 低于预期
  • inline：实际 EPS 等于预期
  • pending：还未发布

这个判断逻辑本身是推导出来的，因为 AInvest 和 Bigdata 的字段中有实际 EPS 与预期 EPS，可用于比较。

What the evidence suggests

如果你是把它接到“信号触发列表”里，我建议按这个优先级接入：

1. 先接 OpenBB

   • 适合 Python，因为文档提供了 Python 调用示例。
   • 能查未来和历史 earnings calendar。
   • 如果你已有 Python 信号程序，它很可能是集成成本较低的起点。

2. 再接 AInvest 或 Bigdata 补 surprise 判断

   • AInvest 的 eps_actual、eps_forecast、eps_surprise 字段更贴近“高于/低于预期”的需求。
   • Bigdata 的 Earnings Surprises 更像是专门用于已发布财报后的 surprise 查询，因为其文档展示了 latest surprise 请求以及 eps_actual、eps_estimated 等字段。

3. 把 API Ninjas / StockFit 作为备选

   • API Ninjas 可查过去 earnings results 和 upcoming earning dates。
   • StockFit 覆盖 upcoming calendar、symbol earnings date lookup、earnings snapshot、EPS history 等 earnings 场景。

Conflicting evidence or uncertainty

目前证据不足以确认这些接口是否稳定返回你特别需要的：

• “5-12 盘前”
• “5-12 盘后”
• “before market open / after market close”
• 具体发布时间，例如美东时间几点

现有证据只明确提到 earnings calendar、upcoming dates、historical releases、EPS、revenue、actual、forecast / estimated、surprise 等字段。 因此，如果“盘前 / 盘后”是硬需求，需要你实际调用接口或查看完整字段文档确认；仅凭现有证据不能保证。

Open questions

• 你是否只需要 EPS 高于/低于预期，还是也需要 营收高于/低于预期？
• 你的“信号触发列表”是 Python DataFrame、数据库表，还是 TradingView / Excel / 自研系统？
• “盘前 / 盘后”是否是强制字段？如果是，OpenBB、AInvest、API Ninjas、StockFit 都需要实际测试返回字段，因为现有证据没有明确确认这些接口稳定返回盘前 / 盘后字段。
• 你是否接受付费 API？现有证据中，AInvest 示例使用 Authorization: Bearer <token>，但仅凭这些证据不能判断各接口的免费额度或授权限制。

Sources worth trusting most

• OpenBB 文档：最适合作为 Python 集成入口，因为它直接给出 from openbb import obb 和 obb.equity.calendar.earnings() 示例，并说明可查询历史和未来财报发布。
• AInvest API 文档：字段最贴近“actual vs forecast vs surprise”的判断需求，示例返回包含 eps_actual、eps_forecast、eps_surprise。
• Bigdata API 文档：适合补充已发布财报后的 surprise 数据，因为它返回 eps_actual、eps_estimated 和 reporting_date。
• API Ninjas / StockFit 文档：可以作为备选数据源，但需要进一步验证字段完整性、权限和费用；现有证据只确认它们覆盖 earnings results、upcoming dates、upcoming calendar、symbol lookup、snapshot、EPS history 等能力。

Recommended next step

建议你先用 OpenBB + AInvest / Bigdata 做一个两段式数据管线：

1. 用 OpenBB 拉取未来和历史财报日历。
2. 对已经发布的 ticker，再用 AInvest 或 Bigdata 查询 eps_actual 与 eps_forecast / eps_estimated。
3. 在你的信号列表中新增一列，例如：

def classify_earnings(row):
    if row["eps_actual"] is None:
        return f'{row["earnings_date"]} 待发布'

    if row["eps_actual"] > row["eps_estimate"]:
        return "高于预期"
    elif row["eps_actual"] < row["eps_estimate"]:
        return "低于预期"
    else:
        return "符合预期"

4. 如果你必须显示“盘前 / 盘后”，先针对这几个接口各抽样调用 20–50 个 ticker，确认返回字段里是否存在 session、time、release_time、bmo/amc 等字段；现有证据不能确认这一点。

Summary

最推荐从 OpenBB 开始，因为它有 Python 调用示例，能查历史和未来 earnings calendar，并包含 EPS 与营收数据。 如果重点是“财报发布后自动判断高于预期还是低于预期”，则应补充接入 AInvest 或 Bigdata，因为它们明确返回实际 EPS 与预期 EPS 相关字段。 但“盘前 / 盘后”字段目前证据不足，不能保证这些接口一定支持，需要实际调用或查完整字段文档确认。