A short and sweet way of acknowledging the latest economic events
Financial news is not the only major factor that influences the stock market but also another prominent aspect which is the economic events. To define it in plain english, economic events are events related to a company’s finance that have economic significance and influences the stock market as well as the company’s financial condition.
Like how stock screeners are built to easily get the latest information on the price changes of the desired stocks, economic calendars are used for updating themselves with the latest and upcoming economic events and making investments accordingly.
Since I’m not really fond of using external economic calendars tools and building things myself is my forte, my go-to for this task is always Python and with the help of EOD Historical Data’s (EODhd) APIs, the process is made easier. In this article, we will be building two different types of economic calendars using EOD Historical Data’s API for economic calendars in Python. Without further ado, let’s dive into the article!
Note: This article is intensely based on the APIs provided by EOD Historical Data. So to follow up with the upcoming content without any distress, make sure that you have an account for yourself as it enables you to access your private API key. You can create an account using the link here. Also, not all APIs mentioned in this article are offered for free but a subscription is needed. View the pricing of all subscriptions here and choose what best fits you.
Importing Packages
Let’s first start by importing the required packages into our python environment as it is the foremost process in any programming project. The only packages we need in this article are Requests to make API calls and Pandas for working with the data. In case you have not yet installed these two packages, enter the following lines of code in your command line:
pip install requests
pip install pandas
After installing the packages, we can now import them into our python environment using the code below:
import requests
import pandas as pd
api_key = 'YOUR API KEY'
We have now successfully imported the essential packages into our environment along with storing the API key into the 'api_key' variable.
Earnings Economic Calendar
The first type of calendar we are going to build in this article is an earnings calendar. For those who don’t what an earnings calendar is, it is a calendar that reveals the reporting as well as the releasing date of the earnings statement of a particular company. Investors use earnings statements to assess the performance of the stocks and start tuning their portfolios accordingly. Hence it can be said that the earnings statement has a direct influence on the investors and the market, and has economic significance.
In this article, we are going to build two different types of earnings calendars: An upcoming earnings calendar and a historical earnings calendar of a specific stock. Let’s start off with the first type of calendar.
Upcoming Earnings Calendar
The basic idea of this section is to define a function that builds a basic upcoming earnings calendar representing the reporting date of the earnings statement of a particular along with its influence on the market. The python code to build the calendar looks like this:
def get_upcoming_earnings(start_report_date, end_report_date, currency, api_key, n_limit):
url = f'https://eodhistoricaldata.com/api/calendar/earnings?api_token={api_key}&fmt=json&from={start_report_date}&to={end_report_date}'
u_earnings = requests.get(url).json()
u_earnings_df = pd.DataFrame(u_earnings['earnings']).drop('before_after_market', axis = 1).fillna(0)
u_earnings_df = u_earnings_df[u_earnings_df.currency == f'{currency}']
u_earnings_df = u_earnings_df[u_earnings_df.actual != 0]
u_earnings_df = u_earnings_df.rename(columns = {'code':'stock'})
u_earnings_df = u_earnings_df.iloc[-n_limit:]
u_earnings_df.index = range(len(u_earnings_df))
return u_earnings_df
us_stocks_u_earnings = get_upcoming_earnings('2021-11-23', '2021-11-26', 'USD', api_key, 10)
us_stocks_u_earnings
Let’s now break down the above-represented code. Firstly, we are defining a function named 'get_upcoming_earnings' that takes the following as parameters: The starting date of the earnings calendar ('start_report_date'), the currency of the earnings data ('currency'), the ending date of the earnings calendar ('end_report_date'), API Key ('api_key'), and finally the length of the output ('n_limit').
Inside the function, we are first storing the API URL into the 'url' variable, followed by that, we are making an API call using the 'get' function provided by the Requests package to extract the data in JSON format. Let’s now take a minute to have a look at the structure of the API URL. This is the URL used inside the above-defined function:
https://eodhistoricaldata.com/api/calendar/earnings?api_token={api_key}&fmt=json&from={start_report_date}&to={end_report_date}
The first parameter in the URL is the 'api_token' parameter where we have to specify the API key. The second parameter is the 'fmt' parameter, which is an optional one, where we have to mention the type of output we want, either JSON or CSV. The third and fourth parameters are the 'from' and 'to' parameters in which the starting and ending date of the earnings calendar needs to be specified.
Coming back to the code, after storing the API response into the 'data' variable, we are converting it into a Pandas Dataframe along with some data manipulations and storing it into another variable 'u_earnings_df '. The following lines of code are further data manipulations carried out based on the given inputs. Lastly, we are returning the final dataframe and calling the created function to build an upcoming earnings calendar that looks like this:
Historical Earnings Calendar
The concept of this section is to create a calendar that represents a given stock’s historical earnings data within a specified timeframe which has information of the reporting date of the statement along with its influence on the market. The structure of the code is more or less similar to the ones we saw before while creating the upcoming earnings calendar and looks like this:
def get_historical_earnings(stock, start_date, api_key):
url = f'https://eodhistoricaldata.com/api/calendar/earnings?api_token={api_key}&fmt=json&symbols={stock}&from={start_date}'
h_earnings = requests.get(url).json()
h_earnings_df = pd.DataFrame(h_earnings['earnings']).rename(columns = {'code':'stock'})
return h_earnings_df
aapl_h_earnings = get_historical_earnings('AAPL.US', '2020-01-01', api_key)
aapl_h_earnings
As I said before, the structure of the code is almost identical to the previous section’s ones except for the fact that the parameters of the function and the API URL differ a little. So we will now focus on those two different areas.
The first is the function’s parameters. The above-defined function has three parameters: the symbol of the stock ('stock'), the starting date of the earnings data ('start_date'), and finally the API key ('api_key'). The second is the API URL. There is no big difference between the URL of this section and the previous ones but we are just adding one more parameter, the 'stock' parameter, to specify the stock we would like to access the historical earnings data of. The output of the function is a calendar that looks like this:
IPO Calendar
IPOs are one of the most significant economic events and have a direct influence on the market. To define IPO, it is the abbreviation of Initial Public Offering, where a company becomes a publicly tradeable asset to raise capital for their firm by welcoming new investors. Now the concept of this part of the article is to create a calendar that reveals the upcoming dates of IPOs along with some information and the code to create the IPO calendar looks like this:
def get_upcoming_ipos(start_report_date, end_report_date, api_key):
url = f'https://eodhistoricaldata.com/api/calendar/ipos?api_token={api_key}&fmt=json&from={start_report_date}&to={end_report_date}'
u_ipos = requests.get(url).json()
u_ipos_df = pd.DataFrame(u_ipos['ipos']).drop('name', axis = 1).rename(columns = {'code':'stock'}).fillna(0)
u_ipos_df = u_ipos_df[u_ipos_df.amended_date != 0]
u_ipos_df = u_ipos_df[u_ipos_df.stock != 'N/A']
u_ipos_df.index = range(len(u_ipos_df))
return u_ipos_df
upcoming_ipos = get_upcoming_ipos('2021-11-20', '2021-11-26', api_key)
upcoming_ipos
The above-defined function is not so different from the previously seen code snippets but the API URL changes so we will just focus on that. The API URL used in the code looks like this:
https://eodhistoricaldata.com/api/calendar/ipos?api_token={api_key}&fmt=json&from={start_report_date}&to={end_report_date}
The API URL is not so distinguishable from the ones we saw before. In the previously seen URLs, we will be extracting data from the 'Earnings' page ('/calendar/earnings') but since we are willing to access a different type of information, in our case of IPO data, we are pulling the data from the 'IPOs' page ('/calendar/ipos'). Speaking about the parameters, it is pretty much the same, and nothing much going in that area. The output will be an IPO calendar consisting of all the essential details that look like this:
Closing Notes
In this article, we have seen how can the EODhd’s calendar APIs be used to build several different types of economic calendars. There are also more ways to customize the calendar along with some other API features which are not covered in this article but I would say it is worth the time to have a look at those.
The important message of this article, according to me is, a lot of people are solely relying upon news for their market predictions and investments but the ones who are also looking into and updating themselves with the major economic events will hold a strong edge over the market. And in this article, we found a way to easily manage this task.
With that being said, you’ve reached the end of the article. Hope you learned something new and useful. Also, if you want to see the original documentation for more information, view it using this link: https://eodhistoricaldata.com/financial-apis/calendar-upcoming-earnings-ipos-and-splits/