SEC Data — Financial Statements from SEC EDGAR

Acceso a datos financieros estructurados de la SEC EDGAR mediante la librería secfi + la API JSON de XBRL facts de la SEC.

Obtiene income statements, balance sheets, cash flow statements en formato JSON/CSV estructurado directamente de los filings XBRL.

Soporta US-GAAP (empresas US) e IFRS (empresas extranjeras) con mapping automático de conceptos.

Dependencia

pip install secfi

Requiere pandas y requests (vienen con secfi).

Cómo funciona

La SEC expone datos financieros estructurados via dos endpoints JSON:

El flujo típico:

1. secfi.getCiks() → obtiene el CIK del ticker
2. Fetch companyfacts/CIK{cik}.json → obtiene todos los datos financieros estructurados
3. El script mapea automáticamente conceptos US-GAAP ↔ IFRS según la taxonomía

Taxonomías soportadas

El script detecta automáticamente la taxonomía y resuelve los conceptos usando un mapping US-GAAP ↔ IFRS.

Autenticación

HEADERS = {"User-Agent": "[email protected]"}

La SEC bloquea requests sin User-Agent válido (403 Forbidden). Usar el mismo email que secfi usa internamente.

Script principal: fetch_financials.py

# AAPL (US-GAAP) — todo
python scripts/fetch_financials.py --ticker AAPL --all

# GGAL (IFRS) — todo
python scripts/fetch_financials.py --ticker GGAL --all

# Solo income statement
python scripts/fetch_financials.py --ticker MSFT --income

# Solo balance + cash flow
python scripts/fetch_financials.py --ticker NVDA --balance --cashflow

# Todos los conceptos disponibles (no solo core)
python scripts/fetch_financials.py --ticker AAPL --all --all-concepts

# Output personalizado
python scripts/fetch_financials.py --ticker AAPL --all --output data/aapl

# Solo anual (default)
python scripts/fetch_financials.py --ticker AAPL --all

# Incluir trimestral también
python scripts/fetch_financials.py --ticker AAPL --all --quarterly

Flags disponibles

Output generado

{ticker}_financials.json          → JSON completo con todos los conceptos
{ticker}_financials.csv           → CSV tabular aplanado (concepto x entry)
{ticker}_financials_income_annual.csv  → Matriz concepto x año (income)
{ticker}_financials_balance_annual.csv → Matriz concepto x año (balance)
{ticker}_financials_cashflow_annual.csv → Matriz concepto x año (cash flow)

Mapping IFRS automático

El script incluye un diccionario IFRS_MAP con 33+ conceptos US-GAAP mapeados a sus equivalentes IFRS. Por ejemplo:

Free Cash Flow (FCF)

El script calcula automáticamente el FCF:

FCF = Operating CF - CAPEX

Tanto para US-GAAP como IFRS.

Testeado con

AAPL (US-GAAP) — 55 conceptos extraídos ✅

>> Company facts: 4053 KB
>> Income: 13 conceptos x 17 años
>> Balance: 24 conceptos x 17 años
>> Cash flow: 18 conceptos x 17 años
>> FCF 2025: $98.7B

GGAL (IFRS) — 40 conceptos extraídos ✅

>> Company facts: 724 KB
>> Revenue: $7.72B (2024) · Net Income: $1.76B (2024)
>> Balance: Assets $35.3B · Equity $6.58B
>> Cash flow: Operating $3.80B · FCF $3.57B

Rate Limits

Errores comunes

Estructura del skill

skills/sec-data/
├── SKILL.md                           # Este archivo
├── references/
│   └── FINANCIALS_REFERENCE.md        # Referencia completa: todos los conceptos + mapping IFRS
└── scripts/
    └── fetch_financials.py            # Script principal con mapping IFRS automático