sec-api-utils 0.1.0

A non-official wrapper for the sec-edgar-api, with built-in representation classes.

SEC-API-UTILS

This python package is an unofficial wrapper for the SEC-EDGAR-API. According to the fair-use policy of the API provided by the SEC, 10 requests per second can be made (https://www.sec.gov/developer). Limiting the number of requests is automatically fulfilled by the data loader of the SEC-API-UTILS package. The data loader can be used for retrieving company facts by the use of the ticker name of the company. Furthermore, the python package provides some utilities for plotting the data retrieved. Data can either be retrieved as a dictionary corresponding to the JSON retrieved over the SEC-API or an internal representation starting with the SECCompanyInfo class.

Data Loader

Loading the data over SEC-EDGAR-API can be performed by using the SECAPILoader to which at least the name and the email address must be provided. For being able to use the ticker name as identifier the SECAPILoader loads a ticker to CIK (SEC identification number of the stock) mapping into a cache directory once in the current working directory.

Following 4 lines show the simple loading of data with the use of the SECAPILoader.

from sec_api_utils.data_loading.SECAPILoader import SECAPILoader
from sec_api_utils.data_representation.SECCompanyInfo import SECCompanyInfo
data_loader = SECAPILoader(your_company_name="<your_company_name>", 
                           your_company_email="<your>@<company_email>.com",
                           override_cached_company_tickers=False)
data_msft: SECCompanyInfo = data_loader.get_data_from_ticker(ticker_name="MSFT", as_dict=False)

Setting 'override_cached_company_tickers' to False enforces the data loader to use the 'company_tickers.json' (ticker name to CIK mapping) from the cached directory. When set to true the 'company_tickers.json' is overridden in the cache directory even if it is already available.

When loading the data with 'data_loader.get_data_from_ticker' one can simply choose if he wants the raw data as dictionary or in the representation provided by the package by setting flag 'as_dict' to True or False.

Data Representation (package classes vs. dictionary)

As mentioned in section 'Data Loading' one can choose between representation of the loaded data as a dictionary or as the provided representation covered by the classes in data_representation.

When choosing the dictionary as representation the retrieved object represents a nested dictionary containing the requested data of the given company. The retrieved dictionary will look like the following:

{
	"cik": 789019,
	"entityName": "MICROSOFT CORPORATION",
	"facts": {
		"dei": {
			"EntityCommonStockSharesOutstanding": {
				"label": "Entity Common Stock, Shares Outstanding",
				"description": "Indicate number of shares or other units outstanding of each of registrant's classes of capital or common stock or other ownership interests, if and as stated on cover of related periodic report. Where multiple classes or units exist define each class/interest by adding class of stock items such as Common Class A [Member], Common Class B [Member] or Partnership Interest [Member] onto the Instrument [Domain] of the Entity Listings, Instrument.",
				"units": {
					"shares": [
						{
							"end": "2009-10-19",
							"val": 8879121378,
							"accn": "0001193125-09-212454",
							"fy": 2010,
							"fp": "Q1",
							"form": "10-Q",
							"filed": "2009-10-23",
							"frame": "CY2009Q3I"
						},
						...
					]
				}
			},
			...
		"us-gaap": {
			"AccountsPayableCurrent": {
				"label": "Accounts Payable, Current",
				"description": "Carrying value as of the balance sheet date of liabilities incurred (and for which invoices have typically been received) and payable to vendors for goods and services received that are used in an entity's business. Used to reflect the current portion of the liabilities (due within one year or within the normal operating cycle if longer).",
				"units": {
					"USD": [
						{
							"end": "2009-06-30",
							"val": 3324000000,
							"accn": "0001193125-09-212454",
							"fy": 2010,
							"fp": "Q1",
							"form": "10-Q",
							"filed": "2009-10-23"
						},
                      ...
					]
				}
			},
          ...
		}
	}
}

When using the provided classes as representation of the data, the outermost dictionary will be represented by the SECCompanyInfo class. Filing information about the company are stored inside the SECFilingInfo class, which represents the dictionary in the facts section. Each of the members of the SECFilingInfo like 'us_gaap' is a list of SECBaseMeasures, which contain e.g. label, description and the units. The units member of the SECBaseMeasure is a list of SECUnits, which represent one data point in time to the corresponding SECBaseMeasure. This could be for instance the Goodwill of the company.

SECCompanyInfo provides methods for retrieving the desired information by name in efficient manner. If one wants to get the yearly goodwill information filed by a company one can simply use the SECCompanyInfo retrieved as shown below:

from sec_api_utils.data_loading.SECAPILoader import SECAPILoader
from sec_api_utils.data_representation.SECCompanyInfo import SECCompanyInfo
from sec_api_utils.data_representation.SECBaseMeasure import SECBaseMeasure
data_loader = SECAPILoader(your_company_name="<your_company_name>", 
                           your_company_email="<your>@<company_email>.com",
                           override_cached_company_tickers=False)
data_msft: SECCompanyInfo = data_loader.get_data_from_ticker(ticker_name="MSFT", as_dict=False)
goodwill_filings: SECBaseMeasure = data_msft.get_measure_info("Goodwill")
yearly_goodwill = goodwill_filings.get_by_form_type("10-K")

Plotting

For fast visualization of the datapoints a simple plotting function, which plots the data with the help of matplotlib and seaborn is provided.

Continuing the example from above the goodwill can be plotted with the following call

from sec_api_utils.plotting.SECUnitPlotter import NumberFormat, SECUnitPlotter 
SECUnitPlotter().plot_sec_units_base(yearly_goodwill, auto_number_format=False, number_format=NumberFormat.THOUSANDS, title="Goodwill")

To the plot_sec_units_base() method the List[SECUnits] is passed, which were retrieved and stored in variable 'yearly_goodwill'. Parameter 'auto_number_format' declares if the number format should be determined automatically, which is set to False in this case because we provided a number_format with 'NumberFormat.THOUSANDS'. The passed number format will show the SECUnits in thousands on the plot. Furthermore, we passed a title to the plotting method as well. As a result, we get the following plot: