US Government Electronic Data Gathering, Analysis, and Retrieval System (EDGAR)

class edgar.edgarFiler(ticker, name='webmaster', email='webmaster@sec.gov')

Accesses data from the SEC’s EDGAR database RESTful API. In current state this class wraps all the functionality for the API, providing JSON data to the user. The SEC asks that users do not make more than 10 requests per second. The SEC requires that automated requests declare a user-agent header, and while this class provides a default it is highly recommended that you set your own name and email.

Parameters

  • ticker (string, required) – The ticker symbol of the stock which you would like to access data for.

  • name (string, strongly advised) – Your personal or business name. Used in request headers to validate your API access.

  • email (string, strongly advised.) – Your personal or business email. Used in request headers to validate your API access.

get_accessions(count=20, filter=None)

Returns most recent accession numbers and document type for the document for the desired company If there is no filter set, it sets and attribute called accession_numbers with result. If there are filters applied, the filters are joined with underscores in this format: {filters}_accessions.

Data comes from the data.sec.gov/submissions/ endpoint. The SEC asks that users do not make more than 10 requests per second.

Parameters

  • count (int, optional, default 20) – The number of documents to return.

  • filter (list of strings, optional, defualt is None) – Filters results by the requested form type. Accepts multiple values.

Returns

dictionary, {accession_number : {form : filing_type,date : filing_date}}

get_cik()

Finds the Central Index Key (CIK) for the requested ticker through HTML tree traversal. :return: string, CIK

get_company_concept(concept, taxonomy='us-gaap')

Returns all the disclosures from a single company and concept (a taxonomy and tag) into a single JSON file. Returns a separate array of facts for each units on measure that the company has chosen to disclose. Sets an attribute for the class formatted like {concept}_{taxonomy} which allows you to fetch multiple taxonomies of the same concept.

Data comes from the data.sec.gov/api/xbrl/companyconcept/ endpoint. The SEC asks that users do not make more than 10 requests per second.

Parameters

  • concept (string, required) – The tag or line item you are requesting.

  • taxonomy (string, optional, default is us-gaap) – The reporting taxonomy for the tag you want to access. (us-gaap, ifrs-full, dei, srt)

Returns

Dictionary of raw JSON data returned by endpoint

get_company_facts()

Returns all the company concepts data for a company into a single JSON object. Sets a class attribute called company_facts.

Data comes from the data.sec.gov/api/xbrl/companyfacts/ endpoint. The SEC asks that users do not make more than 10 requests per second.

Returns

Dictionary of raw JSON returned by the endpoint

get_edgar_request(url, user_header=True, stream=False)

Returns a response object from EDGAR with options for headers and file streaming. Throws a verbose error code on non-200 status codes. Saves all raw responses in request_log class attribute.

Parameters

  • url (string, required) – The url you would like to request.

  • user_header – If you would like to send

get_report_raw(accession, directory='')

Takes an accession number and streams a text report file to your environment. File is named in the following format: {ticker}_{accession}. You can use the directory argument to specify the directory you would like to save the file in. This uses the exact text entered and appends it to the filename allowing for relative file placement.

Parameters

  • accession (string, required) – The accession number for the report you would like to download. Available online or through get_accessions method.

  • directory (string, optional) – The directory you would like to send the file to.

Returns

filename, string