stoxim-api 1.0.0

Python SDK for the Stoxim API — company master, financials, ratios, shareholding, governance, announcements, and more.

stoxim-api

Official Python SDK for the Stoxim Financial Data API — company master, financials, ratios, shareholding patterns, corporate actions, governance, and announcements for BSE/NSE-listed companies.

Installation

pip install stoxim-api

Requires Python 3.10+.

Quick Start

from stoxim import Client

client = Client(api_key="sk_live_your_key_here")

# ── Company lookup ─────────────────────────────────────────────────────────────
company = client.company.get("INE040A01034")
print(company.name, company.sector)
# HDFC Bank  Financial Services

# ── Search ─────────────────────────────────────────────────────────────────────
results = client.company.search("Bajaj Finance", limit=5)
for c in results.items:
    print(c.isin, c.name)

# ── Financial periods ──────────────────────────────────────────────────────────
periods = client.financials.list("INE040A01034", period_type="annual", limit=5)
for p in periods.items:
    print(p.period_label, p.revenue, p.pat)

# ── Ratios ─────────────────────────────────────────────────────────────────────
ratios = client.ratios.get("INE040A01034", period_type="annual")
for r in ratios:
    print(r.period_label, r.roe, r.gross_margin, r.pe_ratio)

# ── Shareholding pattern ───────────────────────────────────────────────────────
patterns = client.shareholding.list("INE040A01034")
for s in patterns.items:
    print(s.period_end, s.promoter_pct, s.fii_pct)

# ── Corporate actions ──────────────────────────────────────────────────────────
actions = client.corporate_actions.list("INE040A01034", action_type="dividend")
for a in actions.items:
    print(a.ex_date, a.dividend_amount)

# ── Board composition (Starter+ plan) ─────────────────────────────────────────
board = client.governance.board("INE040A01034")
for member in board:
    print(member.name, member.designation)

# ── AGM records ────────────────────────────────────────────────────────────────
agm_records = client.governance.agm("INE040A01034")

# ── Related-party transactions ─────────────────────────────────────────────────
rpts = client.governance.related_party_transactions("INE040A01034")

# ── Announcements ──────────────────────────────────────────────────────────────
announcements = client.announcements.list(
    "INE040A01034",
    category="financials",
    from_date="2024-01-01",
)
for ann in announcements.items:
    print(ann.filing_date, ann.subject)

Pagination

# Paginate through all large-cap companies
for page in client.company.paginate(market_cap_category="large"):
    for company in page:
        print(company.isin, company.name)

Context Manager

with Client(api_key="sk_live_...") as client:
    company = client.company.get("INE040A01034")
# Connection is closed automatically

Error Handling

from stoxim import (
    AuthenticationError,
    NotFoundError,
    PlanRestrictionError,
    RateLimitError,
    InvalidParameterError,
    ApiError,
)

try:
    company = client.company.get("INVALID_ISIN")
except NotFoundError as e:
    print(f"Not found: {e.message}")
except PlanRestrictionError:
    print("Upgrade your plan to access this endpoint")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
except ApiError as e:
    print(f"Unexpected error [{e.error_code}]: {e.message}")

Configuration

client = Client(
    api_key="sk_live_...",
    timeout=60,          # seconds (default: 30)
    max_retries=5,       # includes initial attempt (default: 3)
    retry_on_429=True,   # respect Retry-After header on 429 (default: True)
)

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint + format
ruff check src/ tests/
ruff format src/ tests/

# Build
pip install build
python -m build
twine check dist/*

License

MIT — see LICENSE.