alterlab-alpha-vantage

Alpha Vantage — 金融市场数据

访问 20 多年的全球金融数据：股票、期权、外汇、加密货币、大宗商品、经济指标、基本面、新闻情绪和 50 多种技术指标，全部通过一个 /query 端点获取。

何时使用此技能

• 获取某个股票代码、外汇货币对或加密资产的 OHLCV 历史价格或最新报价
• 获取预先计算的公司基本面数据（概览比率、报表、收益、股息、拆股）
• 在服务端计算技术指标（SMA、EMA、RSI、BBANDS……）
• 获取大宗商品价格或美国主要宏观经济序列（GDP、CPI、收益率、失业率）
• 获取用于事件研究的新闻情绪、财报电话会议文字稿或内部人交易数据

不适用的情况

场景	改用
使用 FRED ID（UNRATE、GDPC1）的宏观经济序列、服务端 pc1 转换、ALFRED 历史版本	alterlab-fred
来自实际 10-K/10-Q 的行项目、XBRL 事实、SEC EDGAR 的 Form 4/13F 文件	alterlab-edgartools
精确到美分的国债债务、每日/每月财政部报表、拍卖结果	alterlab-usfiscaldata
对冲基金杠杆总量 / SEC Form PF 统计数据	alterlab-hedgefund-monitor
为已下载的序列拟合 ARIMA/回归模型	alterlab-statsmodels

API 密钥设置（必需）

1. 在 https://www.alphavantage.co/support/#api-key 获取免费密钥（高级套餐可提高限额并解锁高级端点）
2. 将其设置为环境变量：

export ALPHAVANTAGE_API_KEY="your_key_here"

如果已配置 Alpha Vantage MCP 连接器（Alpha Vantage 运行官方 MCP 服务，参见 https://mcp.alphavantage.co/），实时查询时优先使用该连接器；以下 REST 请求模式适用于所有场景。

安装

uv pip install requests pandas

基础 URL 和请求模式

所有请求都发送至：

https://www.alphavantage.co/query?function=FUNCTION_NAME&apikey=YOUR_KEY&...params

import os
import requests

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

def av_get(function, **params):
    response = requests.get(BASE_URL, params={"function": function, "apikey": API_KEY, **params}, timeout=30)
    response.raise_for_status()
    data = response.json()
    # Alpha Vantage reports errors and limit hits with HTTP 200 + one of these keys
    for key in ("Error Message", "Information", "Note"):
        if key in data:
            raise RuntimeError(f"Alpha Vantage {key}: {data[key]}")
    return data

快速入门示例

# Stock quote (latest price; end-of-day unless you have a realtime entitlement)
quote = av_get("GLOBAL_QUOTE", symbol="AAPL")
price = quote["Global Quote"]["05. price"]

# Daily OHLCV: compact = latest 100 points (free); outputsize="full" (25+ years) is premium-only
daily = av_get("TIME_SERIES_DAILY", symbol="AAPL", outputsize="compact")
ts = daily["Time Series (Daily)"]

# Company fundamentals
overview = av_get("OVERVIEW", symbol="AAPL")
print(overview["MarketCapitalization"], overview["PERatio"])

# Income statement
income = av_get("INCOME_STATEMENT", symbol="AAPL")
annual = income["annualReports"][0]  # Most recent annual

# Crypto price
crypto = av_get("DIGITAL_CURRENCY_DAILY", symbol="BTC", market="USD")

# Economic indicator
gdp = av_get("REAL_GDP", interval="annual")

# Technical indicator
rsi = av_get("RSI", symbol="AAPL", interval="daily", time_period=14, series_type="close")

API 类别

类别	主要函数
时间序列（股票）	GLOBAL_QUOTE、TIME_SERIES_INTRADAY*、TIME_SERIES_DAILY、TIME_SERIES_DAILY_ADJUSTED*、TIME_SERIES_WEEKLY(_ADJUSTED)、TIME_SERIES_MONTHLY(_ADJUSTED)、REALTIME_BULK_QUOTES*、MARKET_STATUS、SYMBOL_SEARCH
指数数据	INDEX_DATA*、INDEX_CATALOG*
期权	REALTIME_OPTIONS*、HISTORICAL_OPTIONS*（以及看跌看涨比率和成交量/OI 比率端点）
Alpha Intelligence	NEWS_SENTIMENT、EARNINGS_CALL_TRANSCRIPT、TOP_GAINERS_LOSERS、INSIDER_TRANSACTIONS、INSTITUTIONAL_HOLDINGS、ANALYTICS_FIXED_WINDOW、ANALYTICS_SLIDING_WINDOW
基本面	OVERVIEW、ETF_PROFILE、INCOME_STATEMENT、BALANCE_SHEET、CASH_FLOW、SHARES_OUTSTANDING、EARNINGS、EARNINGS_ESTIMATES、DIVIDENDS、SPLITS、LISTING_STATUS、EARNINGS_CALENDAR、IPO_CALENDAR
外汇（FX）	CURRENCY_EXCHANGE_RATE、FX_INTRADAY*、FX_DAILY、FX_WEEKLY、FX_MONTHLY
加密货币	CURRENCY_EXCHANGE_RATE、CRYPTO_INTRADAY*、DIGITAL_CURRENCY_DAILY/WEEKLY/MONTHLY
大宗商品	WTI、BRENT、NATURAL_GAS、COPPER、ALUMINUM、WHEAT、CORN、COTTON、SUGAR、COFFEE、GOLD_SILVER_SPOT、GOLD_SILVER_HISTORY、ALL_COMMODITIES
经济指标	REAL_GDP、REAL_GDP_PER_CAPITA、TREASURY_YIELD、FEDERAL_FUNDS_RATE、CPI、INFLATION、RETAIL_SALES、DURABLES、UNEMPLOYMENT、NONFARM_PAYROLL
技术指标	SMA、EMA、MACD*、RSI、BBANDS、STOCH、ADX、ATR、OBV、VWAP*，以及另外 40 多种

* 仅限高级套餐（依据实时文档，检查日期为 2026-09-23）。免费函数中受高级套餐限制的参数：TIME_SERIES_DAILY 的 outputsize=full，以及报价接口中的 entitlement=realtime|delayed。

常用参数

参数	值	说明
outputsize	compact / full	compact = 最近 100 个数据点；full = 20 年以上（TIME_SERIES_DAILY 需付费）
datatype	json / csv	默认值：json
interval	1min、5min、15min、30min、60min、daily、weekly、monthly	取决于端点
adjusted	true / false	根据拆股/股息进行调整
entitlement	realtime / delayed	需付费；获取历史/日终数据时请省略

速率限制和套餐等级

• 免费密钥：每天 25 次请求。 循环查询多个代码前，请先规划调用次数——30 个股票代码会耗尽每日配额。将响应缓存到磁盘并重复使用。
• 高级套餐按每分钟请求次数售卖（75 至 1,200 次/分钟），并解锁上述带星号的函数。
• 达到限制和发生错误时，返回的 HTTP 200 中会包含 Information（较旧的响应中为 Note）或 Error Message 键，而不是数据。因此，请检查 JSON 正文，而非状态码；上面的 av_get 辅助函数会对此类情况报错。

错误处理

try:
    data = av_get("GLOBAL_QUOTE", symbol="AAPL")
except RuntimeError as err:
    # "Information" usually means the daily quota is used up or the call needs a premium key;
    # "Error Message" usually means a bad function/parameter/symbol.
    print(err)

参考文件

加载以下文件以查看详细的端点文档：

• time-series.md — 股票 OHLCV 数据、报价、批量报价、市场状态
• fundamentals.md — 公司概况、财务报表、收益、股息、拆股
• options.md — 实时和历史期权链数据
• intelligence.md — 新闻/情绪、收益电话会文字稿、内幕交易、分析数据
• forex-crypto.md — 外汇汇率和加密货币价格
• commodities.md — 黄金、白银、石油、天然气、农产品
• economic-indicators.md — GDP、CPI、利率、就业数据
• technical-indicators.md — 50 多种技术分析指标（SMA、EMA、MACD、RSI 等）

在论文或报告中使用任何数值时，请注明 Alpha Vantage 和数据获取日期。

AlterLab Academic Skills 套件的一部分。