REST API

The SEC recently released an API which can be used to more easily access data on companies. For a complete overview of the API, you can read more here.

Wrapper

In order to make this information even easier to extract, secedgar contains functions that wrap around the EDGAR API to make the data even more accessible. Below are the functions available via secedgar.

secedgar.core.rest.get_submissions(lookups: List[str] | str, user_agent: str, recent: bool = True) → dict

Get information about submissions for entities.

Parameters:

  • lookups (list of str or str) – Tickers or CIKs to get submission data for.

  • user_agent (str) – User agent to provide the SEC.

  • recent (bool, optional) – Whether or not to only get the most recent. Setting recent to True will give at least one year of filings or 1000 filings (whichever is more). Setting recent to False will return all filings. Defaults to True.

Returns:

Dictionary with keys being the lookups and values being the responses from the API.

Return type:

dict

secedgar.core.rest.get_company_concepts(lookups: List[str] | str, user_agent: str, concept_name: str) → dict

Get company concepts using SEC’s REST API.

Parameters:

  • lookups (list of str or str) – Tickers or CIKs to get concepts for.

  • user_agent (str) – User agent to send to SEC.

  • concept_name (str) – Name of the concept to get data for.

Returns:

Dictionary with concept data for given lookups.

Return type:

dict

Example

concept = "AccountsPayableCurrent"
get_company_concepts(lookups=["AAPL"],
                     user_agent="Name (email@example.com)",
                     concept_name=concept)
secedgar.core.rest.get_company_facts(lookups: List[str] | str, user_agent: str) → dict

Get company facts for lookups.

Parameters:

  • lookups (list of str or str) – Tickers or CIKs to get company facts for.

  • user_agent (str) – User agent to send to SEC.

Returns:

Dictionary with lookups as keys and company fact dictionaries as values.

Return type:

dict

Examples

>>> facts = get_company_facts(["aapl"], "Name (email@example.com)")
>>> single_fact = facts["aapl"]["facts"]["us-gaap"]["Assets"]["units"]["USD"][0]
>>> single_fact["val"]
39572000000
>>> single_fact["fy"]
2009
>>> single_fact["fp"]
Q3
>>> single_fact["form"]
'10-Q'
>>> single_fact["filed"]
'2009-07-22'
secedgar.core.rest.get_xbrl_frames(user_agent: str, concept_name: str, year: int, quarter: None | int = None, currency: str = 'USD', instantaneous: bool = False) → dict

Get data for concept name in year (and quarter, if given).

Parameters:

  • user_agent (str) – User agent to send to the SEC.

  • concept_name (str) – Concept name to get. For example, “Assets”.

  • year (int) – Year to get concept data for.

  • quarter (Union[int, NoneType], optional) – Quarter to get data for. If given None, will look for data for the entire year. Defaults to None.

  • instantaneous (bool, optional) – Whether to look for instantaneous data. See SEC website for more. Defaults to False.

Returns:

Dictionary with information about concept_name.

Dig into the data key for all period data.

Return type:

dict

Examples

frames = get_xbrl_frames(user_agent="Name (email@example.com)",
                         concept_name="Assets",
                         year=2020,
                         quarter=3,
                         instantaneous=True)
print(frames["data"][-1]["entityName"])
# Prints "MOXIAN (BVI) INC"
print(frames["data"][-1]["val"])
# Prints 2295657
print(frames["data"][-1]["accn"])
# Prints "0001493152-22-013323"