Overview

The FinIQ Earnings API provides a precise historical record of corporate earnings announcements. It goes beyond simple "Actual vs. Estimated" numbers by including Smart Consensus estimates, precise Time of Day timestamps (BMO/AMC), and post-earnings price reaction data.

‍

Key Capabilities:

• History: 20+ Years.
• Coverage: 12,000+ Global Companies.
• Speed: <200ms latency from press release.
• Alpha Signals: Standardized Surprise %, 1-Day Price Reaction, Consensus Trend.

‍

1. Access Methods

‍

2. REST API: Earnings Endpoint

Endpoint: GET https://api.finiq.data/v1/earnings-surprises

‍

Request Parameters:

‍

Example Request (Python)

import requests

url = "https://api.finiq.data/v1/earnings-surprises"
params = {
    "api_token": "YOUR_KEY",
    "ticker": "NVDA",
    "date_from": "2023-01-01"
}

response = requests.get(url, params=params)
data = response.json()

‍

Response Structure (JSON)

{
  "ticker": "NVDA",
  "fiscal_period": "2024-Q4",
  "report_date": "2024-02-21",
  "time_of_day": "After-Market",
  "EPS": {
    "actual": 5.16,
    "consensus": 4.64,
    "surprise": 0.52,
    "surprise_percent": 11.21
  },
  "Revenue": {
    "actual": 22100000000,
    "consensus": 20620000000,
    "surprise_percent": 7.17
  },
  "Stock_Price": {
    "price_before": 674.72,
    "price_after": 785.38,
    "reaction_1d": 16.4
  }
}

‍

3. Data Dictionary (Key Metrics)

‍

4. Bulk Data Access (CSV)

Ideal for backtesting Post-Earnings Announcement Drift (PEAD) strategies.

‍

File Naming Convention: {Exchange}_Earnings_History_{Date}.csv

‍

CSV Columns:

Ticker, Period, ReportDate, TimeOfDay, EPS_Actual, EPS_Consensus, EPS_Surprise_P, Rev_Actual, Rev_Consensus, Rev_Surprise_P, Price_Reaction_1D

‍

How to Download:

1. Navigate to Data Export.
2. Select Earnings Package.
3. Choose Ticker Universe (e.g. "S&P 500").
4. Click Download ZIP.

‍

5. Vector Database Feed (RAG-Ready)

Exclusive to FinIQ.
‍This feed embeds the textual content of the Earnings Call Transcript and the Press Release.

‍

Sample Vector Output (Decoded):

"In the Q4 2023 earnings call, NVIDIA CFO Colette Kress attributed the 11% EPS beat primarily to 'unprecedented demand for Data Center GPUs,' specifically citing H100 shipments."

‍

Use Case:

‍Allows LLMs to answer qualitative questions:

• "Which companies missed earnings due to 'Supply Chain' issues this quarter?"
• "Summarize the CEO's tone regarding guidance for next year."

‍

6. Error Handling & Limits

• Rate Limits: Standard tiers allow 100 requests/second.
• Error Codes:
  • 400 Bad Request: Invalid Ticker.
  • 401 Unauthorized: Invalid API Key.
  • 404 Not Found: No earnings history found for ticker.
  • 429 Too Many Requests: Rate limit exceeded.

‍

7. Need Help?

• Developer Support: email dev-support@finiq.data
• Slack Community: Join our [Quant Developer Slack]
• Postman Collection: [Download Here]

‍