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

bash

pip install secfi

Requiere

pandas

requests

(vienen con secfi).

Cómo funciona

La SEC expone datos financieros estructurados via dos endpoints JSON:

Endpoint	Descripción
Company Facts	`https://data.sec.gov/api/xbrl/companyfacts/CIK{CIK}.json` — Todos los datos XBRL
Company Concept	`https://data.sec.gov/api/xbrl/companyconcept/CIK{CIK}/us-gaap/{concept}.json` — Histórico de un concepto

El flujo típico:

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

Taxonomías soportadas

Taxonomía	Empresas	Formularios	Ejemplos
`us-gaap`	Empresas US	10-K, 10-Q	AAPL, MSFT, NVDA
`ifrs-full`	Empresas extranjeras (Foreign Private Issuers)	20-F, 6-K	GGAL, BABA, SAP, SPOT

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

Autenticación

python

HEADERS = {"User-Agent": "osojuanferpity@xmail.com"}

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

secfi

usa internamente.

Script principal:

fetch_financials.py

bash

# 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

Flag	Descripción
`--ticker` , `-t`	Ticker a consultar (requerido)
`--all`	Fetch de income + balance + cashflow
`--income`	Solo income statement
`--balance`	Solo balance sheet
`--cashflow`	Solo cash flow statement
`--all-concepts`	Todos los conceptos disponibles en la taxonomía (default: solo core)
`--annual`	Solo datos anuales (default)
`--quarterly`	Incluir datos trimestrales
`--output` , `-o`	Prefijo de archivos de salida
`--quiet` , `-q`	Sin salida detallada

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:

US-GAAP	IFRS (ifrs-full)
`Revenues`	`RevenueAndOperatingIncome`
`OperatingIncomeLoss`	`ProfitLossFromOperatingActivities`
`NetIncomeLoss`	`ProfitLoss`
`StockholdersEquity`	`Equity`
`NetCashProvidedByUsedInOperatingActivities`	`CashFlowsFromUsedInOperatingActivities`

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

Límite	Comportamiento
~10 req/s	Límite SEC
Sin API key	Público, requiere User-Agent con email
Datos históricos	No cambian — cachear respuestas

Errores comunes

Error	Causa	Solución
`403 Forbidden`	User-Agent inválido	Usar `osojuanferpity@xmail.com`
`404 Not Found`	CIK incorrecto	Verificar con `secfi.getCiks()`
`Ticker not found`	No está en SEC	Solo empresas que reportan a SEC
`KeyError: us-gaap`	Usa IFRS	El script lo resuelve automáticamente

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

sec-data

NPX Install

Tags

SKILL.md Content