---
title: Earnings
sidebar_position: 5
---

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





Retrieve earnings data for any supported stock symbol.

## Making Requests

Use [StockEarningsRequest](<#StockEarningsRequest>) to make requests to the endpoint using any of the three supported execution methods:

| Method     | Execution     | Return Type                 | Description                                                                                                     |
|------------|---------------|-----------------------------|-----------------------------------------------------------------------------------------------------------------|
| **Get**    | Direct        | `[]StockEarningsReport`     | Directly returns a slice of `[]StockEarningsReport`, facilitating individual access to each earnings report.    |
| **Packed** | Intermediate  | `*StockEarningsResponse`    | Returns a packed `*StockEarningsResponse` object. Must be unpacked to access the `[]StockEarningsReport` slice. |
| **Raw**    | Low-level     | `*resty.Response`           | Provides the raw `*resty.Response` for maximum flexibility. Direct access to raw JSON or `*http.Response`.      |


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

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

StockEarningsRequest represents a request to the [/v1/stocks/earnings/](<https://www.marketdata.app/docs/api/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

- <a href="#StockEarnings">`StockEarnings() *StockEarningsRequest`</a>

  StockEarnings creates a new \*StockEarningsRequest and returns a pointer to the request allowing for method chaining.


#### Setter Methods

- <a href="#StockEarningsRequest.Report">`Report(q string) *StockEarningsRequest`</a>

  Sets the report type parameter for the request.

- <a href="#StockEarningsRequest.Symbol">`Symbol(q string) *StockEarningsRequest`</a>

  Sets the symbol parameter for the request.

- <a href="#StockEarningsRequest.Date">`Date(q interface{}) *StockEarningsRequest`</a>

  Sets the date parameter for the request.

- <a href="#StockEarningsRequest.From">`From(q interface{}) *StockEarningsRequest`</a>

  Sets the 'from' date parameter for the request.

- <a href="#StockEarningsRequest.To">`To(q interface{}) *StockEarningsRequest`</a>

  Sets the 'to' date parameter for the request.

- <a href="#StockEarningsRequest.Countback">`Countback(q int) *StockEarningsRequest`</a>

  Sets the countback parameter for the request.


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

- <a href="#StockEarningsRequest.Get">`Get() ([]StockEarningsReport, error)`</a>

  Sends the request, unpacks the response, and returns the data in a user\-friendly format.

- <a href="#StockEarningsRequest.Packed">`Packed() (*StockEarningsResponse, error)`</a>

  Returns a struct that contains equal\-length slices of primitives. This packed response mirrors Market Data's JSON response.

- <a href="#StockEarningsRequest.Raw">`Raw() (*resty.Response, error)`</a>

  Sends the request as is and returns the raw HTTP response.




<Tabs>
<TabItem value="Example (Get)" label="Example (Get)">




```go
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"}
```

</TabItem>

<TabItem value="Example (Packed)" label="Example (Packed)">




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

ser.Updated = []int64{} // Delete the updated field so the string output does not change between runs.

fmt.Println(ser)
```

#### Output

```
StockEarningsResponse{Symbol: [AAPL], FiscalYear: 2022, FiscalQuarter: 1, Date: [1640926800], ReportDate: [1643259600], ReportTime: [after close], Currency: [USD], ReportedEPS: [2.100000 ], EstimatedEPS: [1.890000 ], SurpriseEPS: [0.210000 ], SurpriseEPSpct: [0.111100 ], Updated: []}
```

</TabItem>

<TabItem value="Example (Raw)" label="Example (Raw)">




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

// Convert the response to a string if it's not already
serString := ser.String()

// Use regex to remove the "updated" key and its value so that the output is consistent between runs.
re := regexp.MustCompile(`,"updated":\[\d+\]`)
cleanedSerString := re.ReplaceAllString(serString, "")

fmt.Println(cleanedSerString)
```

#### Output

```
{"s":"ok","symbol":["AAPL"],"fiscalYear":[2022],"fiscalQuarter":[1],"date":[1640926800],"reportDate":[1643259600],"reportTime":["after close"],"currency":["USD"],"reportedEPS":[2.1],"estimatedEPS":[1.89],"surpriseEPS":[0.21],"surpriseEPSpct":[0.1111]}
```

</TabItem>
</Tabs>

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

```go
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

<a name="StockEarningsRequest.Countback"></a>
### Countback

```go
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.


<a name="StockEarningsRequest.Date"></a>
### Date

```go
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.


<a name="StockEarningsRequest.From"></a>
### From

```go
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.


<a name="StockEarningsRequest.Report"></a>
### Report

```go
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.


<a name="StockEarningsRequest.Symbol"></a>
### Symbol

```go
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.


<a name="StockEarningsRequest.To"></a>
### To

```go
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
<a name="StockEarningsRequest.Get"></a>
### Get

```go
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.



<a name="StockEarningsRequest.Packed"></a>
### Packed

```go
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.


<a name="StockEarningsRequest.Raw"></a>
### Raw

```go
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.



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

```go
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

- <a href="#StockEarningsRequest.Packed">`StockEarningsRequest.Packed()`</a>

  Generates this struct as a response to a stock earnings request.


#### Methods

- <a href="#StockEarningsReport.String">`String() string`</a>

  Returns a string representation of the StockEarningsResponse.

- <a href="#StockEarningsResponse.Unpack">`Unpack() ([]StockEarningsReport, error)`</a>

  Converts the response into a slice of StockEarningsReport structs.


#### Notes

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



<a name="StockEarningsResponse.String"></a>
### String

```go
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.


<a name="StockEarningsResponse.Unpack"></a>
### Unpack

```go
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.









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

```go
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

- <a href="#Unpack">`Unpack()`</a>

  Converts a StockEarningsResponse into a slice of StockEarningsReport structs.


#### Methods

- <a href="#StockEarningsReport.String">`String() string`</a>

  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.



<a name="StockEarningsReport.String"></a>
### String

```go
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.


