twelvedata-python: one client for Twelve Data time series, fundamentals and indicators

A client for one provider, and the README says so plainly

The repository describes itself as the official Python library for Twelve Data, and its stated coverage is broad: stock, forex, cryptocurrency, ETF and index OHLC time series, company profiles and financials, over 100 technical indicators, output as json, csv or pandas, static and dynamic charts, and a real-time WebSocket data stream.

What the package is not is an abstraction over market data in general. Every call goes to one commercial service behind one personal API key, and the README states that an API key is required and points readers to twelvedata.com/pricing to sign up. The dependency on that provider, and on a subscription tier behind it, is more consequential than the dependency list suggests.

The Python package itself is thin by design. The top level of the repository holds a src directory, tests, docs, a Pipfile and Pipfile.lock, requirements.txt, setup.py, setup.cfg and pyproject.toml, and the runtime requirements listed in requirements.txt are just pytimeparse, requests and setuptools. There is no data layer to own and no caching to tune. The licence is MIT, and the last push was on 2026-08-12 on the master branch.

TDClient is the whole entry point, and apikey is its only required field

The design centres on a single object. The README states that the basis for all methods is the TDClient object that takes the required apikey parameter, and that every later call is a method on that object.

From there the client exposes a set of named endpoints. TDClient.time_series() accepts all common parameters. TDClient.exchange_rate(symbol) covers exchange rates, TDClient.currency_conversion(symbol, amount) converts currency, and TDClient.quote(), TDClient.price() and TDClient.eod() take parameters in the same way as .time_series(). Fundamentals arrive through a second family of methods: get_logo, get_profile, get_dividends, get_splits, get_earnings, get_earnings_calendar, get_ipo_calendar, get_statistics, get_insider_transactions, get_income_statement, get_balance_sheet, get_cash_flow, get_key_executives, get_institutional_holders and get_fund_holders.

The returned object is what makes the library pleasant to use, and it is also where the format choice lives. A time series can be converted with ts.as_json() to a JSON array, ts.as_csv() to CSV with header, ts.as_pandas() to a pandas.DataFrame, and ts.as_url() to a list of URLs used. The same object supports the optional dependencies, so the extras you install decide which of these conversions actually work.

Three pip commands, and the extras decide what you can do

Installation is a single pip command, and the variants matter more than the base one. The README gives the plain install without optional dependencies:

pip install twelvedata

With pandas support:

pip install twelvedata[pandas]

And with pandas, matplotlib, plotly and websocket support combined:

pip install twelvedata[pandas,matplotlib,plotly,websocket-client]

Those extras line up with the feature list. pandas enables ts.as_pandas(), matplotlib and plotly back the charting support, and websocket-client backs the real-time data stream. The base install is enough for json and csv output over the ordinary endpoints.

A first call looks like this, and it is the whole pattern: build the client with your key, ask for a time series, then convert it to the format you want.

from twelvedata import TDClient

# Initialize client - apikey parameter is requiered
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
ts.as_pandas()

Replace the placeholder with your own key, and expect the server to return the time series for the symbol and interval you asked for.

The parameter table is where the real constraints live

The supported parameter table is short and shows the limits of the service rather than the library. Required fields are symbol, interval and apikey. symbol covers stock tickers such as AAPL and MSFT, physical currency pairs such as EUR/USD and CNY/JPY, and digital currency pairs such as BTC/USD and XRP/ETH. interval is a time frame drawn from a fixed set: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 8h, 1day, 1week, 1month.

The optional parameters are where mistakes tend to hide. exchange selects the exchange when a symbol trades on more than one, and is valid for both stocks and cryptocurrencies. mic_code is a Market Identifier Code under the ISO 10383 standard and is valid for stocks. country selects the country when a symbol trades in more than one. outputsize is the number of data points to retrieve. timezone sets the timezone at which output datetime will be displayed and supports UTC, Exchange, or a name from the IANA Time Zone Database. start_date and end_date accept yyyy-MM-dd or yyyy-MM-dd hh:mm:ss. order sorts the time series output and supports desc or asc, and date accepts an exact date such as 2021-10-27 or the human language values today and yesterday.

Two of those deserve care in code. The date parameter accepting relative words means a script can silently pull different windows on different days, and the timezone parameter changes the displayed timestamps rather than the sampling period, which matters when you align series across venues.

Fundamentals are JSON only, and coverage varies by country

The fundamentals family has one formatting rule that the time series endpoints do not share: only JSON format is supported, accessible via .as_json(). There is no csv or pandas conversion for a balance sheet or an income statement.

The methods take a long but uniform signature, typically symbol, exchange, country and type, with the financial statements adding period, start_date and end_date. .get_earnings() takes symbol, exchange, country, type, period, outputsize, start_date and end_date, while .get_earnings_calendar() and .get_ipo_calendar() take the calendar-oriented subset. The intent is clear enough from the names that the calling convention is uniform, which keeps the mapping from a financial concept to a method short.

Coverage is the part the library cannot normalise for you. The README states that all fundamentals are supported across global markets, but directs readers to the API documentation and to a support page listing which countries support which fundamentals. In practice a statement method can be supported for one market and not another, so the country coverage page is the place to look before you rely on a specific field.

A typical call is as small as the time series one:

from twelvedata import TDClient

td = TDClient(apikey="YOUR_API_KEY_HERE")

# Get last dividends for AAPL
dividends = td.get_dividends(
    symbol="AAPL",
).as_json()

Indicators hang off the time series object rather than the client

Technical indicators are handled differently from every other endpoint. They are part of the TDClient.time_series() object and share a universal format, TDClient.time_series().with_{Technical Indicator Name}, with examples given as .with_bbands(), .with_percent_b() and .with_macd().

That naming convention is the entire API for indicators, and it has a practical consequence: an indicator is a modifier on a time series request, not a separate call with its own symbol and interval. Each indicator object accepts the parameters from its own specification in the API documentation, and the README states the library supports all indicators implemented by Twelve Data, with the full list of 100+ indicators in that documentation rather than in the repository.

So the flow is: request a time series, attach the indicators you want to it, then convert the result. Chaining indicators on one request is the efficient path, and it is also the reason the indicator parameters are described as per indicator rather than per call.

Where this client is the wrong tool, and what the README leaves undocumented

Three limits are worth naming before adoption. First, provider coupling: there is no switch to another data source, no mock backend for tests, and no interface to implement, so a codebase built on TDClient is tied to one service and one key. Second, fundamentals give you JSON only, so a pandas pipeline over statements needs an extra conversion step that the time series endpoints do not need. Third, access is not free of external constraints, since the key belongs to a subscription and the plan behind it determines what you can query.

The documentation itself is uneven. The README's usage index links to sections for Core data, Fundamentals, Technical indicators, Batch requests, Charts, WebSocket and Advanced, and the feature list claims full support for static and dynamic charts and for a real-time WebSocket data stream, but the README does not show the code for batch requests, charts, the WebSocket client or the advanced options. Anyone planning to use those paths should expect to read the API documentation and the docs directory instead of the README.

On packaging and upkeep, the project publishes no GitHub releases, and pyproject.toml builds with setuptools-scm, writing the version into src/twelvedata/_version.py. Version information is therefore derived from git tags rather than from a published release, and the runtime dependencies are just pytimeparse, requests and setuptools. With an MIT licence and the last push on 2026-08-12, this is a library that tracks its provider closely but releases on a rhythm you will not find in the repository.

Editorial conclusion

Adopt twelvedata-python if your project already depends on Twelve Data and you want its endpoints as typed methods with json, csv and pandas converters rather than hand written HTTP calls. Do not adopt it as a provider independent market data layer, since every method is bound to one service and one API key, and the fundamentals endpoints return JSON only. Before wiring it in, install the extra matching your needs, such as pip install twelvedata[pandas,matplotlib,plotly,websocket-client], confirm the plan behind your apikey at twelvedata.com/pricing, and note that the package carries no GitHub releases and that its version is written from git tags by setuptools-scm into src/twelvedata/_version.py.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. twelvedata/twelvedata-python on GitHub