alphavantage-api

Alpha Vantage API Integration

Financial data API providing stocks, forex, crypto, technical indicators, fundamental data, economic indicators, and AI-powered news sentiment analysis.

Quick Start

Authentication

# Environment variable (recommended)
export ALPHAVANTAGE_API_KEY="your_api_key"

# Or in .env file
ALPHAVANTAGE_API_KEY=your_api_key

Basic Usage (Python)

import requests
import os

API_KEY = os.getenv("ALPHAVANTAGE_API_KEY")
BASE_URL = "https://www.alphavantage.co/query"

def get_quote(symbol: str) -> dict:
    """Get real-time quote for a symbol."""
    response = requests.get(BASE_URL, params={
        "function": "GLOBAL_QUOTE",
        "symbol": symbol,
        "apikey": API_KEY
    })
    return response.json().get("Global Quote", {})

# Example
quote = get_quote("AAPL")
print(f"AAPL: ${quote['05. price']} ({quote['10. change percent']})")

Using Python Package

from alpha_vantage.timeseries import TimeSeries
from alpha_vantage.techindicators import TechIndicators

# Time series data
ts = TimeSeries(key=API_KEY, output_format='pandas')
data, meta = ts.get_daily(symbol='AAPL', outputsize='compact')

# Technical indicators
ti = TechIndicators(key=API_KEY, output_format='pandas')
rsi, meta = ti.get_rsi(symbol='AAPL', interval='daily', time_period=14)

API Functions Reference

Stock Time Series

Function	Description	Free
TIME_SERIES_INTRADAY	1-60min intervals	✅
TIME_SERIES_DAILY	Daily OHLCV	✅
TIME_SERIES_DAILY_ADJUSTED	With splits/dividends	⚠️ Premium
TIME_SERIES_WEEKLY	Weekly OHLCV	✅
TIME_SERIES_MONTHLY	Monthly OHLCV	✅
GLOBAL_QUOTE	Latest quote	✅
SYMBOL_SEARCH	Search symbols	✅

Fundamental Data

Function	Description	Free
OVERVIEW	Company overview	✅
INCOME_STATEMENT	Income statements	✅
BALANCE_SHEET	Balance sheets	✅
CASH_FLOW	Cash flow statements	✅
EARNINGS	Earnings history	✅
EARNINGS_CALENDAR	Upcoming earnings	✅
IPO_CALENDAR	Upcoming IPOs	✅

Forex

Function	Description	Free
CURRENCY_EXCHANGE_RATE	Real-time rate	✅
FX_INTRADAY	Intraday forex	✅
FX_DAILY	Daily forex	✅
FX_WEEKLY	Weekly forex	✅
FX_MONTHLY	Monthly forex	✅

Cryptocurrency

Function	Description	Free
CURRENCY_EXCHANGE_RATE	Crypto rate	✅
DIGITAL_CURRENCY_DAILY	Daily crypto	✅
DIGITAL_CURRENCY_WEEKLY	Weekly crypto	✅
DIGITAL_CURRENCY_MONTHLY	Monthly crypto	✅

Technical Indicators (50+)

Category	Indicators
Trend	SMA, EMA, WMA, DEMA, TEMA, KAMA, MAMA, T3, TRIMA
Momentum	RSI, MACD, STOCH, WILLR, ADX, CCI, MFI, ROC, AROON, MOM
Volatility	BBANDS, ATR, NATR, TRANGE
Volume	OBV, AD, ADOSC
Hilbert	HT_TRENDLINE, HT_SINE, HT_PHASOR, etc.

Economic Indicators

Function	Description	Free
REAL_GDP	US GDP	✅
CPI	Consumer Price Index	✅
INFLATION	Inflation rate	✅
UNEMPLOYMENT	Unemployment rate	✅
FEDERAL_FUNDS_RATE	Fed funds rate	✅
TREASURY_YIELD	Treasury yields	✅

Alpha Intelligence

Function	Description	Free
NEWS_SENTIMENT	AI sentiment analysis	✅
TOP_GAINERS_LOSERS	Market movers	✅
INSIDER_TRANSACTIONS	Insider trades	⚠️ Premium
ANALYTICS_FIXED_WINDOW	Analytics	⚠️ Premium

Rate Limits

Tier	Daily	Per Minute	Price
Free	25	5	$0
Premium	Unlimited	75-1,200	$49.99-$249.99/mo

Important: Rate limits are IP-based, not key-based.

Common Tasks

Task: Get Daily Stock Data

def get_daily_data(symbol: str, full: bool = False) -> dict:
    """Get daily OHLCV data."""
    response = requests.get(BASE_URL, params={
        "function": "TIME_SERIES_DAILY",
        "symbol": symbol,
        "outputsize": "full" if full else "compact",
        "apikey": API_KEY
    })
    return response.json().get("Time Series (Daily)", {})

# Example
data = get_daily_data("AAPL")
latest = list(data.items())[0]
print(f"{latest[0]}: Close ${latest[1]['4. close']}")

Task: Get Technical Indicator

def get_rsi(symbol: str, period: int = 14) -> dict:
    """Get RSI indicator values."""
    response = requests.get(BASE_URL, params={
        "function": "RSI",
        "symbol": symbol,
        "interval": "daily",
        "time_period": period,
        "series_type": "close",
        "apikey": API_KEY
    })
    return response.json().get("Technical Analysis: RSI", {})

# Example
rsi = get_rsi("AAPL")
latest_rsi = list(rsi.values())[0]["RSI"]
print(f"AAPL RSI(14): {latest_rsi}")

Task: Get Company Overview

def get_company_overview(symbol: str) -> dict:
    """Get comprehensive company information."""
    response = requests.get(BASE_URL, params={
        "function": "OVERVIEW",
        "symbol": symbol,
        "apikey": API_KEY
    })
    data = response.json()

    return {
        "name": data.get("Name"),
        "description": data.get("Description"),
        "sector": data.get("Sector"),
        "industry": data.get("Industry"),
        "market_cap": data.get("MarketCapitalization"),
        "pe_ratio": data.get("PERatio"),
        "dividend_yield": data.get("DividendYield"),
        "eps": data.get("EPS"),
        "52_week_high": data.get("52WeekHigh"),
        "52_week_low": data.get("52WeekLow"),
        "beta": data.get("Beta")
    }

Task: Get Forex Rate

def get_forex_rate(from_currency: str, to_currency: str) -> dict:
    """Get currency exchange rate."""
    response = requests.get(BASE_URL, params={
        "function": "CURRENCY_EXCHANGE_RATE",
        "from_currency": from_currency,
        "to_currency": to_currency,
        "apikey": API_KEY
    })
    return response.json().get("Realtime Currency Exchange Rate", {})

# Example
rate = get_forex_rate("USD", "EUR")
print(f"USD/EUR: {rate['5. Exchange Rate']}")

Task: Get Crypto Price

def get_crypto_price(symbol: str, market: str = "USD") -> dict:
    """Get cryptocurrency price."""
    response = requests.get(BASE_URL, params={
        "function": "CURRENCY_EXCHANGE_RATE",
        "from_currency": symbol,
        "to_currency": market,
        "apikey": API_KEY
    })
    data = response.json().get("Realtime Currency Exchange Rate", {})
    return {
        "symbol": symbol,
        "price": data.get("5. Exchange Rate"),
        "last_updated": data.get("6. Last Refreshed")
    }

# Example
btc = get_crypto_price("BTC")
print(f"BTC: ${float(btc['price']):,.2f}")

Task: Get News Sentiment

def get_news_sentiment(tickers: str = None, topics: str = None) -> list:
    """Get AI-powered news sentiment analysis."""
    params = {
        "function": "NEWS_SENTIMENT",
        "apikey": API_KEY
    }
    if tickers:
        params["tickers"] = tickers
    if topics:
        params["topics"] = topics

    response = requests.get(BASE_URL, params=params)
    return response.json().get("feed", [])

# Example
news = get_news_sentiment(tickers="AAPL")
for article in news[:3]:
    sentiment = article.get("overall_sentiment_label", "N/A")
    print(f"{article['title'][:50]}... [{sentiment}]")

Task: Get Economic Indicators

def get_economic_indicator(indicator: str) -> dict:
    """Get US economic indicator data."""
    response = requests.get(BASE_URL, params={
        "function": indicator,
        "apikey": API_KEY
    })
    return response.json()

# Examples
gdp = get_economic_indicator("REAL_GDP")
cpi = get_economic_indicator("CPI")
unemployment = get_economic_indicator("UNEMPLOYMENT")
fed_rate = get_economic_indicator("FEDERAL_FUNDS_RATE")

Task: Get Earnings Calendar

def get_earnings_calendar(horizon: str = "3month") -> list:
    """Get upcoming earnings releases."""
    import csv
    from io import StringIO

    response = requests.get(BASE_URL, params={
        "function": "EARNINGS_CALENDAR",
        "horizon": horizon,  # 3month, 6month, 12month
        "apikey": API_KEY
    })

    # Returns CSV format
    reader = csv.DictReader(StringIO(response.text))
    return list(reader)

# Example
earnings = get_earnings_calendar()
for e in earnings[:5]:
    print(f"{e['symbol']}: {e['reportDate']}")

Error Handling

def safe_api_call(params: dict) -> dict:
    """Make API call with error handling."""
    params["apikey"] = API_KEY

    try:
        response = requests.get(BASE_URL, params=params)
        data = response.json()

        # Check for rate limit
        if "Note" in data:
            print(f"Rate limit: {data['Note']}")
            return {}

        # Check for error message
        if "Error Message" in data:
            print(f"API Error: {data['Error Message']}")
            return {}

        # Check for information message (often rate limit)
        if "Information" in data:
            print(f"Info: {data['Information']}")
            return {}

        return data

    except Exception as e:
        print(f"Request error: {e}")
        return {}

Free vs Premium Features

Free Tier Includes

• 25 requests per day
• 5 requests per minute
• Historical time series (20+ years)
• 50+ technical indicators
• Fundamental data
• Forex and crypto
• Economic indicators
• News sentiment

Premium Required

• Unlimited daily requests
• Adjusted time series
• Realtime US market data
• 15-minute delayed data
• Insider transactions
• Advanced analytics
• Priority support

Best Practices

1. Cache responses - Data doesn't change frequently
2. Use compact outputsize - Unless you need full history
3. Batch requests wisely - 25/day limit is strict
4. Handle rate limits - Check for "Note" key in response
5. Use pandas output - With alpha_vantage package
6. Store historical data - Avoid re-fetching same data

Installation

# Official Python wrapper
pip install alpha_vantage pandas

# For async support
pip install aiohttp

Usage with Pandas

from alpha_vantage.timeseries import TimeSeries
from alpha_vantage.techindicators import TechIndicators
import pandas as pd

# Initialize with pandas output
ts = TimeSeries(key=API_KEY, output_format='pandas')
ti = TechIndicators(key=API_KEY, output_format='pandas')

# Get daily data
data, meta = ts.get_daily(symbol='AAPL', outputsize='compact')

# Get indicators
sma, _ = ti.get_sma(symbol='AAPL', interval='daily', time_period=20)
rsi, _ = ti.get_rsi(symbol='AAPL', interval='daily', time_period=14)

# Combine
analysis = data.join([sma, rsi])

Related Skills

• finnhub-api - Real-time quotes and news
• twelvedata-api - More indicators, better rate limits
• fmp-api - Fundamental analysis focus

References

• Official Documentation
• Python Package
• API Support