/macrotrends

name: macrotrends
description: "Scraper de Macrotrends: financial statements, ratios, employee count con 15+ años de data histórica. Sin API key."
license: MIT

Macrotrends — Financial Data Scraper

Scraper de [Macrotrends](https://www.macrotrends.net/) 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](./scripts/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](./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](./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