twelvedata-api

Twelve Data API 集成技能简介

用途

本技能用于对接 Twelve Data 金融数据 API，为获取股票、外汇、加密货币、ETF、指数等金融数据，以及 100 多种技术指标提供统一的调用方式。适用于需要抓取时间序列数据、进行技术分析、获取基本面信息的场景。

主要能力

核心数据：实时报价（/quote）、当前价格（/price）、收盘价（/eod）、历史 OHLCV（/time_series）、货币换算（/exchange_rate）。
参考数据：代码搜索（/symbol_search）、全部标的列表（/instruments）、交易所列表（/exchanges）、标的类型（/instrument_type）、数据起始时间（/earliest_timestamp）。
基本面数据：利润表、资产负债表、现金流量表、盈利历史、盈利日历、股息历史、拆股历史、关键统计、公司简介。
技术指标：100 多种，涵盖趋势（SMA、EMA、WMA、DEMA、TEMA、KAMA、MAMA、T3、TRIMA、VWMA）、动量（RSI、MACD、随机指标、Williams %R、ADX、CCI、MFI、ROC、AROON）、波动率（布林带、ATR、Keltner 通道、Donchian）、成交量（OBV、AD、ADOSC、VWAP）。所有指标计 1 积分，并可直接与时间序列请求组合。

使用方式

认证采用 API Key，可通过环境变量或 .env 文件配置：

export TWELVEDATA_API_KEY="your_api_key"

基础用法使用 REST 请求（Python 示例）：

import requests
import os

API_KEY = os.getenv("TWELVEDATA_API_KEY")
BASE_URL = "https://api.twelvedata.com"

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

也可使用官方 Python SDK：

from twelvedata import TDClient

td = TDClient(apikey="your_api_key")

ts = td.time_series(
    symbol="AAPL",
    interval="1day",
    outputsize=30
).as_pandas()

quote = td.quote(symbol="AAPL").as_json()

ts_with_indicators = td.time_series(
    symbol="AAPL",
    interval="1day",
    outputsize=50
).with_sma(time_period=20).with_rsi().as_pandas()

安装方式：

pip install twelvedata[matplotlib,plotly]

基础安装：

pip install twelvedata

WebSocket 需要额外安装：

pip install websocket-client

适用场景

获取历史 OHLCV 并转换为 Pandas DataFrame 进行分析。
在时间序列上链式添加多个技术指标，用于技术分析。
批量获取多个标的的报价（每次请求最多 120 个标的）。
获取公司基本面信息（公司简介、关键统计等）。
查询外汇汇率、加密货币价格。
搜索股票/加密货币代码。
使用 WebSocket 接收实时价格推送（需 Pro 套餐）。

限制与计费

积分制：标准接口每标的 1 积分；基本面数据每标的 100 积分；批量请求按单个标的同样计费。
速率限制因套餐而异：Free 每分钟 8 次、每日 800 次、仅试用 WebSocket；Grow（$29）每分钟 55-377 次、无每日上限、无 WebSocket；Pro（$99）每分钟 610-1597 次、无每日上限、支持 WebSocket；Enterprise（$329）每分钟 2584 次以上、无每日上限、支持 WebSocket。
Free 套餐包含：美国股票、外汇、加密货币、时间序列数据（收盘价）、所有技术指标、基础参考数据、1-2 年日内历史、30 年以上日线历史。
需付费套餐的功能：更高调用频率、国际股票（Grow+）、WebSocket 流（Pro+）、盘前盘后数据（Pro+）、延长交易时段、共同基金与 ETF 细分（Enterprise）、无每日限制。
错误处理时可检查响应头中的 api-credits-used 与 api-credits-left 监控积分。

最佳实践

使用批量请求，每次最多 120 个标的。
缓存参考数据（交易所、标的列表变动较少）。
使用 SDK 的 Pandas 输出以便数据处理。
将指标与 time_series 链式组合（共 1 积分）。
监控积分使用情况，检查响应头。
根据场景选择合适的时间间隔：分析用 1day，交易用 1min。