AlphaVantage API for Earnings Data

When investing in a public company there are only a handful of times during the year where investors are given meaningful updates on how the company is performing. The most meaningful of these updates come through the companies quarterly earnings reports.

When retail investors are analyzing a stock for a potential investment the first thing many will look at is the price action. Has the stock been trending up? Has the stock price come down to a point where it is now cheap? For me personally, I look at the earnings data. If there is a meaningful upward trend in the quarterly and annual earnings per share (EPS) to me that signals many good things but at its core it signals growth.

When using AlphaVantage’s API to obtain stock data for analysis it is very easy to access the time series data and various technical indicators, however I found it difficult to get all the earnings data in a workable format. Below is the work around I used to pull all the quarterly and annual earnings data into one dataframe.

Pulling Quarterly EPS Data

Above we start with our imports and by defining which ticker/stock we want to pull data for. For this post we will use Zoom Video Communications (ZM). We then do an API call to get the EPS data in a json object which is a bit of a mess as you can see in the picture below.

{'symbol': 'ZM',
 'annualEarnings': [{'fiscalDateEnding': '2020-10-31', 'reportedEPS': '2.11'},
  {'fiscalDateEnding': '2020-01-31', 'reportedEPS': '0.35'}],
 'quarterlyEarnings': [{'fiscalDateEnding': '2020-10-31',
   'reportedDate': '2020-11-30',
   'reportedEPS': '0.99',
   'estimatedEPS': '0.7604',
   'surprise': '0.2296',
   'surprisePercentage': '30.1946'},
  {'fiscalDateEnding': '2020-07-31',
   'reportedDate': '2020-08-31',
   'reportedEPS': '0.92',
   'estimatedEPS': '0.4538',
   'surprise': '0.4662',
   'surprisePercentage': '102.7325'},
  {'fiscalDateEnding': '2020-04-30',
   'reportedDate': '2020-06-02',
   'reportedEPS': '0.2',
   'estimatedEPS': '0.0985',
   'surprise': '0.1015',
   'surprisePercentage': '103.0457'},
  {'fiscalDateEnding': '2020-01-31',
   'reportedDate': '2020-03-04',
   'reportedEPS': '0.15',
   'estimatedEPS': '0.0711',
   'surprise': '0.0789',
   'surprisePercentage': '110.9705'},
  {'fiscalDateEnding': '2019-10-31',
   'reportedDate': '2019-12-05',
   'reportedEPS': '0.09',
   'estimatedEPS': '0.0311',
   'surprise': '0.0589',
   'surprisePercentage': '189.3891'},
  {'fiscalDateEnding': '2019-07-31',
   'reportedDate': '2019-09-05',
   'reportedEPS': '0.08',
   'estimatedEPS': '0.0144',
   'surprise': '0.0656',
   'surprisePercentage': '455.5556'},
  {'fiscalDateEnding': '2019-04-30',
   'reportedDate': '2019-06-06',
   'reportedEPS': '0.03',
   'estimatedEPS': '0.0061',
   'surprise': '0.0239',
   'surprisePercentage': '391.8033'}]}

The EPS object is a dictionary but the only values we want are those stored in the key ‘quarterlyEarnings’. In the above function we access the first value in quarterlyEarnings and use it to create a dataframe. We then loop through the remaining values which are stored in a list of dictionaries and merge each one to the dataframe until we have all the values we need.

We then transpose the dataframe, convert the datetime columns to datetime, all other columns to numeric (which we renamed), set the index and return the dataframe.

The result of our quarterly_earnings_df function is below.

Pulling Annual EPS Data

The process for pulling the annual EPS data is virtually the same as the quarterly as you can see in the below code. The only differences are in the first for loop where we specify the range based on the annualEarnings rather than the quarterly, and where we swap out the quarterlyEarnings argument in the if and else statement for the annualEarnings.

Dataframe for ZM using annual_earnings_df function

Pulling all earnings data

With both the quarterly_earnings_df and annual_earnings_df functions we created above, we can create a new function to pull all the earnings data into one dataframe.

When using earnings data in tandem with time series data to analyze the price action of a stock, it is best to use the reported earnings date since the date represents when current/potential investors were presented with the information. With this in mind below is the function to pull all earnings data for any given ticker.

All we are doing with this function is using the other two functions we created to pull individual dataframes for quarterly (dfq) and annual earnings (dfa) while also creating a dictionary (reported_dict) with the keys being the fiscalDateEnding and the values being the reportedDate. We then use this dictionary to map the values onto the index of our annual earnings dataframe and merge the two dataframes together. The results of our three functions is a clean dataframe with all the earnings data we need to use in our analysis.