Earnings

Get historical earnings per share data or a future earnings calendar for a stock.

Premium Endpoint

The earnings endpoint requires a premium subscription. Free and trial accounts cannot access this data.

Making Requests

Use the earnings() method on the stocks resource to fetch earnings data:

Output Format	Return Type	Description
JSON	Earnings	Returns an Earnings object containing earnings report data (default).
CSV	Earnings	Returns an Earnings object with CSV data accessible via getCsv().
HTML	Earnings	Returns an Earnings object with HTML data accessible via getHtml().

HTML Not Yet Available

Format::HTML is included for forward compatibility, but HTML responses are not currently implemented by the Market Data API.

earnings

public function earnings(
    string $symbol,
    ?string $from = null,
    ?string $to = null,
    ?int $countback = null,
    ?string $date = null,
    ?Parameters $parameters = null
): Earnings

Get historical earnings per share data or a future earnings calendar for a stock.

Parameters

• symbol (string)

  The stock ticker symbol (e.g., "AAPL").

• from (string, optional)

  The earliest earnings report to include. If omitted without countback, returns recent and upcoming earnings. Accepted formats: ISO 8601, Unix timestamp.

• to (string, optional)

  The latest earnings report to include. Accepted formats: ISO 8601, Unix timestamp.

• countback (int, optional)

  Number of earnings reports to return before to. Use instead of from.

• date (string, optional)

  Retrieve a specific earnings report by date. Accepted formats: ISO 8601, Unix timestamp.

• parameters (Parameters, optional)

  Universal parameters for customizing the output format. See Parameters for details.

Returns

• Earnings

  An Earnings response object containing the earnings data.

Example (Recent Earnings)

<?php

use MarketDataApp\Client;

$client = new Client();

// Get recent and upcoming earnings for AAPL
$earnings = $client->stocks->earnings('AAPL');

foreach ($earnings->earnings as $report) {
    echo "Date: " . $report->report_date->format('Y-m-d') . "\n";
    echo "Fiscal Year: " . $report->fiscal_year . " Q" . $report->fiscal_quarter . "\n";
    echo "EPS Estimate: $" . $report->estimated_eps . "\n";
    echo "EPS Actual: $" . ($report->reported_eps ?? 'N/A') . "\n";
    echo "Surprise: " . ($report->surprise_eps ?? 'N/A') . "\n\n";
}

Output

Date: 2024-01-25
Fiscal Year: 2024 Q1
EPS Estimate: $2.10
EPS Actual: $2.18
Surprise: 0.08

Date: 2024-04-25
Fiscal Year: 2024 Q2
EPS Estimate: $1.50
EPS Actual: N/A
Surprise: N/A

Example (Historical Range)

<?php

use MarketDataApp\Client;

$client = new Client();

// Get historical earnings for a date range
$earnings = $client->stocks->earnings(
    symbol: 'AAPL',
    from: '2023-01-01',
    to: '2023-12-31'
);

echo "AAPL Earnings for 2023:\n";
echo "========================\n";

foreach ($earnings->earnings as $report) {
    $surprise = $report->surprise_eps ?? 0;
    $surpriseIndicator = $surprise > 0 ? '↑' : ($surprise < 0 ? '↓' : '-');

    echo sprintf(
        "Q%d %d: EPS $%.2f (Est: $%.2f) %s\n",
        $report->fiscal_quarter,
        $report->fiscal_year,
        $report->reported_eps ?? 0,
        $report->estimated_eps ?? 0,
        $surpriseIndicator
    );
}

Example (Last N Reports)

<?php

use MarketDataApp\Client;

$client = new Client();

// Get the last 4 earnings reports
$earnings = $client->stocks->earnings(
    symbol: 'AAPL',
    to: 'today',
    countback: 4
);

echo "Last 4 Quarterly Earnings:\n";

foreach ($earnings->earnings as $report) {
    echo sprintf(
        "%s: Q%d FY%d - $%.2f EPS\n",
        $report->report_date->format('Y-m-d'),
        $report->fiscal_quarter,
        $report->fiscal_year,
        $report->reported_eps ?? 0
    );
}

Example (CSV)

<?php

use MarketDataApp\Client;
use MarketDataApp\Endpoints\Requests\Parameters;
use MarketDataApp\Enums\Format;

$client = new Client();

// Get earnings as CSV
$earnings = $client->stocks->earnings(
    symbol: 'AAPL',
    from: '2023-01-01',
    parameters: new Parameters(format: Format::CSV)
);

echo $earnings->getCsv();

Earning

class Earning
{
    public string $symbol;
    public int $fiscal_year;
    public int $fiscal_quarter;
    public Carbon $date;
    public Carbon $report_date;
    public string $report_time;
    public ?string $currency;
    public ?float $reported_eps;
    public ?float $estimated_eps;
    public ?float $surprise_eps;
    public ?float $surprise_eps_pct;
    public Carbon $updated;
}

Represents a single earnings report.

Properties

• symbol (string): The stock ticker symbol.
• fiscal_year (int): The fiscal year of the earnings report.
• fiscal_quarter (int): The fiscal quarter (1-4).
• date (Carbon): The last calendar day that corresponds to this earnings report (period end date).
• report_date (Carbon): The date the earnings report was released or is projected to be released.
• report_time (string): Time of day for the report ("before market open", "after market close", or "during market hours").
• currency (string|null): The currency of the earnings report.
• reported_eps (float|null): Actual reported EPS. Typically non-GAAP unless the company does not report non-GAAP earnings. Null for future reports.
• estimated_eps (float|null): The average consensus EPS estimate by Wall Street analysts.
• surprise_eps (float|null): The difference between reported EPS and estimated EPS.
• surprise_eps_pct (float|null): The percentage difference between reported and estimated EPS.
• updated (Carbon): The date/time the earnings data was last updated.

Earnings

class Earnings extends ResponseBase
{
    public string $status;
    public array $earnings;
}

Represents a collection of earnings reports.

Properties

• status (string): Response status ("ok" or "no_data").
• earnings (Earning[]): Array of Earning objects.

Methods

• getCsv(): Returns the raw CSV data (when using Format::CSV).
• getHtml(): Returns the raw HTML data (when using Format::HTML).
• isJson(): Returns true if the response contains JSON data.