Twelve Data Python Client

The Twelve Data Python client provides access to the Twelve Data financial API and WebSocket services. Key capabilities include:

• Time Series Data: Retrieve OHLC (Open, High, Low, Close) data for stocks, forex, cryptocurrency, ETFs, and indices.
• Fundamental Data: Access company profiles, financials, and other fundamental metrics.
• Technical Indicators: Access over 100+ technical indicators.
• Flexible Output Formats: Data can be returned in json, csv, or pandas formats.
• Charting: Full support for both static and dynamic charts.
• Real-time Data: Real-time data streaming via WebSockets.

Note: An API key is required to use the service.

The library supports two types of charting:

1. Static Charts: Based on matplotlib. Requires the mplfinance package. Use .as_pyplot_figure().
2. Interactive Charts: Based on plotly. Use .as_plotly_figure().show().

Both methods can be used on a standard time series or a time series with technical indicators applied.

# Static Chart (requires mplfinance)
ts.as_pyplot_figure()

# Interactive Chart (requires plotly)
ts.with_ema(time_period=7).with_macd().as_plotly_figure().show()

You can install the twelvedata library using pip. Depending on your needs, you can install the base package or include optional dependencies for data analysis and real-time streaming.

• Base installation: Minimal package without optional dependencies.
• With pandas support: Adds support for returning data as pandas.DataFrame objects.
• Full installation: Includes pandas, matplotlib, plotly, and websocket-client for advanced charting and real-time WebSocket data streams.

# Base installation
pip install twelvedata

# Install with pandas support
pip install twelvedata[pandas]

# Full installation with pandas, matplotlib, plotly, and websocket support
pip install twelvedata[pandas,matplotlib,plotly,websocket-client]

The TDClient is the primary entry point for the Twelve Data Python library. It requires an apikey parameter to authenticate your requests. All core data, fundamentals, and technical indicator methods are accessed through an instance of this class.

from twelvedata import TDClient

# Initialize client - apikey parameter is required
td = TDClient(apikey="YOUR_API_KEY_HERE")

The Context class is used by all request builders to manage session settings and authentication. It holds the apikey required for Twelvedata API access, the base_url, the http_client, and a defaults dictionary for parameters used across requests. It also manages self_heal_time_s, which defines the retry interval in seconds.

You can create a new context or derive one from an existing one using from_context(ctx) to ensure consistent settings across different parts of your application.

# Example of how Context attributes are structured
# Note: Actual instantiation typically happens via the main client
ctx = Context()
ctx.apikey = 'YOUR_API_KEY'
ctx.base_url = 'https://api.twelvedata.com'
ctx.defaults = {'format': 'json'}
ctx.self_heal_time_s = 5

When using TDWebSocket, you can process incoming real-time data by providing a callback function to the on_event parameter in your configuration/context.

The TDWebSocket uses an internal EventHandler thread that continuously pulls events from a queue and passes them to your provided function. If no function is provided, events are simply queued and discarded by the handler.

To ensure your application can keep up with the data stream, monitor for the error message: "Event queue is full. New events are not added." which indicates your on_event handler is too slow or the max_queue_size is too small.

def my_event_handler(data):
    print(f"Received data: {data}")

# The handler is typically passed via the context/defaults used to initialize TDWebSocket
# ctx.defaults = {'on_event': my_event_handler}

If a method is not returning the expected data or is throwing errors, you can inspect the actual HTTP request being sent. Append .as_url() to any method or chain of methods to return a list of the URLs used to construct the request.

ts = td.time_series(symbol="AAPL", interval="1min").with_bbands().with_ema()
print(ts.as_url())

Use TDClient.time_series() to fetch historical market data. You can specify parameters like symbol, interval, outputsize, and timezone.

Once a time series object is created, you can convert the output into different formats:

• ts.as_json(): Returns a JSON array.
• ts.as_csv(): Returns CSV data with a header.
• ts.as_pandas(): Returns a pandas.DataFrame.
• ts.as_url(): Returns a list of the URLs used to construct the request.

from twelvedata import TDClient

td = TDClient(apikey="YOUR_API_KEY_HERE")

# Construct the necessary time series
ts = td.time_series(
    symbol="AAPL",
    interval="1min",
    outputsize=10,
    timezone="America/New_York",
)

# Returns pandas.DataFrame
df = ts.as_pandas()

You can request data for up to 120 symbols in a single API call. This is supported by passing a comma-delimited string or a list of symbols to the symbol parameter.

Important: Batch requests are only supported with .as_json() and .as_pandas() formats.

• .as_json() returns a dictionary where keys are the symbols and values are the data tuples.
• .as_pandas() returns a 3D DataFrame with a MultiIndex of (symbol, datetime).

# Option 1: Comma-delimited string
ts = td.time_series(symbol="V, RY, AUD/CAD, BTC/USD", interval="1day")

# Option 2: List of symbols
ts = td.time_series(symbol=["V", "RY", "AUD/CAD", "BTC/USD"], interval="1day")

# Using as_pandas with batch
df = ts.with_macd().as_pandas()
# Access specific symbol via MultiIndex: df.loc['AAPL']