Tracking Earnings Events Programmatically with SteadyAPI

Earnings reports represent the most significant sources of idiosyncratic risk and opportunity in the financial markets. For algorithmic traders and risk managers, knowing the precise date and time of a report is essential to manage gap risk and implied volatility exposure. Missing an earnings date can lead to unintended exposure to binary market events, while correctly anticipating them allows for strategies such as volatility arbitrage and pre-earnings momentum trading.

To access this endpoint, you must obtain an API key:
Get your API key

The Endpoint

The GET /v2/markets/calendar/earnings endpoint allows developers to programmatically retrieve past, present, and upcoming earnings data. This endpoint provides essential metadata including the date of the report, the time of day (before market open or after market close), consensus estimates, and historical surprise data.

Documentation:
Calendar Events - Earnings

Detailed Parameter Analysis

This endpoint offers flexible filtering options to suit different data requirements, whether you are building a broad market scanner or tracking a specific portfolio.

• ticker
  Use this parameter when you need data for a specific asset (e.g., ticker=AZO). This is ideal for updating a watchlist or validating the event timeline for a specific position.
• days
  This integer parameter filters for upcoming earnings within a rolling window (e.g., days=7). This is useful for generating Week Ahead dashboards to identify potential volatility catalysts.
• start_date and end_date
  Use these string parameters (Format: YYYY-MM-DD) to define a strict historical or future window. This is necessary for backtesting strategies around earnings seasons.
• page
  Pagination control for responses that return large datasets, such as broad date range queries.

Python Example

The following Python script demonstrates how to fetch the earnings profile for AutoZone (AZO). Ensure you replace {YOUR_AUTH_KEY} with your actual API token.

import requests
import json

# Define the endpoint URL
url = "https://api.steadyapi.com/v2/markets/calendar/earnings"

# Set up query parameters
# We are querying for a specific ticker to get its upcoming earnings profile
params = {
    'ticker': 'AZO' 
}

# Set authentication headers
headers = {
    'Authorization': 'Bearer {YOUR_AUTH_KEY}',
    'Content-Type': 'application/json'
}

try:
    # Make the GET request
    response = requests.request("GET", url, headers=headers, params=params)
    
    # Check for successful response
    if response.status_code == 200:
        data = response.json()
        print(json.dumps(data, indent=2))
    else:
        print(f"Error: {response.status_code} - {response.text}")
        
except Exception as e:
    print(f"An error occurred: {str(e)}")

Understanding the Response

The API returns a JSON object containing a list of earnings events matching your query.

{
  "body": [
    {
      "symbol": "AZO",
      "symbolName": "Autozone",
      "nextEarningsDate": "09/24/24",
      "lastPrice": "3,042.74",
      "timeCode": "Before Open",
      "estimatedEarnings": "$53.59",
      "lastReportedEarnings": "N/A",
      "lastEarningsSurprisePercent": "N/A"
    }
  ]
}

Key Fields Analysis

• nextEarningsDate
  The specific date the company is scheduled to report. Algorithms should use this to close positions or initiate hedges prior to this date.
• timeCode
  Indicates timing relative to market hours. Before Open implies the stock will gap immediately at the open of the reporting date. After Close implies the volatility event will occur after the session ends on that date.
• estimatedEarnings
  The market consensus EPS forecast. Significant deviations from this number in the actual report often drive the post-earnings price move.
• lastEarningsSurprisePercent
  Historical data showing how much the company exceeded or missed estimates in the previous quarter. This metric helps gauge the likelihood of a future surprise.

Practical Use Cases

Automated Earnings Calendars

Financial portals and brokerage interfaces can use the days parameter to auto-populate a Weekly Earnings Watchlist, highlighting high-profile tickers reporting in the next 5 to 7 days.

Volatility Arbitrage Strategies

Quantitative traders use this data to identify when Implied Volatility (IV) is likely to be highest (just before the earnings announcement) and when it will experience IV Crush (immediately after the announcement). By filtering via the timeCode field, traders can time entry and exit points for options strategies like Iron Condors or Straddles with high precision.

Learn more or explore other endpoints:
SteadyAPI Stock and Options Data API