CompaniesMarketCap — Financial Rankings Scraper

Scraper de CompaniesMarketCap que extrae rankings financieros (market cap, earnings, revenue, employees, P/E, márgenes, activos, deuda, cash), marketcap histórico de stocks y ETF holdings.

Usa el sistema de CSV download nativo del sitio (?download=csv) — no requiere API key y es más mantenible que scrapear HTML.

---

⚠️ Aviso Legal

• CompaniesMarketCap no tiene API pública oficial. Usa el endpoint CSV que está públicamente disponible.
• Respetá los términos de servicio del sitio.
• Implementá rate limiting (mín 2 segundos entre requests).

---

Instalación

pip install requests beautifulsoup4

---

Scripts

Script	Descripción
fetch_cmc.py	Script principal: rankings, stock history, ETF holdings

---

Uso rápido

# Ranking de market cap (default)
python scripts/fetch_cmc.py --rankings

# Ranking de earnings
python scripts/fetch_cmc.py --rankings --metric earnings

# Ranking de revenue (top 10)
python scripts/fetch_cmc.py --rankings --metric revenue --limit 10

# Stock marketcap histórico
python scripts/fetch_cmc.py --stock NVDA
python scripts/fetch_cmc.py --stock GGAL

# ETF holdings
python scripts/fetch_cmc.py --etf SPY --holdings

# Todo junto + output a JSON
python scripts/fetch_cmc.py --stock AAPL --rankings --output aapl_full.json

# Modo silencioso (solo JSON)
python scripts/fetch_cmc.py --rankings --metric earnings --limit 5 --quiet

---

Endpoints

Flag	Data	Método	Detalle
--rankings	Ranking list	CSV download	12 métricas + ETFs, ~10,852 empresas
--stock TICKER	Marketcap histórico	HTML	28-31 años por stock
--etf TICKER --holdings	ETF holdings	HTML	~505 posiciones (SPY)
--etf TICKER	ETF summary	HTML	Información del ETF

Rankings disponibles (--metric)

Métrica	Descripción
marketcap (default)	Market Capitalization
earnings	Earnings (TTM)
revenue	Revenue (TTM)
employees	Employee count
pe_ratio	Price/Earnings ratio
operating_margin	Operating margin (TTM)
total_assets	Total assets
net_assets	Net assets
liabilities	Total liabilities
debt	Total debt
cash	Cash on hand
pb_ratio	Price/Book ratio
etfs	ETF market caps

---

Flags adicionales

Flag	Descripción
--limit N	Limitar a N filas en rankings
--output archivo.json	Guardar output a archivo
--delay N	Delay entre requests (default: 2.0s)
--quiet	Modo silencioso (solo JSON)

---

Resolución automática ticker → slug

El scraper resuelve automáticamente el slug de la URL a partir del nombre de la compañía en el CSV:

Ticker	Nombre → Slug
NVDA	NVIDIA → nvidia
AAPL	Apple → apple
GGAL	Galicia Financial Group → galicia-financial-group
SPY	SPDR S&P 500 ETF → spdr-sp-500-etf
BRK-B	Berkshire Hathaway → berkshire-hathaway

---

Estructura del skill

skills/companiesmarketcap/
├── SKILL.md                              # Este archivo
├── references/
│   └── REFERENCE.md                      # Documentación completa
└── scripts/
    └── fetch_cmc.py                      # Script principal

---

📖 Documentación detallada: Consultá references/REFERENCE.md para la documentación exhaustiva de cada endpoint, columnas, ejemplos y consideraciones técnicas.