Macrotrends — Financial Data Scraper

Scraper de Macrotrends que extrae datos financieros históricos: income statements, balance sheets, cash flow statements, financial ratios y employee count con hasta 15+ años de data para ~6,500 tickers de mercados US (NYSE, NASDAQ, AMEX), incluyendo ADRs internacionales de +30 países.

Los datos vienen en JSON embebido en la página (no requiere API key, solo requests + BeautifulSoup).

---

⚠️ Aviso Legal

• Macrotrends no tiene API pública oficial. Este scraper accede a datos públicamente disponibles en la web.
• Respetá los términos de servicio de Macrotrends.
• Implementá rate limiting (mín 2 segundos entre requests, recomendado 3s).
• El sitio puede cambiar su estructura HTML/JS, rompiendo el scraper.

---

Instalación

pip install requests beautifulsoup4

---

Scripts

Script	Descripción
fetch_financials.py	Script principal: statements, ratios, employees

---

Uso rápido

# Income statement anual
python scripts/fetch_financials.py --ticker NVDA --income

# Todo lo disponible (income + balance + cashflow + ratios + employees)
python scripts/fetch_financials.py --ticker AAPL --all

# Statements trimestrales
python scripts/fetch_financials.py --ticker MSFT --income --quarterly
python scripts/fetch_financials.py --ticker MSFT --balance --quarterly

# Ratios anuales o trimestrales
python scripts/fetch_financials.py --ticker NVDA --ratios
python scripts/fetch_financials.py --ticker GGAL --ratios --quarterly

# Employee count
python scripts/fetch_financials.py --ticker NVDA --employees

# Output a archivo JSON
python scripts/fetch_financials.py --ticker AAPL --all --output data.json

# Silencioso (solo JSON)
python scripts/fetch_financials.py --ticker NVDA --all --quiet

---

Endpoints disponibles

Flag	Data	Frecuencias	Períodos
--income	Income Statement	Anual, Trimestral	~15 años / ~60 quarters
--balance	Balance Sheet	Anual, Trimestral	~15 años / ~60 quarters
--cashflow	Cash Flow	Solo anual	~15 años
--ratios	Financial Ratios (20 ratios)	Anual, Trimestral	~15 años / ~60 quarters
--employees	Employee Count	Anual	~15 años
--all	Todos los anteriores	Según --quarterly	-

Flags adicionales

Flag	Descripción
--quarterly	Usa frecuencia trimestral (donde esté disponible)
--output	Archivo JSON de salida (default: stdout)
--slug	Slug manual (si el search no funciona)
--delay	Delay entre requests (default: 3.0s)
--quiet	Modo silencioso

---

Resolución ticker → slug

Macrotrends usa URLs con el formato /stocks/charts/{TICKER}/{SLUG}/financial-statements.

El slug se resuelve automáticamente via el search endpoint interno. Ejemplos:

Ticker	Slug
AAPL	apple
NVDA	nvidia
MSFT	microsoft
GGAL	grupo-financiero-galicia-sa
TSLA	tesla

Si el search falla, se puede pasar el slug manualmente:

python scripts/fetch_financials.py --ticker GGAL --slug grupo-financiero-galicia-sa --all

---

Datos disponibles por statement

Income Statement (22 campos)

Revenue, COGS, Gross Profit, R&D, SG&A, Operating Income, Net Income, EBITDA, EBIT, EPS, Shares Outstanding, etc.

Balance Sheet (23 campos)

Cash, Receivables, Inventory, Total Assets, Total Liabilities, Shareholders Equity, Debt, Retained Earnings, etc.

Cash Flow (29 campos)

Net Income, Depreciation, Working Capital Changes, Capex, Free Cash Flow, Dividends, Stock Repurchases, etc.

Financial Ratios (20 ratios)

Current Ratio, Debt/Equity, Gross/Operating/Net Margins, ROE, ROA, ROI, Book Value/Share, FCF/Share, etc.

Employee Count

Año a año, empleados totales.

Ver referencia completa de campos en references/STATEMENTS_REFERENCE.md.

---

Cobertura de Mercados

Macrotrends cubre ~6,500 tickers que cotizan en NYSE, NASDAQ y AMEX (incluyendo ADRs).

Tipo	Cantidad	Ejemplos
US Common Stocks	~5,300	AAPL, NVDA, MSFT
ADRs Internacionales	~276+	GGAL (Argentina), BABA (China), TM (Japón), PBR (Brasil), SAN (España), BP (UK)
ETFs & Fondos	~91	SPY, QQQ, VTI
Class A/B Shares	~22	BRK.A, BRK.B

Ver detalle completo de mercados, ADRs por país y cómo buscar tickers en references/MARKETS_REFERENCE.md.

---

Rate Limits

Comportamiento	Recomendación
Requests seguidos sin delay	429 Too Many Requests
Delay recomendado	3 segundos entre requests
Tickers por ejecución	~5-6 como máximo (para evitar bloqueo)
Backoff	Si recibís 429, esperá 30-60s

---

Errores comunes

Error	Causa	Solución
429 Too Many Requests	Rate limit	Aumentar --delay o esperar
slug not found	No se pudo resolver el ticker	Usar --slug manualmente
No data found for X	Endpoint no disponible	Verificar que el ticker existe en Macrotrends
originalData not found	Página cambió estructura	Reportar issue

---

Estructura del skill

skills/macrotrends/
├── SKILL.md                              # Este archivo
├── references/
│   ├── STATEMENTS_REFERENCE.md           # Referencia de campos
│   └── MARKETS_REFERENCE.md             # Cobertura de mercados y ADRs
└── scripts/
    └── fetch_financials.py               # Script principal