Advanced Usage Examples#

edgar-sec enables high-throughput, resilient EDGAR® data pipelines. This page covers file caching, rate limiting, concurrent async requests, parameter customization, and error handling.

—

Advanced Client Features#

Caching and Rate Limiting

Automatically cache responses and throttle API requests to comply with EDGAR limits.

Caching and rate limiting documentation
Async Concurrent Requests

Fetch multiple endpoints concurrently using edgar_sec.EdgarAPI.Async.

Asynchronous requests using AsyncAPI
Parameter Customization

Use datetime, list, and string inputs seamlessly with auto-conversion.

API parameter formatting
Error Handling

Raise clear, typed exceptions for invalid inputs and failed requests.

Exception catching and validation

—

Caching and Rate Limiting#

See Example
import edgar_sec as ed

edgar = ed.EdgarAPI(cache_mode=True, cache_size=512)

submission = edgar.get_submissions(ticker="MSFT")
print(submission.entity_type)

# Cached if repeated:
filing = edgar.get_company_facts("AAPL")

edgar-sec enforces the 10 requests per second SEC limit and supports file-based caching.

—

Concurrent Requests with Async#

See Example
import edgar_sec as ed
import asyncio

async def fetch_all():
    edgar = ed.EdgarAPI().Async
    tickers = ["AAPL", "TSLA", "MSFT"]
    tasks = [edgar.get_submissions(ticker=t) for t in tickers]
    results = await asyncio.gather(*tasks)

    for result in results:
        print(result.name, len(result.filings))

asyncio.run(fetch_all())

Perfect for data collection pipelines and bulk processing.

—

Customizing API Requests#

See Example
from datetime import datetime
import edgar_sec as ed

edgar = ed.EdgarAPI()
frame = edgar.get_frames(
    taxonomy="us-gaap",
    tag="RevenueFromContractWithCustomerExcludingAssessedTax",
    unit="USD",
    period=datetime(2022, 3, 31),
    instantaneous=True
)
print(frame.data[0].entity_name, frame.data[0].val)

Use datetime, CIKs, or tickers — edgar-sec converts and validates them for you.

—

Error Handling and Validation#

See Example
import edgar_sec as ed

edgar = ed.EdgarAPI()

try:
    edgar.get_submissions(ticker=None)
except ValueError as e:
    print("Validation error:", e)

try:
    edgar.get_company_concept("us-gaap", "InvalidTag", ticker="AAPL")
except Exception as e:
    print("API error:", e)

Descriptive error messages help you debug quickly.

—