twelvedata-api

Twelve Data API 連携

株式、外国為替、暗号資産、ETF、指数、および100種類以上のテクニカル指標を提供する包括的な金融データ API です。優れた Python SDK にも対応しています。

クイックスタート

認証

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

# Or in .env file
TWELVEDATA_API_KEY=your_api_key

基本的な使い方（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()

# Example
quote = get_quote("AAPL")
print(f"AAPL: ${quote['close']} ({quote['percent_change']}%)")

公式 SDK の使用

from twelvedata import TDClient

td = TDClient(apikey="your_api_key")

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

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

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

API エンドポイントリファレンス

コアデータ

エンドポイント	説明	クレジット
/quote	リアルタイムの気配値	1
/price	現在価格のみ	1
/eod	日末価格	1
/time_series	過去の OHLCV	1
/exchange_rate	通貨換算	1

リファレンスデータ

エンドポイント	説明	クレジット
/symbol_search	銘柄を検索	1
/instruments	すべての金融商品を一覧表示	無料
/exchanges	取引所を一覧表示	無料
/instrument_type	種類を一覧表示	無料
/earliest_timestamp	データ開始日	無料

ファンダメンタルデータ

エンドポイント	説明	クレジット
/income_statement	損益計算書	100
/balance_sheet	貸借対照表	100
/cash_flow	キャッシュフロー	100
/earnings	業績履歴	100
/earnings_calendar	今後の決算発表	100
/dividends	配当履歴	1
/splits	株式分割履歴	1
/statistics	主要統計	100
/profile	企業プロフィール	100

テクニカル指標（100種類以上）

すべての指標は1クレジットで利用でき、time_series に含めることができます。

トレンド： SMA、EMA、WMA、DEMA、TEMA、KAMA、MAMA、T3、TRIMA、VWMA モメンタム： RSI、MACD、ストキャスティクス、Williams %R、ADX、CCI、MFI、ROC、AROON ボラティリティ： ボリンジャーバンド、ATR、ケルトナーチャネル、ドンチャン 出来高： OBV、AD、ADOSC、VWAP

レート制限

プラン	呼び出し/分	1日あたり	WebSocket
無料	8	800	トライアルのみ
Grow ($29)	55-377	無制限	❌
Pro ($99)	610-1597	無制限	✅
Enterprise ($329)	2584+	無制限	✅

クレジットシステム：

• 標準エンドポイント：銘柄あたり1クレジット
• ファンダメンタルデータ：銘柄あたり100クレジット
• バッチリクエスト：個別リクエストと同じコスト

よくあるタスク

タスク：Pandas で時系列データを取得する

from twelvedata import TDClient
import pandas as pd

td = TDClient(apikey=API_KEY)

def get_historical_data(symbol: str, days: int = 100) -> pd.DataFrame:
    """Get historical OHLCV data as DataFrame."""
    ts = td.time_series(
        symbol=symbol,
        interval="1day",
        outputsize=days
    )
    return ts.as_pandas()

# Example
df = get_historical_data("AAPL", 100)
print(df.head())

タスク：複数の指標を使ったテクニカル分析

def get_technical_analysis(symbol: str) -> pd.DataFrame:
    """Get price data with technical indicators."""
    ts = td.time_series(
        symbol=symbol,
        interval="1day",
        outputsize=100
    )

    # Chain indicators
    df = (ts
        .with_sma(time_period=20)
        .with_sma(time_period=50)
        .with_rsi(time_period=14)
        .with_macd()
        .with_bbands()
        .as_pandas()
    )

    return df

# Example
analysis = get_technical_analysis("AAPL")

タスク：複数の銘柄を取得する（バッチ）

def get_batch_quotes(symbols: list) -> dict:
    """Get quotes for multiple symbols efficiently."""
    symbol_str = ",".join(symbols)

    response = requests.get(
        f"{BASE_URL}/quote",
        params={
            "symbol": symbol_str,
            "apikey": API_KEY
        }
    )
    return response.json()

# Example: Up to 120 symbols per request
quotes = get_batch_quotes(["AAPL", "MSFT", "GOOGL", "AMZN"])

タスク：ファンダメンタルデータを取得する

def get_fundamentals(symbol: str) -> dict:
    """Get comprehensive fundamental data."""
    # Note: Each call costs 100 credits

    profile = requests.get(
        f"{BASE_URL}/profile",
        params={"symbol": symbol, "apikey": API_KEY}
    ).json()

    stats = requests.get(
        f"{BASE_URL}/statistics",
        params={"symbol": symbol, "apikey": API_KEY}
    ).json()

    return {
        "name": profile.get("name"),
        "sector": profile.get("sector"),
        "industry": profile.get("industry"),
        "market_cap": stats.get("statistics", {}).get("valuations_metrics", {}).get("market_capitalization"),
        "pe_ratio": stats.get("statistics", {}).get("valuations_metrics", {}).get("trailing_pe"),
        "dividend_yield": stats.get("statistics", {}).get("dividends_and_splits", {}).get("dividend_yield")
    }

タスク：外国為替レートを取得する

def get_forex_rate(from_currency: str, to_currency: str) -> dict:
    """Get currency exchange rate."""
    response = requests.get(
        f"{BASE_URL}/exchange_rate",
        params={
            "symbol": f"{from_currency}/{to_currency}",
            "apikey": API_KEY
        }
    )
    return response.json()

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

タスク：暗号資産データを取得する

def get_crypto_price(symbol: str, exchange: str = "Binance") -> dict:
    """Get cryptocurrency price."""
    response = requests.get(
        f"{BASE_URL}/quote",
        params={
            "symbol": f"{symbol}/USD",
            "exchange": exchange,
            "apikey": API_KEY
        }
    )
    return response.json()

# Example
btc = get_crypto_price("BTC")
print(f"BTC: ${btc['close']}")

タスク：銘柄を検索する

def search_symbols(query: str, show_plan: bool = False) -> list:
    """Search for stock/crypto symbols."""
    params = {
        "symbol": query,
        "apikey": API_KEY
    }
    if show_plan:
        params["show_plan"] = "true"

    response = requests.get(f"{BASE_URL}/symbol_search", params=params)
    return response.json().get("data", [])

# Example
results = search_symbols("Apple")
for r in results[:5]:
    print(f"{r['symbol']}: {r['instrument_name']}")

WebSocket によるリアルタイムストリーミング

from twelvedata import TDClient

td = TDClient(apikey=API_KEY)

def on_event(event):
    """Handle real-time price updates."""
    print(f"{event['symbol']}: ${event['price']}")

# Create WebSocket (requires Pro plan)
ws = td.websocket(
    symbols=["AAPL", "MSFT", "GOOGL"],
    on_event=on_event
)

ws.connect()
ws.keep_alive()

エラー処理

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

    try:
        response = requests.get(f"{BASE_URL}/{endpoint}", params=params)
        data = response.json()

        # Check for API errors
        if "status" in data and data["status"] == "error":
            print(f"API Error: {data.get('message', 'Unknown error')}")
            return {}

        # Check remaining credits
        credits_used = response.headers.get("api-credits-used")
        credits_left = response.headers.get("api-credits-left")
        if credits_left:
            print(f"Credits remaining: {credits_left}")

        return data

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

無料機能とプレミアム機能

無料プランに含まれる機能

• API 呼び出しは毎分8回、1日800回
• 米国株、外国為替、暗号資産
• 時系列データ（日末）
• すべてのテクニカル指標
• 基本的なリファレンスデータ
• 日中足データの履歴は1～2年分
• 日足データの履歴は30年以上分

プレミアムプランが必要な機能

• より高いレート制限
• 国際株（Grow 以上）
• WebSocket ストリーミング（Pro 以上）
• プレマーケット／アフターマーケットデータ（Pro 以上）
• 取引時間の延長
• 投資信託と ETF の内訳（Enterprise）
• 1日あたりの制限なし

ベストプラクティス

1. バッチリクエストを使う - 1回の呼び出しで最大120銘柄
2. リファレンスデータをキャッシュする - 取引所や金融商品が変更されることはほとんどありません
3. SDK の Pandas 出力を使う - データを簡単に操作できます
4. 指標を連携させる - time_series に含めると、合計1クレジットです
5. クレジットを確認する - レスポンスヘッダーを確認してください
6. 適切な間隔を使う - 分析には1day、取引には1min

インストール

# Python SDK with all features
pip install twelvedata[matplotlib,plotly]

# Basic installation
pip install twelvedata

# For WebSocket
pip install websocket-client

関連スキル

• finnhub-api - リアルタイムニュースに重点
• alphavantage-api - 指標データの代替ソース
• fmp-api - ファンダメンタル分析に重点

参考資料

• 公式ドキュメント
• Python SDK
• テクニカル指標
• 料金