hub-equity: Python SDK

Typed Python client for the Hub-Equity financial-data API: machine-readable XBRL / iXBRL from primary filings, SEC EDGAR (US) and ESEF (Europe), normalized into canonical financial concepts, with the provenance preserved.

What sets the data apart, and what this SDK exposes:

• Source-linked. Every value carries the filing it came from (form_type, filing_date, a viewer URL). You can trace any number back to the filer's document, not a black box that silently rewrites as-filed history.
• Point-in-time. Query a metric as it was known on a date (get_metric_as_of): filings filed after the cutoff are excluded. No lookahead bias for backtests.
• XBRL-native. Calculation linkbase (with filer weights and verifier-corrected weights), dimensional structure, and the raw filer-declared facts, not just flattened labels.
• Restatement-aware. Per-concept deltas across 10-K/A amendments.
• Cross-issuer, calendar-aligned. compare matches periods by calendar year (Bloomberg / FactSet convention), so Apple (Sep FYE) and a Dec-FYE peer line up.

The SDK is a thin, typed wrapper over the public REST API: it ships no data and no secrets; you bring your own API key. Full API reference: https://docs.hub-equity.com.

Maturity. The data engine and public REST API behind this SDK run in production and power Hub-Equity's own chat. This PyPI package is a newly published client for that API; the surface is stable (SemVer 1.0), but as a distributed package it is fresh, hence the Beta classifier.

Install

pip install hub-equity
# Optional pandas helpers:
pip install 'hub-equity[pandas]'

Python 3.10+. Runtime deps: httpx, pydantic.

Authentication

from hub_equity import HubEquity

# Explicit key
client = HubEquity(api_key="hubq_live_...")

# Or set HUBEQUITY_API_KEY env var (recommended for notebooks)
client = HubEquity()

# Or no key: anonymous freemium access (lower rate limits, premium endpoints gated)
client = HubEquity(api_key="")

Get a key at https://hub-equity.com/settings/api-keys (shown once, store it securely). Set HUBEQUITY_API_URL to point the client at a non-default host (defaults to https://api.hub-equity.com).

Entity arguments accept a ticker (e.g. "AAPL") or a Hub-Equity UUID on every entities/{id}/... method. The one exception is compare, which takes UUIDs only (resolve a ticker via the entity detail endpoint or the web app first).

Quickstart

from hub_equity import HubEquity

with HubEquity() as client:
    rev = client.get_metric_history("AAPL", "REVENUE", years=5)
    print(f"{rev.entity_name}: {rev.hub_label} (CAGR {rev.cagr_pct:.1f}%)")
    for p in rev.points:
        print(f"  FY{p.fiscal_year}: {p.value:,.0f} {p.currency}"
              f"  ({p.yoy_growth_pct:+.1f}% YoY)  ← {p.source.form_type} {p.source.filing_date}")
        # p.source.viewer_url / p.source.external_url -> trace back to the filing

Methods

Every method returns a typed pydantic model (autocomplete + validation), with extra="allow" so a newer API never breaks an older SDK.

Point-in-time: no lookahead bias

# What did Apple's FY2022 revenue look like as known on 2023-01-15,
# before any later 10-K/A restated it?
snap = client.get_metric_as_of("AAPL", "REVENUE", as_of="2023-01-15", years=3)
for p in snap.points:
    print(f"FY{p.fiscal_year}: {p.value:,.0f} {p.currency}"
          f"  (from {p.form_type} filed {p.filing_date})")

Compare issuers (calendar-year aligned, premium)

# compare takes UUIDs; resolve tickers first (entity detail endpoint / web app).
matrix = client.compare(
    entity_ids=["<apple-uuid>", "<msft-uuid>"],
    hub_concept_codes=["REVENUE", "NET_INCOME"],
    fiscal_year=2024,
)
for row in matrix.rows:
    cell = row.cells.get("REVENUE")
    if cell:
        print(f"{row.name} ({row.ticker}): {cell.value:,.0f} {cell.currency}"
              f"  [{cell.extraction_method}]")

Audit a number to its filing

# Filing-level quality pre-screen
grade = client.get_filing_quality_grade("<filing-uuid>")
print(grade.letter_grade, grade.overall_score)
for d in grade.drivers:
    print(f"  {d.name}: {d.score:.2f} (w={d.weight})")

# then drill to the raw filer-declared facts (qname, unit, decimals, dimensions).
facts = client.get_filing_facts("<filing-uuid>", concept="Revenue", limit=50)
for f in facts.facts:
    print(f.concept_qname, f.value_numeric, f.unit, f.dimensions)

pandas

import pandas as pd

hist = client.get_metric_history("MSFT", "REVENUE", years=10)
df = pd.DataFrame([p.model_dump() for p in hist.points])
df["source_form"] = [p.source.form_type for p in hist.points]

Reliability

• Retries 429 (rate limit) + 5xx (server) with exponential backoff (3 retries, base 1 s, cap 10 s); honors Retry-After when present.
• After exhausting retries on 429, raises RateLimitError (subclass of HubEquityError) with the last retry_after attached.
• Other 4xx raise HubEquityError immediately (no retries), with .status_code.

from hub_equity import HubEquity, HubEquityError, RateLimitError

with HubEquity() as client:
    try:
        rev = client.get_metric_history("AAPL", "REVENUE")
    except RateLimitError as exc:
        print(f"Rate-limited, retry after {exc.retry_after}s")
    except HubEquityError as exc:
        print(f"{exc.status_code}: {exc}")

Rate limits

Bucketed per API key (per JWT user, or per IP for anonymous callers). Premium endpoints (compare, point-in-time) require a Pro/Enterprise key.

Versioning

Semantic versioning. The 1.x surface is stable: no breaking change to an existing method or model without a major bump. Pin a version in production (hub-equity==1.0.0). Response models use extra="allow", so additive API changes ship in minor releases without breaking older SDK installs.

License

Apache-2.0. See LICENSE.