How to download the public companies’ earnings calendar in Python | by Eryk Lewinson | Towards Data Science

At the moment of writing, we are currently close to the end of the Q1 2020 earnings season. For many investors and quantitative finance hobbyists, this is a specially interesting period, with multiple short-term investment opportunities. That is why in this article, I wanted to briefly introduce the concept of the earnings season and show how to easily extract all the important information using Python.
The term earnings season refers to the time periods of the year during which most publicly listed companies release their quarterly corporate earnings reports to the public. The earnings seasons occur in the months immediately following the end of each fiscal quarter, so this would correspond to the months of January, April, July, and October. Typically, the earnings seasons last for about 6 weeks, after which the number of reported earnings subsidies to the off-season frequency (there are still some companies reporting off-season, as their financial calendars might be a bit different than the most).
Why is the earnings season an important time for potential investors? Simply because around the date of the given company’s earnings release (and mostly on the date itself), one can expect some significant price movements of the stock. That is caused by the fact that the public companies report their financial and general situation: profits/losses made in the past quarter, any significant changes to the organization, etc. Financial analysts use that information for assessing the intrinsic value of the stock — in order to determine if its current market price is over- or under-valued. This, in turn, is a potential signal for the investors to buy/sell/hold the stock.
Most of the companies have a dedicated part of their websites for potential/current investors, where they provide access to the earnings reports and also to the dates of the incoming earnings releases. Naturally, getting information from individual websites would not be feasible (or at least it would not be a pleasant experience). That is why we will refer to the popular source of financial data — Yahoo! Finance. Below you can see an image coming from the current earnings calendar.
In one of my previous articles, I showed how to leverage some popular Python libraries to easily download information related to the stock prices (and some additional information about the companies themselves). In this article, I extend the toolkit with a new library called yahoo-earnings-calendar (yes, the name is pretty self-explanatory). It definitely has a few advantages over the previously described solutions, as you will see below.
Aside from the standard libraries, we need to install yahoo_earnings_calendar by running the following line of code in the terminal:
pip install yahoo_earnings_calendar
Having done that, we import all the libraries we will use in this article:
Below, we will go over the three available methods used for downloading the earnings calendar.
The first method we explore is used for downloading the earnings for a specific date. To download the data, we first define the date using the datetime library. In this example, we use the current day (15th of May, 2020). Then, we instantiate an object of the YahooEarningsCalendar class. Using the earnings_on method, we download the data in the form of a list of dictionaries. Lastly, we store the downloaded data in a pandas.DataFrame.
Running the code generates the preview of the DataFrame.
The startdatetimetype column contains information about the time of the earnings call. Traditionally, the earnings (and any other important information about the company’s situation) are announced during an earnings call with the interested investors. Summing up, this is when the earnings are announced to the public.
Legend for the startdatetimetype column:
BMO — before the market opens
AMC — after the market closes
TAS/TNS — time not specified
By running df_earnings.shape we see that the DataFrame has 119 rows, which is in line with the screenshot presented above. A potential shortcoming of downloading the calendar this way is the fact that we only receive earnings data about US companies.
That is the default setting of the filter used on the Yahoo! Finance website. The easiest and most certain solution to download information about non-US companies is to do so by using the stock’s ticker. We discuss that method below.
Downloading the calendar for a range of dates is very similar to what we already described. This time, we use the earnings_between method and provide the start and end dates of the period of interest. For the example below, we download the earnings’ dates for the next 7 days.
This time earnings_df contains 312 positions.
One important thing to take into account while working with the earnings data is the fact that the calendar can change over time. So in the case of downloading the earnings a few weeks/months ahead of time, you might want to refresh the download every now and then to make sure the data is still valid.
Lastly, we download the earnings dates for a specific product, Twitter in this case. We do that by using the get_earnings_of method and providing the stock’s ticker. What is different this time around is that the request will return a list of past and future earnings. That is why we extract the date from the timestamp string (it is stored in the ISO-8601 format) and use the between method to filter out only the earnings from the upcoming 180 days.
The code returns the following table, which contains the 2 earnings release dates for Twitter in the upcoming 180 days.
In this article, I explained what is the earnings season and how to easily get all the earnings releases dates from Yahoo! Finance.
Having the data available for use in Python, I can think of a few potential use-cases:
Building an automated email /Slack bot notifying you about relevant earnings releases.
Including the earnings release dates in your ML model used for predicting the price of the stock. For example, you can indicate the earnings dates as changepoints in Facebook's Prophet.
The yahoo-earnings-calendar library is pretty compact in terms of lines of code, so I would definitely recommend inspecting the code to understand how the data is actually scraped from Yahoo! Finance. This might be especially important, as Yahoo! tends to change the website rather frequently, what can result in the library becoming unusable, at least until it is fixed. That is why you should be cautious when putting any code based on it into production. Additionally, it definitely makes sense to be familiar with the methodology used for scraping the data, so you can potentially fix any issues before they are fixed by the author. And you can always do a pull request with that update :)
You can find the code used for this article on my GitHub. As always, any constructive feedback is welcome. You can reach out to me on Twitter or in the comments.
Not that long ago I published a book on using Python for solving practical tasks in the financial domain. If you are interested, I posted an article introducing the contents of the book. You can get the book on Amazon or Packt’s website.
[1] Yahoo! Earnings Calendar Scraper — GitHub