Skip to main content

Earnings

Get historical earnings-per-share data and the upcoming earnings calendar for a stock, one report per fiscal quarter.

Premium Endpoint

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

Making Requests​

Both call styles live on the Stocks service (client.Stocks). Use GetEarnings for the simplest call, or Earnings when you also need the raw response and rate-limit metadata.

MethodReturnDescription
GetEarnings(symbol, opts...)([]Earning, error)Convenience wrapper; uses context.Background() and discards the response metadata.
Earnings(ctx, symbol, opts...)([]Earning, *response.Response, error)Context-aware; also returns the raw response + rate-limit metadata.

Earnings​

func (s *Service) Earnings(ctx context.Context, symbol string, opts ...EarningsOption) ([]Earning, *response.Response, error)
func (s *Service) GetEarnings(symbol string, opts ...EarningsOption) ([]Earning, error)

Fetch earnings reports for one symbol. With no options the API returns its default set of recent and upcoming reports.

Parameters​

  • ctx (context.Context) — controls cancellation and deadlines (context method only).
  • symbol (string) — the stock ticker symbol, e.g. "AAPL". Required; an empty string returns a validation error without making a request.
  • Options (stocks.EarningsOption):
    • stocks.WithEarningsWindow(w DateWindow) — set the reporting date range as a single DateWindow value. Build the window with any of the shared date-window constructors, for example stocks.OnDate(d), stocks.Between(from, to), or stocks.LastN(4).

Returns​

  • []Earning — earnings reports, one per fiscal quarter.
  • *response.Response — raw response + rate-limit metadata (context method only).
  • error — non-nil on request/validation failure.

Notes​

  • EPS fields on the returned Earning values are pointers (*float64) and are nil when the API reports no value, such as for earnings not yet reported. This distinguishes a missing value from a true $0.00.
  • Only the calendar date of each time.Time in a window is used; the time-of-day and zone are ignored.
  • If the API responds with 404 because no data is available, Earnings returns a nil slice, a nil error, and a non-nil *response.Response whose NoData field is true.
package main

import (
	"fmt"
	"log"

	"github.com/MarketDataApp/sdk-go/v2/marketdata"
)

func main() {
	client, err := marketdata.NewClient(marketdata.WithToken("YOUR_TOKEN"))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	earnings, err := client.Stocks.GetEarnings("AAPL")
	if err != nil {
		log.Fatal(err)
	}

	for _, e := range earnings {
		reported := "n/a"
		if e.ReportedEPS != nil {
			reported = fmt.Sprintf("$%.2f", *e.ReportedEPS)
		}
		fmt.Printf("FY%d Q%d  report %s  EPS %s\n",
			e.FiscalYear, e.FiscalQuarter, e.ReportDate.Format("2006-01-02"), reported)
	}
}

Output​

FY2024 Q1  report 2024-01-25  EPS $2.18
FY2024 Q2  report 2024-04-25  EPS n/a

Date Windows​

stocks.WithEarningsWindow takes a DateWindow — the same sealed-union value used by Candles and News. Build one with exactly one constructor:

ConstructorSelectsAPI parameters
stocks.OnDate(d)a single calendar daydate=d
stocks.Between(from, to)an explicit closed range (inclusive)from=from&to=to
stocks.Since(from)everything from a day onwardfrom=from
stocks.Until(to)up to and including a dayto=to
stocks.LastN(n)the n most recent reportscountback=n
stocks.LastNUntil(n, to)the n reports ending at a daycountback=n&to=to

Earning​

type Earning struct {
	Symbol             string    `json:"symbol"`        // Stock ticker symbol
	FiscalYear         int       `json:"fiscalYear"`    // Fiscal year of the report
	FiscalQuarter      int       `json:"fiscalQuarter"` // Fiscal quarter (1-4)
	Date               time.Time `json:"date"`          // Last calendar day of the fiscal period
	ReportDate         time.Time `json:"reportDate"`    // When earnings were / will be reported
	ReportTime         string    `json:"reportTime"`    // When during the day (before/after market, during hours)
	Currency           string    `json:"currency"`      // Currency of the report (may be empty for future earnings)
	ReportedEPS        *float64  `json:"reportedEPS"`   // Actual reported EPS (nil for future earnings)
	EstimatedEPS       *float64  `json:"estimatedEPS"`  // Consensus analyst estimate
	SurpriseEPS        *float64  `json:"surpriseEPS"`   // Difference between reported and estimated
	SurpriseEPSPercent *float64  `json:"surpriseEPSpct"` // Surprise as a percentage
	Updated            time.Time `json:"updated"`       // When this earnings data was last updated
}

Represents a single earnings report, one per fiscal quarter. Timestamps are normalized to US Eastern time.

Fields​

  • Symbol — the stock ticker symbol.
  • FiscalYear / FiscalQuarter — the fiscal year and quarter (1-4) of the report.
  • Date — the last calendar day of the fiscal period.
  • ReportDate — the date the earnings were or will be reported.
  • ReportTime — when during the day the report is/was released (before market, after market, or during hours).
  • Currency — the currency of the report; may be empty for future earnings.
  • ReportedEPS — the actual reported EPS; nil for earnings not yet reported.
  • EstimatedEPS — the consensus analyst estimate; nil when unavailable.
  • SurpriseEPS — the difference between reported and estimated EPS; nil when unavailable.
  • SurpriseEPSPercent — the surprise as a percentage (JSON alias surpriseEPSpct); nil when unavailable.
  • Updated — when this data was last updated.

Helper Methods​

  • String() string — a one-line summary of the report (EPS fields render as n/a when nil).