Basic Usage Examples#

This page shows how to quickly start using the edgar_sec package to interact with the SEC EDGAR® API. You’ll learn how to initialize a client, fetch submission history, extract XBRL facts, and look up tickers or CIKs.

If you’re new to edgar-sec, start here!

—

Getting Started#

Initialize the Client
import edgar_sec as ed
edgar = ed.EdgarAPI()

No API key needed — EDGAR data is public. See Advanced Usage Examples for async and caching options.

Fetch Submission History
submission_history = edgar.get_submissions(ticker="AAPL")
print(submission_history.filings[0].form, submission_history.filings[0].filing_date)

Retrieve the last 1,000+ SEC filings for a company. Returns a edgar_sec.objects.SubmissionHistory object.

Fetch Company XBRL Facts
facts = edgar.get_company_facts(ticker="AAPL")
revenue = facts.facts["us-gaap"].disclosures.get("RevenueFromContractWithCustomerExcludingAssessedTax")
if revenue and "USD" in revenue.units:
    print(f"Latest revenue: ${revenue.units['USD'][0].val}")

Load all tagged XBRL disclosures for a company. Access structured concepts via taxonomy and tag.

Get Company Concept
concept = edgar.get_company_concept(
    taxonomy="us-gaap",
    tag="Assets",
    ticker="MSFT"
)
print(concept.units[0].val)

Query a specific financial disclosure (e.g. Assets, Liabilities).

—

Helper Utilities#

Convert Ticker to CIK
results = ed.EdgarHelpers.get_cik(search="Tesla")
for match in results:
   print(match.name, match.cik)

Returns list of edgar_sec.objects.Company matches. Useful for mapping names or tickers to official identifiers.

Validate and Convert Period Strings
from datetime import datetime
from edgar_sec.helpers import EdgarHelpers

period = EdgarHelpers.datetime_cy_conversion(datetime(2022, 3, 1))
print(period)  # CY2022Q1

Used to construct correct period identifiers for frame queries.

—