Skip to main content

Earnings

Retrieve earnings data for any supported stock symbol.

Making Requests​

Use StockEarningsRequest to make requests to the endpoint using any of the three supported execution methods:

MethodExecutionReturn TypeDescription
GetDirect[]StockEarningsReportDirectly returns a slice of []StockEarningsReport, facilitating individual access to each earnings report.
PackedIntermediate*StockEarningsResponseReturns a packed *StockEarningsResponse object. Must be unpacked to access the []StockEarningsReport slice.
RawLow-level*resty.ResponseProvides the raw *resty.Response for maximum flexibility. Direct access to raw JSON or *http.Response.

StockEarningsRequest​

type StockEarningsRequest struct {
    // contains filtered or unexported fields
}

StockEarningsRequest represents a request to the /v1/stocks/earnings/ endpoint. It encapsulates parameters for symbol, report type, and date to be used in the request. This struct provides methods such as Report(), Symbol(), Date(), From(), To(), and Countback() to set these parameters respectively.

Generated By​

Setter Methods​

Execution Methods​

These methods are used to send the request in different formats or retrieve the data. They handle the actual communication with the API endpoint.

ser, err := StockEarnings().Symbol("AAPL").From("2022-01-01").To("2022-01-31").Get()
if err != nil {
	fmt.Print(err)
	return
}

for _, report := range ser {
	report.Updated = time.Time{}
	fmt.Println(report)
}

Output​

StockEarningsReport{Symbol: "AAPL", FiscalYear: 2022, FiscalQuarter: 1, Date: "2021-12-31", ReportDate: "2022-01-27", ReportTime: "after close", Currency: "USD", ReportedEPS: 2.100000, EstimatedEPS: 1.890000, SurpriseEPS: 0.210000, SurpriseEPSPct: 0.111100, Updated: "nil"}

StockEarnings​

func StockEarnings() *StockEarningsRequest

StockEarnings creates a new StockEarningsRequest with default parameters and associates it with the default client. This function initializes the request with default parameters for symbol, report type, and date, and sets the request path based on the predefined endpoints for stock earnings.

Returns​

  • *StockEarningsRequest

    A pointer to the newly created StockEarningsRequest with default parameters and associated client.

StockEarningsRequest Setter Methods​

Countback​

func (ser *StockEarningsRequest) Countback(q int) *StockEarningsRequest

Countback sets the countback parameter for the StockEarningsRequest. This method specifies the number of periods to return, counting backwards from the 'to' date.

Parameters​

  • int

    The number of periods to return.

Returns​

  • *StockEarningsRequest

    This method returns a pointer to the *StockEarningsRequest instance it was called on. This allows for method chaining.

Date​

func (ser *StockEarningsRequest) Date(q interface{}) *StockEarningsRequest

Date sets the date parameter for the StockEarningsRequest. This method is used to specify the date for which the stock earnings data is requested.

Parameters​

  • interface{}

    An interface{} representing the date to be set. It can be a string, a time.Time object, a Unix int, or any other type that the underlying dates package method can process.

Returns​

  • *StockEarningsRequest

    This method returns a pointer to the *StockEarningsRequest instance it was called on. This allows for method chaining.

From​

func (ser *StockEarningsRequest) From(q interface{}) *StockEarningsRequest

From sets the 'from' date parameter for the StockEarningsRequest. This method is used to specify the starting point of the date range for which the stock earnings data is requested.

Parameters​

  • interface{}

    An interface{} representing the date to be set. It can be a string, a time.Time object, a Unix int, or any other type that the underlying dates package method can process.

Returns​

  • *StockEarningsRequest

    This method returns a pointer to the *StockEarningsRequest instance it was called on. This allows for method chaining.

Report​

func (ser *StockEarningsRequest) Report(q string) *StockEarningsRequest

Report sets the report type parameter for the StockEarningsRequest. This method is used to specify which earnings report to be retrieved.

Parameters​

  • string

    A string representing which report to be returned.

Returns​

  • *StockEarningsRequest

    This method returns a pointer to the *StockEarningsRequest instance it was called on. This allows for method chaining.

Symbol​

func (ser *StockEarningsRequest) Symbol(q string) *StockEarningsRequest

Symbol sets the symbol parameter for the StockEarningsRequest. This method is used to specify the stock symbol for which earnings data is requested.

Parameters​

  • string

    A string representing the stock symbol to be set.

Returns​

  • *StockEarningsRequest

    This method returns a pointer to the *StockEarningsRequest instance it was called on. This allows for method chaining.

To​

func (ser *StockEarningsRequest) To(q interface{}) *StockEarningsRequest

To sets the 'to' date parameter for the StockEarningsRequest. This method is used to specify the ending point of the date range for which the stock earnings data is requested.

Parameters​

  • interface{}

    An interface{} representing the date to be set. It can be a string, a time.Time object, a Unix int, or any other type that the underlying dates package method can process.

Returns​

  • *StockEarningsRequest

    This method returns a pointer to the *StockEarningsRequest instance it was called on. This allows for method chaining.

StockEarningsRequest Execution Methods​

Get​

func (ser *StockEarningsRequest) Get() ([]models.StockEarningsReport, error)

Get sends the StockEarningsRequest, unpacks the StockEarningsResponse, and returns a slice of StockEarningsReport. It returns an error if the request or unpacking fails.

Returns​

  • []models.StockEarningsReport

    A slice of StockEarningsReport containing the unpacked earnings data from the response.

  • error

    An error object that indicates a failure in sending the request or unpacking the response.

Packed​

func (ser *StockEarningsRequest) Packed() (*models.StockEarningsResponse, error)

Packed sends the StockEarningsRequest and returns the StockEarningsResponse.

Returns​

  • *models.StockEarningsResponse

    A pointer to the StockEarningsResponse obtained from the request.

  • error

    An error object that indicates a failure in sending the request.

Raw​

func (ser *StockEarningsRequest) Raw() (*resty.Response, error)

Raw executes the StockEarningsRequest and returns the raw *resty.Response. The *resty.Response can be used to access the raw JSON or *http.Response directly.

Returns​

  • *resty.Response

    The raw response from the executed StockEarningsRequest.

  • error

    An error object if the StockEarningsRequest is nil, the MarketDataClient is nil, or if an error occurs during the request execution.

StockEarningsResponse​

type StockEarningsResponse struct {
    Symbol         []string   `json:"symbol"`         // Symbol represents the stock symbols.
    FiscalYear     []int64    `json:"fiscalYear"`     // FiscalYear represents the fiscal years of the earnings report.
    FiscalQuarter  []int64    `json:"fiscalQuarter"`  // FiscalQuarter represents the fiscal quarters of the earnings report.
    Date           []int64    `json:"date"`           // Date represents the earnings announcement dates in UNIX timestamp.
    ReportDate     []int64    `json:"reportDate"`     // ReportDate represents the report release dates in UNIX timestamp.
    ReportTime     []string   `json:"reportTime"`     // ReportTime represents the time of day the earnings were reported.
    Currency       []string   `json:"currency"`       // Currency represents the currency used in the earnings report.
    ReportedEPS    []*float64 `json:"reportedEPS"`    // ReportedEPS represents the actual earnings per share reported.
    EstimatedEPS   []*float64 `json:"estimatedEPS"`   // EstimatedEPS represents the consensus earnings per share estimate.
    SurpriseEPS    []*float64 `json:"surpriseEPS"`    // SurpriseEPS represents the difference between reported EPS and estimated EPS.
    SurpriseEPSpct []*float64 `json:"surpriseEPSpct"` // SurpriseEPSpct represents the percentage difference between reported and estimated EPS.
    Updated        []int64    `json:"updated"`        // Updated represents the last update time in UNIX timestamp.
}

StockEarningsResponse encapsulates the data received as a response to a stock earnings data request. It contains detailed information about stock earnings, including symbols, fiscal years, fiscal quarters, dates, report dates, report times, currencies, reported EPS, estimated EPS, surprise EPS, surprise EPS percentage, and last update times.

Generated By​

Methods​

Notes​

  • The dates in this struct are represented as UNIX timestamps.
  • EPS fields may be nil if the data is not available.

String​

func (ser *StockEarningsResponse) String() string

String generates a string representation of the StockEarningsResponse.

This method formats the StockEarningsResponse fields into a readable string, including handling nil values for EPS fields and empty values for fiscalYear and fiscalQuarter gracefully by displaying them as "nil" or "empty" respectively.

Returns​

  • `A string representation of the StockEarningsResponse.

Unpack​

func (ser *StockEarningsResponse) Unpack() ([]StockEarningsReport, error)

Unpack converts the StockEarningsResponse struct into a slice of StockEarningsReport structs.

This method iterates over the fields of a StockEarningsResponse struct, creating a StockEarningsReport struct for each symbol present in the response. It then populates the fields of each StockEarningsReport struct with the corresponding data from the StockEarningsResponse struct. The method handles the conversion of Unix timestamps to time.Time objects for the Date, ReportDate, and Updated fields. It also directly assigns pointer fields for ReportedEPS, EstimatedEPS, SurpriseEPS, and SurpriseEPSpct to handle potential nil values gracefully.

Returns​

  • []StockEarningsReport

    A slice of StockEarningsReport structs constructed from the StockEarningsResponse.

  • error

    An error if the unpacking process fails, nil otherwise.

StockEarningsReport​

type StockEarningsReport struct {
    Symbol         string    // Symbol represents the stock symbol.
    FiscalYear     int64     // FiscalYear represents the fiscal year of the earnings report.
    FiscalQuarter  int64     // FiscalQuarter represents the fiscal quarter of the earnings report.
    Date           time.Time // Date represents the earnings announcement date.
    ReportDate     time.Time // ReportDate represents the report release date.
    ReportTime     string    // ReportTime represents the time of day the earnings were reported.
    Currency       string    // Currency represents the currency used in the earnings report.
    ReportedEPS    *float64  // ReportedEPS represents the actual earnings per share reported.
    EstimatedEPS   *float64  // EstimatedEPS represents the consensus earnings per share estimate.
    SurpriseEPS    *float64  // SurpriseEPS represents the difference between reported EPS and estimated EPS.
    SurpriseEPSpct *float64  // SurpriseEPSpct represents the percentage difference between reported and estimated EPS.
    Updated        time.Time // Updated represents the last update time.
}

StockEarningsReport represents a single earnings report for a stock, encapsulating details such as the stock symbol, fiscal year, fiscal quarter, earnings date, report date and time, currency used in the report, reported EPS, estimated EPS, surprise EPS, surprise EPS percentage, and the last update time.

Generated By​

  • Unpack()

    Converts a StockEarningsResponse into a slice of StockEarningsReport structs.

Methods​

  • String() string

    Returns a string representation of the StockEarningsReport.

Notes​

  • The Date, ReportDate, and Updated fields are represented as time.Time objects, providing a standardized format for date and time.
  • EPS fields (ReportedEPS, EstimatedEPS, SurpriseEPS, SurpriseEPSpct) are pointers to float64, allowing for nil values to represent missing data.

String​

func (ser StockEarningsReport) String() string

String returns a string representation of the StockEarningsReport struct. This method is primarily used for logging or debugging purposes, allowing developers to easily view the contents of a StockEarningsReport instance in a human-readable format. The method formats various fields of the struct, including handling nil pointers for EPS values gracefully by displaying them as "nil".

Returns​

  • string

    A formatted string that represents the StockEarningsReport instance, including all its fields. Fields that are pointers to float64 (ReportedEPS, EstimatedEPS, SurpriseEPS, SurpriseEPSpct) are displayed as their dereferenced values if not nil, otherwise "nil".

Notes​

  • The Date, ReportDate, and Updated fields are formatted as "YYYY-MM-DD" for consistency and readability.
  • This method ensures that nil pointer fields do not cause a panic by checking their existence before dereferencing.