# Earnings (Python SDK)

Retrieve earnings data for any supported stock symbol.

## Making Requests

Use the `earnings()` method on the `stocks` resource to fetch earnings data. The method supports multiple output formats:

| Output Format | Return Type                                     | Description                                                                                                                               |
|---------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame`        | Returns a DataFrame with earnings data indexed by symbol (default).                                                                       |
| **INTERNAL**  | `StockEarnings` or `StockEarningsHumanReadable` | Returns a StockEarnings object. When `use_human_readable=True`, returns a StockEarningsHumanReadable object with capitalized field names. |
| **JSON**      | `dict`                                          | Returns the raw JSON response as a dictionary.                                                                                            |
| **CSV**       | `str`                                           | Writes CSV data to file and returns the filename string.                                                                                  |

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

```python
def earnings(
    symbol: str,
    *,
    report: str = None,
    date: str | datetime.datetime = None,
    from_date: str | datetime.datetime = None,
    to_date: str | datetime.datetime = None,
    countback: int = None,
    output_format: OutputFormat = OutputFormat.DATAFRAME,
    date_format: DateFormat = None,
    columns: list[str] = None,
    add_headers: bool = None,
    use_human_readable: bool = False,
    mode: Mode = None,
    filename: str | Path = None,
) -> StockEarnings | StockEarningsHumanReadable | dict | str | MarketDataClientErrorResult
```

Fetches earnings data for a stock symbol. The `symbol` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.

### Parameters

- `symbol` (str)

  The stock symbol for which to fetch earnings data.

- `report` (str, optional)

  Filter by report type (e.g., "annual", "quarterly").

- `date` (str | datetime.datetime, optional)

  Specific date for the earnings data.

- `from_date` (str | datetime.datetime, optional)

  Start date for the date range.

- `to_date` (str | datetime.datetime, optional)

  End date for the date range.

- `countback` (int, optional)

  Number of earnings reports to return, counting backwards from the `to_date`.

- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)

  The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)

  The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)

  Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)

  Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)

  Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)

  The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- `filename` (str | Path, optional)

  File path for CSV output (only used with `output_format=OutputFormat.CSV`).

### Returns

- `StockEarnings` | `StockEarningsHumanReadable` | `dict` | `str` | `MarketDataClientErrorResult`

  The earnings data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.

### Example (DataFrame)

```python
from marketdata import MarketDataClient

client = MarketDataClient()

# Get stock earnings as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.stocks.earnings("AAPL")
# or
df = client.stocks.earnings(symbol="AAPL")

print(df)
```

### Example (Internal)

```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get stock earnings as internal object
earnings = client.stocks.earnings("AAPL", output_format=OutputFormat.INTERNAL)

# Access earnings properties
print(f"Symbol: {earnings.symbol}")
print(f"Fiscal Year: {earnings.fiscalYear}")
print(f"Fiscal Quarter: {earnings.fiscalQuarter}")
print(f"Reported EPS: {earnings.reportedEPS}")
print(f"Estimated EPS: {earnings.estimatedEPS}")
```

### Example (JSON)

```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get stock earnings as JSON
earnings = client.stocks.earnings("AAPL", output_format=OutputFormat.JSON)

print(earnings)
```

### Example (CSV)

```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path

client = MarketDataClient()

# Get stock earnings as CSV
csv_file = client.stocks.earnings(
    "AAPL",
    output_format=OutputFormat.CSV,
    filename=Path("earnings.csv")
)

print(f"CSV file saved to: {csv_file}")
```

### Example (Human Readable)

```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get stock earnings in human-readable format
earnings = client.stocks.earnings(
    "AAPL",
    output_format=OutputFormat.INTERNAL,
    use_human_readable=True
)

# Access earnings properties
print(f"Symbol: {earnings.Symbol}")
print(f"Fiscal Year: {earnings.Fiscal_Year}")
print(f"Fiscal Quarter: {earnings.Fiscal_Quarter}")
print(f"Reported EPS: {earnings.Reported_EPS}")
print(f"Estimated EPS: {earnings.Estimated_EPS}")
print(f"Surprise EPS: {earnings.Surprise_EPS}")
```

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

```python
@dataclass
class StockEarnings:
    s: str
    symbol: list[str]
    fiscalYear: list[int]
    fiscalQuarter: list[int]
    date: list[datetime.datetime]
    reportDate: list[datetime.datetime]
    reportTime: list[str]
    currency: list[str]
    reportedEPS: list[float]
    estimatedEPS: list[float]
    surpriseEPS: list[float]
    surpriseEPSpct: list[float]
    updated: list[datetime.datetime]
```

StockEarnings represents earnings data for a stock, encapsulating fiscal year, quarter, and EPS information. All lists have the same length, allowing you to access earnings data by index.

### Properties

- `s` (str): Status indicator ("ok" for successful responses).
- `symbol` (list[str]): List of stock symbols.
- `fiscalYear` (list[int]): List of fiscal years.
- `fiscalQuarter` (list[int]): List of fiscal quarters.
- `date` (list[datetime.datetime]): List of earnings dates (automatically converted from timestamps).
- `reportDate` (list[datetime.datetime]): List of report dates (automatically converted from timestamps).
- `reportTime` (list[str]): List of report times.
- `currency` (list[str]): List of currencies.
- `reportedEPS` (list[float]): List of reported earnings per share.
- `estimatedEPS` (list[float]): List of estimated earnings per share.
- `surpriseEPS` (list[float]): List of surprise earnings per share (difference between reported and estimated).
- `surpriseEPSpct` (list[float]): List of surprise EPS percentages.
- `updated` (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).

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

```python
@dataclass
class StockEarningsHumanReadable:
    Symbol: list[str]
    Fiscal_Year: list[int]
    Fiscal_Quarter: list[int]
    Date: list[datetime.datetime]
    Report_Date: list[datetime.datetime]
    Report_Time: list[str]
    Currency: list[str]
    Reported_EPS: list[float]
    Estimated_EPS: list[float]
    Surprise_EPS: list[float]
    Surprise_EPS_Percent: list[float]
    Updated: list[datetime.datetime]
```

StockEarningsHumanReadable represents earnings data in human-readable format with capitalized field names and formatted values. All lists have the same length, allowing you to access earnings data by index.

### Properties

- `Symbol` (list[str]): List of stock symbols.
- `Fiscal_Year` (list[int]): List of fiscal years.
- `Fiscal_Quarter` (list[int]): List of fiscal quarters.
- `Date` (list[datetime.datetime]): List of earnings dates (automatically converted from timestamps).
- `Report_Date` (list[datetime.datetime]): List of report dates (automatically converted from timestamps).
- `Report_Time` (list[str]): List of report times.
- `Currency` (list[str]): List of currencies.
- `Reported_EPS` (list[float]): List of reported earnings per share.
- `Estimated_EPS` (list[float]): List of estimated earnings per share.
- `Surprise_EPS` (list[float]): List of surprise earnings per share (difference between reported and estimated).
- `Surprise_EPS_Percent` (list[float]): List of surprise EPS percentages.
- `Updated` (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).

### Notes

- Field names use capitalized format with underscores (e.g., `Fiscal_Year` instead of `fiscalYear`, `Reported_EPS` instead of `reportedEPS`).