alpha-vantage

name	alpha-vantage
description	API de datos financieros de EE.UU.: acciones, forex, crypto, indicadores técnicos, fundamental data.
license	MIT

Alpha Vantage — Financial Data API

⚠️ IMPORTANTE: Requiere API Key gratuita. Ver sección de Autenticación.

API de datos financieros con cobertura global (20+ bolsas, 200,000+ tickers).

Base URL: https://www.alphavantage.co/query
Documentación completa: alphavantage.co/documentation

---

Autenticación

Obtener API Key (GRATIS)

1. Ir a: https://www.alphavantage.co/support/#api-key
2. Completar el formulario (email, nombre, tipo de uso)
3. Recibir key instantáneamente por email
4. No requiere tarjeta de crédito

Usar la API Key

import os
API_KEY = os.getenv("ALPHAVANTAGE_API_KEY")  # Recomendado
# o directamente:
API_KEY = "TU_API_KEY_AQUI"

⚠️ NUNCA hardcodear la API key en código que se va a compartir/commits.

---

Rate Limits

Plan	Requests/Día	Requests/Minuto	Precio
Free	25	5	$0
Standard	∞	75	$49.99/mes
Premium	∞	150	$99.99/mes
Enterprise	∞	1,200	$249.99/mes

Recomendaciones para Free Tier

• Cachear respuestas — los datos no cambian frecuentemente
• Usar outputsize=compact — retorna últimos 100 datos (gratis)
• No hacer llamadas en cada request de usuario
• Esperar 12+ segundos entre requests (5 req/min máximo)

Si llegás al límite

El API retorna:

{
  "Error Message": "Thank you for using Alpha Vantage! Our standard API call frequency is 5 requests per minute and 25 requests per day. Please subscribe to a premium plan for higher API call volume."
}

---

Endpoints Disponibles

Time Series — Acciones (Free Tier)

Function	Descripción	Notas
TIME_SERIES_DAILY	OHLCV diario	⚠️ Solo compact (100 datos)
TIME_SERIES_WEEKLY	OHLCV semanal	Full history
TIME_SERIES_MONTHLY	OHLCV mensual	Full history
GLOBAL_QUOTE	Quote último precio	Rápido
SYMBOL_SEARCH	Buscar símbolos

Time Series — PREMIUM

Function	Descripción
TIME_SERIES_INTRADAY	Datos intraday (1/5/15/30/60 min)
TIME_SERIES_DAILY_ADJUSTED	Con splits/dividendos
outputsize=full	Historia completa (20+ años)

Fundamental Data (Free Tier)

Function	Descripción
OVERVIEW	Company overview
INCOME_STATEMENT	Estado de resultados
BALANCE_SHEET	Balance general
CASH_FLOW	Flujo de caja
EARNINGS	Ganancias históricas

Forex (Free Tier)

Function	Descripción
CURRENCY_EXCHANGE_RATE	Tipo de cambio actual
FX_INTRADAY	Intraday forex
FX_DAILY	Forex diario
FX_WEEKLY	Forex semanal
FX_MONTHLY	Forex mensual

Cryptocurrency (Free Tier)

Function	Descripción
CURRENCY_EXCHANGE_RATE	Crypto vs fiat
DIGITAL_CURRENCY_DAILY	Crypto diario
DIGITAL_CURRENCY_WEEKLY	Crypto semanal
DIGITAL_CURRENCY_MONTHLY	Crypto mensual

Technical Indicators (50+ Free Tier)

Ver lista completa en ./references/indicators.md:

Categoría	Indicadores
Trend	SMA, EMA, WMA, DEMA, TEMA, KAMA, etc.
Momentum	RSI, MACD, STOCH, WILLR, ADX, CCI, etc.
Volatility	BBANDS, ATR, NATR, TRANGE
Volume	OBV, AD, ADOSC

Economic Indicators (Free Tier)

Function	Descripción
REAL_GDP	PIB de EE.UU.
CPI	Índice de Precios al Consumidor
INFLATION	Tasa de inflación
UNEMPLOYMENT	Tasa de desempleo
FEDERAL_FUNDS_RATE	Tasa de fondos federales
TREASURY_YIELD	Rendimientos del tesoro

Alpha Intelligence (Free Tier)

Function	Descripción	Notas
NEWS_SENTIMENT	Análisis de sentimiento	Free
TOP_GAINERS_LOSERS	Mejores/peores	Free
INSIDER_TRANSACTIONS	Transacciones insiders	⚠️ PREMIUM
ANALYTICS_FIXED_WINDOW	Analytics avanzado	⚠️ PREMIUM

---

Ejemplos de Uso

Quote actual (más simple)

import requests

url = "https://www.alphavantage.co/query"
params = {
    "function": "GLOBAL_QUOTE",
    "symbol": "AAPL",
    "apikey": API_KEY
}
r = requests.get(url, params=params)
quote = r.json()["Global Quote"]
print(f"AAPL: ${quote['05. price']}")

Time Series Diario

params = {
    "function": "TIME_SERIES_DAILY",
    "symbol": "IBM",
    "outputsize": "compact",  # últimos 100 días (free)
    "apikey": API_KEY
}
r = requests.get(url, params=params)
data = r.json()["Time Series (Daily)"]

Indicador Técnico (RSI)

params = {
    "function": "RSI",
    "symbol": "IBM",
    "interval": "daily",
    "time_period": 14,
    "apikey": API_KEY
}

Forex

params = {
    "function": "CURRENCY_EXCHANGE_RATE",
    "from_currency": "BTC",
    "to_currency": "USD",
    "apikey": API_KEY
}

---

Scripts de Descarga

Usá los scripts en ./scripts/:

# Descargar quotes de múltiples símbolos
python ./scripts/download_quotes.py --symbols AAPL,GOOGL,MSFT --output data/

# Descargar time series diarios
python ./scripts/download_timeseries.py --symbol AAPL --output data/

# Descargar indicadores técnicos
python ./scripts/download_indicators.py --symbol AAPL --indicator RSI --output data/

---

Errores Comunes

Error	Causa	Solución
"5 requests per minute"	Rate limit	Esperar 12+ segundos
"25 requests per day"	Daily limit	Esperar 24 horas o upgrade
"Invalid API call"	Symbol no existe	Usar SYMBOL_SEARCH primero
"premium" en response	Endpoint premium	Usar alternativa free o upgrade