Como integrar calendário de resultados (earnings) no seu sistema de sinais de trading

Para integrar eventos de divulgação de resultados (earnings) em um sistema de sinais ou trading quantitativo, você basicamente precisa de três tipos de dados:

• data do resultado
• horário de divulgação (pré‑mercado ou pós‑mercado)
• comparação entre resultado real e estimativa (EPS real vs estimado)

Existem várias APIs e bibliotecas que fornecem esse tipo de informação. Algumas são mais adequadas para integração direta em Python, enquanto outras são APIs REST usadas por dashboards ou sistemas automatizados.

1. OpenBB (boa opção para integração em Python)

Se o seu sistema de sinais já roda em Python, OpenBB costuma ser uma das opções mais simples de integrar.

O endpoint:

obb.equity.calendar.earnings()

permite obter calendários de resultados passados e futuros, incluindo dados de EPS e receita.

Exemplo básico:

from openbb import obb

# calendário de resultados
obb.equity.calendar.earnings()

# intervalo específico
obb.equity.calendar.earnings(start_date="2024-02-01", end_date="2024-02-07")

O OpenBB também permite selecionar diferentes provedores de dados (por exemplo fmp, nasdaq, seeking_alpha).

Isso facilita usar o calendário de earnings como fonte principal para seu sistema de triggers.

2. AInvest (útil para detectar beat ou miss)

A API da AInvest retorna campos prontos para comparar expectativas do mercado com o resultado real.

Exemplo de campos retornados:

• eps_actual
• eps_forecast
• eps_surprise
• revenue_actual
• revenue_forecast

Com isso é fácil classificar o resultado automaticamente:

• eps_actual > eps_forecast

  → superou expectativas (beat)

• eps_actual < eps_forecast

  → abaixo das expectativas (miss)

• eps_actual == eps_forecast

  → em linha

Esse tipo de dado é ideal para preencher a coluna de "resultado" na sua lista de sinais.

3. Bigdata Earnings Surprises (dados pós‑resultado)

Outra API focada em surpresas de resultados é a Bigdata Earnings Surprises API.

Ela fornece campos como:

• reporting_date
• eps_actual
• eps_estimated
• revenue_actual
• revenue_estimated
• eps_surprise_pct

Essa API é mais útil depois que o resultado já foi divulgado, para medir o tamanho da surpresa em relação ao consenso do mercado.

4. Outras APIs que podem servir como fonte de calendário

Além das anteriores, existem outros serviços que também disponibilizam calendários de resultados:

• API Ninjas Earnings Calendar – retorna resultados passados e datas futuras de divulgação.
• StockFit Earnings API – fornece calendário futuro, busca por ticker e histórico de EPS.
• Finnhub – oferece calendário de resultados com estimativas e resultados reais.
• Alpha Vantage – possui endpoint EARNINGS_CALENDAR para eventos futuros.

Essas APIs geralmente retornam os dados em JSON ou CSV, o que facilita integrar diretamente em pipelines de trading ou DataFrames.

Estrutura típica para integrar no seu sistema

Uma tabela comum para enriquecer sua lista de sinais pode ser algo assim:

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

Campos sugeridos:

• earnings_status

  • reported
  • upcoming
  • unknown

• surprise_result

  • beat
  • miss
  • inline
  • pending

Lógica simples de classificação:

if eps_actual > eps_estimate:
    result = "beat"
elif eps_actual < eps_estimate:
    result = "miss"
else:
    result = "inline"

Atenção ao horário da divulgação

Seu requisito de mostrar algo como:

• “12/05 pré‑mercado”
• “12/05 pós‑mercado”

depende do provedor de dados. Nem todos os endpoints confirmam claramente campos como:

• before market open

• after market close

• report_time

A documentação disponível apenas garante datas de divulgação e dados de EPS/receita, mas não confirma de forma consistente o campo de sessão (pré ou pós‑mercado).

Por isso, o ideal é testar algumas chamadas reais da API antes de integrar definitivamente.

Sugestão prática de arquitetura

Uma pipeline comum em sistemas quantitativos costuma ser:

1. OpenBB ou Finnhub → calendário de earnings (eventos futuros).
2. AInvest / Bigdata → resultado real vs estimado após divulgação.
3. Atualizar sua tabela de sinais com:
   • horário de divulgação
   • status (pendente ou divulgado)
   • beat/miss

Assim você consegue adicionar automaticamente uma coluna de contexto de resultados no seu sistema de trading.

Resumo

Para integrar dados de earnings em um programa de sinais:

• OpenBB é uma boa escolha para Python e calendário de resultados.
• AInvest fornece campos diretos para comparar EPS real e estimado.
• Bigdata pode complementar com métricas de surpresa após o resultado.
• APIs como API Ninjas, Finnhub ou StockFit também podem servir como fonte alternativa de calendário.

Combinando duas dessas fontes, normalmente já é possível montar um sistema automatizado que mostra data do earnings, horário aproximado e se o resultado superou ou ficou abaixo das expectativas.