---
title: Earnings tg p
sidebar_position: 4
tags:
  - "API: Premium"
---

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

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

## Endpoint
```
https://api.marketdata.app/v1/stocks/earnings/{symbol}/
```

#### Method
```
GET
```
## Request Example

<Tabs>
<TabItem value="HTTP" label="HTTP" default>

**GET** [https://api.marketdata.app/v1/stocks/earnings/AAPL/](https://api.marketdata.app/v1/stocks/earnings/AAPL/)

</TabItem>
<TabItem value="NodeJS" label="NodeJS">

```js title="app.js"
fetch("https://api.marketdata.app/v1/stocks/earnings/AAPL/")
  .then((res) => {
    console.log(res);
  })
  .catch((err) => {
    console.log(err);
  });
```

</TabItem>
<TabItem value="Python" label="Python">

```python title="app.py"
from marketdata.client import MarketDataClient

client = MarketDataClient()
earnings = client.stocks.earnings("AAPL")
print(earnings)
```

</TabItem>
<TabItem value="Go" label="Go">

```go title="stockEarnings.go"

import (
  "fmt"

  api "github.com/MarketDataApp/sdk-go"
)

func ExampleStockEarningsRequest() {
	earningsReports, err := StockEarnings().Symbol("AAPL").Get()
	if err != nil {
		fmt.Print(err)
		return
	}

	for _, report := range earningsReports {
		fmt.Println(report)
	}
}
```
</TabItem>
</Tabs>

## Response Example

```json
{
  "s": "ok",
  "symbol": ["AAPL"],
  "fiscalYear": [2023],
  "fiscalQuarter": [1],
  "date": [1672462800],
  "reportDate": [1675314000],
  "reportTime": ["before market open"],
  "currency": ["USD"],
  "reportedEPS": [1.88],
  "estimatedEPS": [1.94],
  "surpriseEPS": [-0.06],
  "surpriseEPSpct": [-3.0928],
  "updated": [1701690000]
}
```

## Request Parameters

<Tabs>
<TabItem value="required" label="Required" default>

- **symbol** `string`

  The company's ticker symbol.

</TabItem>
<TabItem value="Optional" label="Optional">

- **from** `date`

  The earliest earnings report to include in the output. If you use countback, `from` is not required. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

- **to** `date`

  The latest earnings report to include in the output. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

- **countback** `number`

  Countback will fetch a specific number of earnings reports before `to`. If you use `from`, countback is not required.

- **date** `date`

  Retrieve a specific earnings report by date. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

- **report** `datekey`

  Retrieve a specific earnings report by date and quarter. Example: `2023-Q4`. This allows you to retrieve a 4th quarter value without knowing the company's specific fiscal year.

</TabItem>
</Tabs>

## Response Attributes

<Tabs>
<TabItem value="Success" label="Success" default>

- **s** `string`

  Will always be `ok` when there is data for the symbol requested.

- **symbol** `array[string]`

  The symbol of the stock.

- **fiscalYear** `array[number]`

  The fiscal year of the earnings report. This may not always align with the calendar year.

- **fiscalQuarter** `array[number]`

  The fiscal quarter of the earnings report. This may not always align with the calendar quarter.

- **date** `array[date]`

  The last calendar day that corresponds to this earnings report.

- **reportDate** `array[date]`

  The date the earnings report was released or is projected to be released.

- **reportTime** `array[string]`

  The value will be either `before market open`, `after market close`, or `during market hours`.

- **currency** `array[string]`

  The currency of the earnings report.

- **reportedEPS** `array[number]`

  The earnings per share reported by the company. Earnings reported are typically non-GAAP unless the company does not report non-GAAP earnings.

  :::tip

  GAAP (Generally Accepted Accounting Principles) earnings per share (EPS) count all financial activities except for discontinued operations and major changes in accounting methods. Non-GAAP EPS, on the other hand, typically doesn't include losses or devaluation of assets, and often leaves out irregular expenses like significant restructuring costs, large tax or legal charges, especially for companies not in the financial sector.
  :::

- **estimatedEPS** `array[number]`

  The average consensus estimate by Wall Street analysts.

- **surpriseEPS** `array[number]`

  The difference (in earnings per share) between the estimated earnings per share and the reported earnings per share.

- **surpriseEPSpct** `array[number]`

  The difference in percentage terms between the estimated EPS and the reported EPS, expressed as a decimal. For example, if the estimated EPS is 1.00 and the reported EPS is 1.20, the surpriseEPSpct would be 0.20 (or 20%).

- **updated** `array[date]`

  The date/time the earnings data for this ticker was last updated.

</TabItem>
<TabItem value="NoData" label="No Data">

- **s** `string`

  Status will be `no_data` if no earnings data can be found for the symbol.

</TabItem>
<TabItem value="Error" label="Error">

- **s** `string`

  Status will be `error` if the request produces an error response.

- **errmsg** `string`
  An error message.

</TabItem>
</Tabs>

## Usage Information

### Data Availability

This endpoint provides historical earnings data and future earnings calendar information. Earnings data is fundamental data that is updated after companies report their quarterly and annual results.

| User Type | Exchange Entitlement | Data Type |
|-----------|---------------------|------------|
| All Users | Not Required | Historical/Fundamental |

### Pricing

The cost of using the earnings API endpoint is 1 credit per API call.

| Data Type     | Cost Basis                | Credits Required per Unit |
|--------------------|---------------------------|---------------------------|
| Earnings Data    | Per API call         | 1 credit                  |