Earnings

Premium

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

Endpoint

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

Method

GET

Request Example

HTTP

GET https://api.marketdata.app/v1/stocks/earnings/AAPL/

NodeJS

app.js

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

Python

app.py

import requests

url = "https://api.marketdata.app/v1/stocks/earnings/AAPL/"
response = requests.request("GET", url)

print(response.text)

Go

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)
	}
}

Response Example

{
  "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

Required

• symbol string

  The company's ticker symbol.

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.

Response Attributes

Success

• 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.

No Data

• s string

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

Error

• s string

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

• errmsg string An error message.