Stock Earnings (investing.com) - Actor Documentation

Overview

The Stock Earnings (investing.com) actor is a specialized web scraper designed to fetch comprehensive earnings data for publicly traded stocks from Investing.com. This actor provides historical earnings information including actual vs. forecasted earnings per share (EPS), revenue data, surprise percentages, and price change metrics.

Features

• Comprehensive Earnings Data: Retrieves historical earnings records with actual and forecasted metrics
• Multi-Country Support: Supports 45+ countries and major stock exchanges worldwide
• Financial Metrics: Includes EPS, revenue, surprise percentages, and price change data
• Historical Analysis: Provides multiple quarters/years of earnings history
• Summary Statistics: Calculates average surprise rates and positive surprise counts
• JSON Output: Clean, structured data format for easy integration

Input Parameters

Required Parameters

Parameter	Type	Description	Example
stockSymbol	string	Stock ticker symbol (1-10 characters)	"AAPL", "MSFT", "BBVA"

Optional Parameters

Parameter	Type	Description	Default
country	string	Country where the stock is listed	"united states"

Supported Countries

The actor supports stocks from 45+ countries including:

Major Markets:

• United States
• United Kingdom
• Germany
• France
• Japan
• China
• Canada
• Australia

European Markets:

• Spain, Italy, Netherlands, Belgium, Portugal
• Austria, Switzerland, Norway, Sweden, Denmark, Finland
• Poland, Czech Republic, Hungary, Greece, Turkey, Russia

Asian Markets:

• South Korea, India, Malaysia, Singapore, Thailand
• Indonesia, Philippines, Vietnam, Taiwan, Hong Kong

Other Markets:

• Brazil, Mexico, Argentina, Chile, Colombia, Peru
• South Africa, Israel, Saudi Arabia, UAE, New Zealand

Output Data Structure

The actor returns an array of earnings records, each containing:

[
  {
    "currencyId": 12,
    "date": "2025-07-23T00:00:00.000Z",
    "epsActual": 0.52,
    "epsForecast": 0.61,
    "epsSurprisePercent": -14.75,
    "priceChangePercent": -14.12,
    "reportMonth": 6,
    "reportYear": 2025,
    "revenueActual": 25500000000,
    "revenueForecast": 24330000000,
    "revenueSurprisePercent": 4.81
  }
]

Field Descriptions

Field	Type	Description
currencyId	number	Currency identifier for the stock
date	string	Earnings announcement date (ISO format)
epsActual	number/null	Actual earnings per share reported
epsForecast	number	Forecasted earnings per share
epsSurprisePercent	number/null	EPS surprise percentage (actual vs forecast)
priceChangePercent	number/null	Stock price change percentage after earnings
reportMonth	number	Month of the reporting period (1-12)
reportYear	number	Year of the reporting period
revenueActual	number/null	Actual revenue reported
revenueForecast	number	Forecasted revenue
revenueSurprisePercent	number/null	Revenue surprise percentage

Usage Examples

Basic Usage

{
  "stockSymbol": "AAPL"
}

With Country Specification

{
  "stockSymbol": "BBVA",
  "country": "spain"
}

Multiple Examples

{
  "stockSymbol": "MSFT",
  "country": "united states"
}

Summary Data

The actor also generates a comprehensive summary stored in the key-value store:

{
  "stock": "AAPL",
  "country": "united states",
  "stock_symbol": "AAPL",
  "has_data": true,
  "retrieved_at": "2025-07-08T10:30:00.000Z",
  "total_records": 10,
  "latest_earnings_date": "2025-07-23T00:00:00.000Z",
  "latest_report_quarter": 6,
  "latest_report_year": 2025,
  "latest_eps_actual": 0.52,
  "latest_eps_forecast": 0.61,
  "latest_eps_surprise_percent": -14.75,
  "latest_revenue_actual": 25500000000,
  "latest_revenue_forecast": 24330000000,
  "latest_revenue_surprise_percent": 4.81,
  "latest_price_change_percent": -14.12,
  "avg_eps_surprise_percent": -2.35,
  "positive_eps_surprises": 4,
  "avg_revenue_surprise_percent": 1.23,
  "positive_revenue_surprises": 6
}

Error Handling

The actor includes comprehensive error handling for:

• Validation Errors: Invalid stock symbols or parameters
• IO Errors: Network connectivity issues
• Runtime Errors: Unexpected processing errors
• Connection Errors: Failed requests to Investing.com
• File Not Found Errors: Missing resources

Performance Considerations

• Rate Limiting: Respects Investing.com's rate limits
• Efficient Processing: Optimized for bulk data retrieval
• Memory Management: Handles large datasets efficiently
• Retry Logic: Built-in retry mechanism for failed requests

Integration Tips

1. Data Analysis: Use the summary statistics for quick insights
2. Historical Trends: Analyze surprise percentages over time
3. Comparative Analysis: Compare earnings across different stocks
4. Alert Systems: Monitor for earnings surprises
5. Financial Modeling: Use actual vs. forecast data for model validation

Limitations

• Data availability depends on Investing.com's coverage
• Historical data depth may vary by stock and country
• Some fields may be null for upcoming earnings (forecasts only)
• Currency conversion not performed (use currencyId for reference)

Support

If you have any questions or encounter any issues, please consult the Apify documentation or reach out to us through one of the following channels:

• Verify input parameters match the schema requirements
• Check the Apify platform documentation
• Review the actor logs for detailed error messages

• Telegram: @pintoflow
• Apify Platform: You can also contact us directly through this platform.

---