secblast 0.1.8

Python SDK for the SecBlast SEC Filing API

SecBlast Python SDK

Python SDK for the SecBlast SEC Filing API.

Installation

pip install secblast

Quick Start

from secblast import SecBlastClient

# Initialize the client
client = SecBlastClient(api_key="your-api-key")

# Look up a company
entity = client.get_entity(ticker="AAPL")
print(f"{entity.name} (CIK: {entity.cik})")

# Search filings
filings = client.lookup_filings(
    tickers=["AAPL"],
    form_types=["10-K"],
    date_from="2023-01-01",
)
print(f"Found {filings.count} filings")

# Full-text search
results = client.fulltext_search(
    "material contract",
    form_types=["8-K"],
)
for hit in results.hits:
    print(f"{hit.accession_number}: {hit.text_content[:100]}...")

# Get financial data
balance_sheet = client.get_balance_sheet(cik="320193")

Async Support

import asyncio
from secblast import AsyncSecBlastClient

async def main():
    async with AsyncSecBlastClient(api_key="your-api-key") as client:
        entity = await client.get_entity(ticker="AAPL")
        print(entity.name)

asyncio.run(main())

API Reference

Entity Lookup

# Search entities with filters
entities = client.lookup_entities(
    tickers=["AAPL", "MSFT"],
    exchanges=["NASDAQ"],
    sics=["3571"],  # Electronic Computers
    name_includes=["tech"],
)

# Get single entity
entity = client.get_entity(ticker="AAPL")
entity = client.get_entity(cik="320193")

Filing Lookup

# Search filings
filings = client.lookup_filings(
    tickers=["AAPL"],
    form_types=["10-K", "10-Q"],
    date_from="2023-01-01",
    date_to="2023-12-31",
    exclude_amendments=True,
    sort_by="filing_date",
    sort_order="desc",
)

# Get detailed filing info
detail = client.get_filing_info("0000320193-23-000077")
print(detail.filing.form_type)
print(len(detail.documents))

# Get 10-K/10-Q sections
sections = client.get_filing_sections(document_id, form_type="10-K")
for section in sections:
    print(f"{section.id}: {section.name}")

# Batch fetch 8-K items
items = client.get_8k_items([
    "0001829126-25-010357",
    "0001213900-25-126699",
])

Full-Text Search

# Standard search
results = client.fulltext_search("revenue growth")

# Exact phrase
results = client.fulltext_search(
    "material contract",
    query_type="match_phrase",
)

# Lucene query syntax
results = client.fulltext_search(
    "revenue AND NOT loss",
    query_type="query_string",
)

# With filters
results = client.fulltext_search(
    "merger agreement",
    ciks=["320193"],
    form_types=["8-K"],
    date_from="2023-01-01",
    sort_by="_score",  # Sort by relevance
)

Documents

# Get raw document content
content = client.get_document(document_id)  # Returns bytes

# Get as JSON
doc = client.get_document(document_id, output_format="json")
print(doc.file_name, doc.content_type)

# Generate PDF
pdf_bytes = client.get_pdf(document_id=document_id)
# Or entire filing
pdf_bytes = client.get_pdf(accession_number="0000320193-23-000077")

Financial Data

# Get financial statements
balance_sheet = client.get_balance_sheet(cik="320193")
income_stmt = client.get_income_statement(cik="320193")
cash_flow = client.get_cash_flow(cik="320193")

# Get raw XBRL data
raw = client.get_raw_financials(cik="320193")

# List available filings
filings = client.list_financial_filings(cik="320193")

# Get historical data for a concept
history = client.get_financial_history(cik="320193", concept="us-gaap:Revenue")

# Export to Excel
xlsx_bytes = client.export_financials_excel(cik="320193")
with open("financials.xlsx", "wb") as f:
    f.write(xlsx_bytes)

Error Handling

from secblast import (
    SecBlastClient,
    AuthenticationError,
    RateLimitError,
    ValidationError,
)

client = SecBlastClient(api_key="your-api-key")

try:
    entity = client.get_entity(ticker="AAPL")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limit exceeded: {e.limit_type}")
except ValidationError as e:
    print(f"Invalid request: {e.message}")

License

MIT