EdgarAPI

class edgar_sec.EdgarAPI(cache_mode=False)[source]

Bases: object

Interact with the US Securities and Exchange Commission EDGAR API.

This class provides methods to access the SEC’s EDGAR database through their RESTful API endpoints. The data.sec.gov service delivers JSON-formatted data without requiring authentication or API keys. The API provides access to: Filing entity submission history and XBRL financial statement data (forms 10-Q, 10-K, 8-K, 20-F, 40-F, 6-K).

Examples

>>> api = EdgarAPI(cache_mode=True)
>>> apple_data = api.get_submissions("0000320193")
>>> company_concept = api.get_company_concept("0000320193", "us-gaap", "AccountsPayable")

Note

The SEC imposes a request rate limit which this implementation respects through built-in rate limiting mechanisms. The rate limit is 10 requests per second. If the rate limit is exceeded, the API will raise a ValueError with an appropriate message.

class AsyncAPI(parent)[source]

Bases: object

Asynchronous version of the EdgarAPI methods.

Parameters:

parent – The parent EdgarAPI instance that created this AsyncAPI instance. This provides access to configuration and resources of the parent.

Returns:

An instance of the AsyncAPI class that provides async methods

for all EdgarAPI functionality.

Return type:

AsyncAPI

Example

>>> from edgar_sec import EdgarAPI
>>> import asyncio
>>> async def get_apple_data():
>>>     api = EdgarAPI(cache_mode=True)
>>>     # Get Apple Inc's submission history asynchronously
>>>     apple_history = await api.Async.get_submissions("0000320193")
>>>     print(apple_history.name)
>>> asyncio.run(get_apple_data())
'Apple Inc.'

Note

All methods in this class are coroutines that must be awaited. They follow the same rate limiting as the synchronous methods but are more efficient when making multiple concurrent requests.

async get_company_concept(central_index_key, taxonomy, tag)[source]

Asynchronously retrieve XBRL disclosures for a specific concept from a company.

Parameters:

  • central_index_key (str) – 10-digit Central Index Key (CIK) of the entity, including leading zeros. A CIK may be obtained at the SEC’s CIK lookup: https://www.sec.gov/search-filings/cik-lookup

  • taxonomy (str) – A non-custom taxonomy identifier (e.g. ‘us-gaap’, ‘ifrs-full’, ‘dei’, or ‘srt’).

  • tag (str) – The specific disclosure concept tag to retrieve, such as ‘AccountsPayableCurrent’ or ‘Assets’.

Returns:

An object containing all disclosures related to the specified concept, organized by units of measure.

Return type:

CompanyConcept

Example

>>> from edgar_sec import EdgarAPI
>>> import asyncio
>>> async def main():
>>>     api = EdgarAPI()
>>>     # Get Apple Inc's Accounts Payable disclosure asynchronously
>>>     concept = await api.Async.get_company_concept("0000320193", "us-gaap", "AccountsPayableCurrent")
>>>     for unit in concept.units:
>>>         print(f"Value: {unit.val}, Period: {unit.end}")
>>> asyncio.run(main())

Note

This endpoint returns separate arrays of facts for each unit of measure that the company has disclosed (e.g., values reported in both USD and EUR).

async get_company_facts(central_index_key)[source]

Asynchronously retrieve all XBRL disclosures for a company in a single request.

Parameters:

central_index_key (str) – 10-digit Central Index Key (CIK) of the entity, including leading zeros. A CIK may be obtained at the SEC’s CIK lookup: https://www.sec.gov/search-filings/cik-lookup

Returns:

An object containing all facts and disclosures for the company, organized by taxonomy and concept.

Return type:

CompanyFact

Example

>>> from edgar_sec import EdgarAPI
>>> import asyncio
>>> async def main():
>>>     api = EdgarAPI()
>>>     # Get all Apple Inc's financial disclosures asynchronously
>>>     facts = await api.Async.get_company_facts("0000320193")
>>>     # Access a specific concept in the US GAAP taxonomy
>>>     revenue = facts.facts["us-gaap"].disclosures.get("RevenueFromContractWithCustomerExcludingAssessedTax")
>>>     if revenue and "USD" in revenue.units:
>>>         print(f"Latest revenue: ${revenue.units['USD'][0].val}")
>>> asyncio.run(main())

Note

This is the most comprehensive endpoint, returning all concepts across all taxonomies for a company. The response can be quite large for companies with extensive filing histories.

async get_frames(taxonomy, tag, unit, period)[source]

Asynchronously retrieve aggregated XBRL facts across multiple companies for a specific period.

Parameters:

  • taxonomy (str) – A non-custom taxonomy identifier (e.g. ‘us-gaap’, ‘ifrs-full’, ‘dei’, or ‘srt’).

  • tag (str) – The specific disclosure concept tag to retrieve (e.g. ‘AccountsPayableCurrent’, ‘Assets’).

  • unit (str) – Unit of measurement for the requested data. Default is ‘pure’. Denominated units are separated by ‘-per-’ (e.g. ‘USD-per-shares’), non-denominated units are specified directly (e.g. ‘USD’).

  • period (str) – The reporting period in the format: Annual (365 days ±30 days): CY#### (e.g. ‘CY2019’), Quarterly (91 days ±30 days): CY####Q# (e.g. ‘CY2019Q1’), Instantaneous: CY####Q#I (e.g. ‘CY2019Q1I’)

Returns:

An object containing facts from multiple companies for the specified concept and period.

Return type:

Frame

Example

>>> from edgar_sec import EdgarAPI
>>> import asyncio
>>> async def main():
>>>     api = EdgarAPI()
>>>     # Get all companies' Q1 2019 Accounts Payable data in USD asynchronously
>>>     frame = await api.Async.get_frames("us-gaap", "AccountsPayableCurrent", "USD", "CY2019Q1I")
>>>     # Print the first few results
>>>     for i, disclosure in enumerate(frame.data[:3]):
>>>         print(f"{disclosure.entity_name}: ${disclosure.val}")
>>> asyncio.run(main())

Note

Due to varying company fiscal calendars, the frame data is assembled using the dates that best align with calendar periods. Be mindful that facts in a frame may have different exact reporting start and end dates.

async get_submissions(central_index_key)[source]

Asynchronously retrieve a company’s submission history from the SEC EDGAR database.

Parameters:

central_index_key (str) – 10-digit Central Index Key (CIK) of the entity, including leading zeros. A CIK may be obtained at the SEC’s CIK lookup: https://www.sec.gov/search-filings/cik-lookup

Returns:

An object containing the entity’s filing history,

including company information and recent filings.

Return type:

SubmissionHistory

Example

>>> from edgar_sec import EdgarAPI
>>> import asyncio
>>> async def main():
>>>     api = EdgarAPI()
>>>     # Get Apple Inc's submission history asynchronously
>>>     apple_history = await api.Async.get_submissions("0000320193")
>>>     print(apple_history.name)
>>> asyncio.run(main())
'Apple Inc.'

Note

This endpoint returns the most recent 1,000 filings or at least one year’s worth, whichever is more. For entities with additional filings, the response includes references to additional JSON files and their date ranges.

get_company_concept(central_index_key, taxonomy, tag)[source]

Retrieve XBRL disclosures for a specific concept from a company.

Parameters:

  • central_index_key (str) – 10-digit Central Index Key (CIK) of the entity, including leading zeros. A CIK may be obtained at the SEC’s CIK lookup: https://www.sec.gov/search-filings/cik-lookup

  • taxonomy (str) – A non-custom taxonomy identifier (e.g. ‘us-gaap’, ‘ifrs-full’, ‘dei’, or ‘srt’).

  • tag (str) – The specific disclosure concept tag to retrieve, such as ‘AccountsPayableCurrent’ or ‘Assets’.

Returns:

An object containing all disclosures related to the specified concept, organized by units of measure.

Return type:

CompanyConcept

Example

>>> from edgar_sec import EdgarAPI
>>> api = EdgarAPI()
>>> # Get Apple Inc's Accounts Payable disclosure
>>> concept = api.get_company_concept("0000320193", "us-gaap", "AccountsPayableCurrent")
>>> for unit in concept.units:
>>>     print(f"Value: {unit.val}, Period: {unit.end}")

Note

This endpoint returns separate arrays of facts for each unit of measure that the company has disclosed (e.g., values reported in both USD and EUR).

get_company_facts(central_index_key)[source]

Retrieve all XBRL disclosures for a company in a single request.

Parameters:

central_index_key (str) – 10-digit Central Index Key (CIK) of the entity, including leading zeros. A CIK may be obtained at the SEC’s CIK lookup: https://www.sec.gov/search-filings/cik-lookup

Returns:

An object containing all facts and disclosures for the company, organized by taxonomy and concept.

Return type:

CompanyFact

Example

>>> from edgar_sec import EdgarAPI
>>> api = EdgarAPI()
>>> # Get all Apple Inc's financial disclosures
>>> facts = api.get_company_facts("0000320193")
>>> # Access a specific concept in the US GAAP taxonomy
>>> revenue = facts.facts["us-gaap"].disclosures.get("RevenueFromContractWithCustomerExcludingAssessedTax")
>>> if revenue and "USD" in revenue.units:
>>>     print(f"Latest revenue: ${revenue.units['USD'][0].val}")

Note

This is the most comprehensive endpoint, returning all concepts across all taxonomies for a company. The response can be quite large for companies with extensive filing histories.

get_frames(taxonomy, tag, unit, period)[source]

Retrieve aggregated XBRL facts across multiple companies for a specific period.

Parameters:

  • taxonomy (str) – A non-custom taxonomy identifier (e.g. ‘us-gaap’, ‘ifrs-full’, ‘dei’, or ‘srt’).

  • tag (str) – The specific disclosure concept tag to retrieve (e.g. ‘AccountsPayableCurrent’, ‘Assets’).

  • unit (str) – Unit of measurement for the requested data. Default is ‘pure’. Denominated units are separated by ‘-per-’ (e.g. ‘USD-per-shares’), non-denominated units are specified directly (e.g. ‘USD’).

  • period (str) – The reporting period in the format: Annual (365 days ±30 days): CY#### (e.g. ‘CY2019’), Quarterly (91 days ±30 days): CY####Q# (e.g. ‘CY2019Q1’), Instantaneous: CY####Q#I (e.g. ‘CY2019Q1I’).

Returns:

An object containing facts from multiple companies for the specified concept and period.

Return type:

Frame

Example

>>> from edgar_sec import EdgarAPI
>>> api = EdgarAPI()
>>> # Get all companies' Q1 2019 Accounts Payable data in USD
>>> frame = api.get_frames("us-gaap", "AccountsPayableCurrent", "USD", "CY2019Q1I")
>>> # Print the first few results
>>> for i, disclosure in enumerate(frame.data[:3]):
>>>     print(f"{disclosure.entity_name}: ${disclosure.val}")

Note

Due to varying company fiscal calendars, the frame data is assembled using the dates that best align with calendar periods. Be mindful that facts in a frame may have different exact reporting start and end dates.

get_submissions(central_index_key)[source]

Retrieve a company’s submission history from the SEC EDGAR database.

Parameters:

central_index_key (str) – 10-digit Central Index Key (CIK) of the entity, including leading zeros. A CIK may be obtained at the SEC’s CIK lookup: https://www.sec.gov/search-filings/cik-lookup

Returns:

An object containing the entity’s filing history,

including company information and recent filings.

Return type:

SubmissionHistory

Example

>>> from edgar_sec import EdgarAPI
>>> api = EdgarAPI()
>>> # Get Apple Inc's submission history
>>> apple_history = api.get_submissions("0000320193")
>>> print(apple_history.name)
'Apple Inc.'

Note

This endpoint returns the most recent 1,000 filings or at least one year’s worth, whichever is more. For entities with additional filings, the response includes references to additional JSON files and their date ranges.