# Earnings (PHP SDK)

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

> [!NOTE]
> **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()`. |

> [!WARNING]
> **HTML Not Yet Available**
>
> `Format::HTML` is included for forward compatibility, but HTML responses are not currently implemented by the Market Data API.

<a name="earnings"></a>
## earnings

```php
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](https://www.marketdata.app/docs/sdk/php/parameters), optional)

  Universal parameters for customizing the output format. See [Parameters](https://www.marketdata.app/docs/sdk/php/parameters) for details.

### Returns

- `Earnings`

  An Earnings response object containing the earnings data.

### Example (Recent Earnings)

```php
<?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
<?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
<?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
<?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();
```

<a name="Earning"></a>
## Earning

```php
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.

<a name="Earnings"></a>
## Earnings

```php
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.