Package: secapi-tl
secapiThis module provides a set of functions that can be used to query
company submissions from the sec.
As well as some utility functions that can be used to get sec related
information about companies.Technical informationThe module was developed with python 2.7.18 and only uses build-in python packages as well
as the packages typing, requests, ratelimiter andOpenDateRange.Installation$ pip install secapi-tlcore functionssec_requestThe sec_request method is used to make requests to the sec.
It has a rate limit mechanism implemented that ensures that the amount of
requests stays in the boundaries set by the sec.
All methods from this module
use this method internally for their requests. Thereby your own requests to
the sec will be compatible if you use this method. Furthermore, the sec_request method will automatically
create a header with a valid User-Agent. You can also pass your own header to the method.
If this header does not contain a User-Agent, the method will add a valid User-Agent to the header.fromsecapi_tlimportsec_requestraw_data=sec_request(url="https://www.sec.gov/Archives/edgar/data/320193/000032019323000070/xslF345X04/wf-form4_168444912415136.xml")get_submissionsThe get_submissions function queries company submissions via the
data.sec.gov/submissions/ endpoint as recommendedhere.
The method takes parameters that can be used to filter the queried submissions.
A query accepts the following parameters:ticker_symbol_or_cik: The ticker symbol or cik of the company you want to query submissions for.
Takes lowercase and uppercase letters for ticker symbols.
Ciks must be passed as strings but leading zeros are not required.start_date: Only submissions that have been published at or after this date will be queried.
The date must be passed as a string of format YYYY-MM-DD.end_date: Only submissions that have been published at or before this date will be queried.
The date must be passed as a string of format YYYY-MM-DD.form_type: Only submissions that have one of the specified form types will be queried.
You can pass a form type as a string or a list of form types as a list of strings.The method returns a list of Submission objects. Each submission object holds
the data for one submission. The data can be accessed via properties of the object.fromsecapi_tlimportget_submissions# query form 4 submissions for apple in january 2021submissions=get_submissions(ticker_symbol_or_cik="AAPL",start_date="2021-01-01",end_date="2021-01-31",form_type="4")!!! WARNING !!! Since the data.sec.gov/submissions/ endpoint is constantly under a
high load, it can happen that a TooManyRequestsError is raised. Since the method
does use the sec_request method there is no violation of the rate limit. Requests
to other endpoints will therefore still work. The occurrence of this error is
highly dependent on the usage of this method. So you might need to implement
a mechanism that handles this error depending on your use case. The TooManyRequests
error is part of this module and can be imported from the module.fromsecapi_tlimportTooManyRequestsErrorutility functionsMost of the utility functions are based on thecompany tickers file.
They use this file for transitions between cik and ticker symbol or to
proof if a ticker symbol is registered at the sec or not.is_registeredThis method takes a ticker symbol and returns True if the ticker symbol is registered
at the sec and False if it is not registered. If the method returns True the ticker symbol
can be used with all other methods of this module. The ticker symbol can be uppercase and
lowercase. The method will automatically convert the ticker symbol to uppercase letters.fromsecapi_tlimportis_registeredis_registered("AAPL")# Trueis_registered("aapl")# Trueis_registered("AAP")# Falseticker_to_cikThis method takes a ticker symbol and returns the cik of the company to which the ticker symbol belongs.
If the ticker symbol is not found a ValueError is raised.
The ticker symbol can be uppercase and lowercase. The method will automatically convert the ticker symbol to uppercase letters.fromsecapi_tlimportticker_to_cikticker_to_cik("AAPL")# "320193"filter_tickers_registeredTakes a list of ticker symbols and returns a list of those ticker symbols that
are found to be registered at the sec. The ticker symbols can be uppercase and lowercase.
The returned ticker symbols are uppercase.fromsecapi_tlimportfilter_tickers_registeredfilter_tickers_registered(["AAPL","TSLA","AAP"])# ["AAPL", "TSLA"]This method is useful if you want to query submissions for a list of companies
and you dont know if all of the companies are registered at the sec.
All the returned ticker symbols will work with the get_submissions method.get_registered_tickersReturns a list of all ticker symbols that are found in thecompany tickers file.get_registered_ciksReturns a list of all ciks that are found in thecompany tickers file.