Package: twelvedata
Twelve Data Python Client for financial API & WebSocketOfficial python library forTwelve Data. This package supports all main features of the service:Get stock, forex, cryptocurrency, ETF, and index OHLC time series.Companies' profiles, financials, options, and much more fundamentals data.Get over 100+ technical indicators.Output data as:json,csv,pandasFull support for static and dynamic charts.Real-time WebSocket data stream.API keyis required. If you don't have it yet, get it by signing uphere.InstallationUse the package managerpipto install Twelve Data API library (without optional dependencies):pipinstalltwelvedataOr install with pandas support:pipinstalltwelvedata[pandas]Or install with pandas, matplotlib, plotly, and websocket support:pip install twelvedata[pandas,matplotlib,plotly,websocket-client]UsageCore dataFundamentalsTechnical indicatorsBatch requestsChartsWebSocketAdvancedSupported parametersParameterDescriptionTypeRequiredsymbolstock ticker (e.g. AAPL, MSFT);physical currency pair (e.g. EUR/USD, CNY/JPY);digital currency pair (BTC/USD, XRP/ETH)stringyesintervaltime frame: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 8h, 1day, 1week, 1monthstringyesapikeyyour personal API Key, if you don't have one - get itherestringyesexchangeif symbol is traded in multiple exchanges specify the desired one, valid for both stocks and cryptocurrenciesstringnomic_codeMarket Identifier Code (MIC) under ISO 10383 standard, valid for stocksstringnocountryif symbol is traded in multiple countries specify the desired one, valid for stocksstringnooutputsizenumber of data points to retrieveintnotimezonetimezone at which output datetime will be displayed, supports:UTC,Exchangeor according to IANA Time Zone Databasestringnostart_datestart date and time of sampling period, acceptsyyyy-MM-ddoryyyy-MM-dd hh:mm:ssformatstringnoend_dateend date and time of sampling period, acceptsyyyy-MM-ddoryyyy-MM-dd hh:mm:ssformatstringnoordersorting order of the time series output, supportsdescorascstringnodateCould be the exact date, e.g.2021-10-27, or in human languagetodayoryesterdaystringnoThe basis for all methods is theTDClientobject that takes the requiredapikeyparameter.Time seriesTDClient.time_series()accepts all common parameters. Time series may be converted to several formats:ts.as_json()- will return JSON arrayts.as_csv()- will return CSV with headerts.as_pandas()- will return pandas.DataFramets.as_url()- will return list of URLs usedfromtwelvedataimportTDClient# Initialize client - apikey parameter is requieredtd=TDClient(apikey="YOUR_API_KEY_HERE")# Construct the necessary time seriests=td.time_series(symbol="AAPL",interval="1min",outputsize=10,timezone="America/New_York",)# Returns pandas.DataFramets.as_pandas()Other core data endpoints:Exchange rate -TDClient.exchange_rate(symbol)Currency conversion -TDClient.currency_conversion(symbol, amount)Quote -TDClient.quote()takes parameters as.time_series()Real-time price -TDClient.price()takes parameters as.time_series()End of day price -TDClient.eod()takes parameters as.time_series()FundamentalsAll fundamentals are supported across global markets. Refer to API documentationhereand find out which countries support which fundamentals by visitingthispage..get_logo(symbol, exchange, country, type).get_profile(symbol, exchange, country, type).get_dividends(symbol, exchange, country, type).get_splits(symbol, exchange, country, type).get_earnings(symbol, exchange, country, type, period, outputsize, start_date, end_date).get_earnings_calendar(symbol, exchange, country, period, start_date, end_date).get_ipo_calendar(symbol, exchange, country, start_date, end_date).get_statistics(symbol, exchange, country, type).get_insider_transactions(symbol, exchange, country, type).get_income_statement(symbol, exchange, country, type, period, start_date, end_date).get_balance_sheet(symbol, exchange, country, type, period, start_date, end_date).get_cash_flow(symbol, exchange, country, type, period, start_date, end_date).get_options_expiration(symbol, exchange, country, type).get_options_chain(symbol, exchange, country, type, expiration_date, option_id, side).get_key_executives(symbol, exchange, country, type).get_institutional_holders(symbol, exchange, country, type).get_fund_holders(symbol, exchange, country, type)Only JSON format is supported accessible via.as_json()fromtwelvedataimportTDClienttd=TDClient(apikey="YOUR_API_KEY_HERE")# Get all expiration datesexpirations=td.get_options_expiration(symbol="AAPL",).as_json()['dates']# Extract only put options for the soonest expiration dateput_options=td.get_options_chain(symbol="AAPL",side="put",expiration_date=expirations[0]).as_json()['puts']print(put_options)Technical indicatorsThis Python library supports all indicators implemented by Twelve Data. Full list of 100+ technical indicators   may be found inAPI documentation.Technical indicators are part ofTDClient.time_series()object.It shares the universal formatTDClient.time_series().with_{Technical Indicator Name}, e.g..with_bbands(),.with_percent_b(),.with_macd()Indicator object accepts all parameters according to its specification inAPI documentation, e.g..with_bbands()accepts:series_type,time_period,sd,ma_type. If parameter is not provided it will be set to default value.Indicators may be used in arbitrary order and conjugated, e.g.TDClient.time_series().with_aroon().with_adx().with_ema()By default, technical indicator will output with OHLC values. If you do not need OHLC, specifyTDClient.time_series().without_ohlc()fromtwelvedataimportTDClienttd=TDClient(apikey="YOUR_API_KEY_HERE")ts=td.time_series(symbol="ETH/BTC",exchange="Huobi",interval="5min",outputsize=22,timezone="America/New_York",)# Returns: OHLC, BBANDS(close, 20, 2, EMA), PLUS_DI(9), WMA(20), WMA(40)ts.with_bbands(ma_type="EMA").with_plus_di().with_wma(time_period=20).with_wma(time_period=40).as_pandas()# Returns: STOCH(14, 1, 3, SMA, SMA), TSF(close, 9)ts.without_ohlc().with_stoch().with_tsf().as_json()Batch requestsWith batch requests up to 120 symbols might be returned per single API call. There are two options on how to do this:# 1. Pass instruments symbols as a string delimited by comma (,)ts=td.time_series(symbol="V, RY, AUD/CAD, BTC/USD:Huobi")# 2. Pass as a list of symbolsts=td.time_series(symbol=["V","RY","AUD/CAD","BTC/USD:Huobi"])Important.Batch requests are only supported with.as_json()and.as_pandas()formats.With.as_json()the output will be a dictionary with passed symbols as keys. The value will be a tuple with quotes, just the same as with a single request.ts=td.time_series(symbol='AAPL,MSFT',interval="1min",outputsize=3)df=ts.with_macd().with_macd(fast_period=10).with_stoch().as_json(){"AAPL":({'datetime':'2020-04-23 15:59:00','open':'275.23001','high':'275.25000','low':'274.92999','close':'275.01001','volume':'393317','macd_1':'-0.33538','macd_signal_1':'-0.24294','macd_hist_1':'-0.09244','macd_2':'-0.40894','macd_signal_2':'-0.29719','macd_hist_2':'-0.11175','slow_k':'4.52069','slow_d':'7.92871'},{'datetime':'2020-04-23 15:58:00','open':'275.07001','high':'275.26999','low':'275.00000','close':'275.25000','volume':'177685','macd_1':'-0.31486','macd_signal_1':'-0.21983','macd_hist_1':'-0.09503','macd_2':'-0.38598','macd_signal_2':'-0.26925','macd_hist_2':'-0.11672','slow_k':'14.70578','slow_d':'6.82079'},{'datetime':'2020-04-23 15:57:00','open':'275.07001','high':'275.16000','low':'275.00000','close':'275.07751','volume':'151169','macd_1':'-0.30852','macd_signal_1':'-0.19607','macd_hist_1':'-0.11245','macd_2':'-0.38293','macd_signal_2':'-0.24007','macd_hist_2':'-0.14286','slow_k':'4.55965','slow_d':'2.75237'}),"MSFT":({'datetime':'2020-04-23 15:59:00','open':'171.59000','high':'171.64000','low':'171.22000','close':'171.42000','volume':'477631','macd_1':'-0.12756','macd_signal_1':'-0.10878','macd_hist_1':'-0.01878','macd_2':'-0.15109','macd_signal_2':'-0.12915','macd_hist_2':'-0.02193','slow_k':'20.95244','slow_d':'26.34919'},{'datetime':'2020-04-23 15:58:00','open':'171.41000','high':'171.61000','low':'171.33501','close':'171.61000','volume':'209594','macd_1':'-0.12440','macd_signal_1':'-0.10408','macd_hist_1':'-0.02032','macd_2':'-0.14786','macd_signal_2':'-0.12367','macd_hist_2':'-0.02419','slow_k':'39.04785','slow_d':'23.80945'},{'datetime':'2020-04-23 15:57:00','open':'171.34500','high':'171.48000','low':'171.25999','close':'171.39999','volume':'142450','macd_1':'-0.13791','macd_signal_1':'-0.09900','macd_hist_1':'-0.03891','macd_2':'-0.16800','macd_signal_2':'-0.11762','macd_hist_2':'-0.05037','slow_k':'19.04727','slow_d':'14.92063'})}With.as_pandas()the output will be a 3D DataFrame with MultiIndex for (symbol, datetime).ts=td.time_series(symbol='AAPL,MSFT',interval="1min",outputsize=3)df=ts.with_macd().with_macd(fast_period=10).with_stoch().as_pandas()#                                open       high  ...    slow_k    slow_d# AAPL 2020-04-23 15:59:00  275.23001  275.25000  ...   4.52069   7.92871#      2020-04-23 15:58:00  275.07001  275.26999  ...  14.70578   6.82079#      2020-04-23 15:57:00  275.07001  275.16000  ...   4.55965   2.75237# MSFT 2020-04-23 15:59:00  171.59000  171.64000  ...  20.95244  26.34919#      2020-04-23 15:58:00  171.41000  171.61000  ...  39.04785  23.80945#      2020-04-23 15:57:00  171.34500  171.48000  ...  19.04727  14.92063## [6 rows x 13 columns]df.loc['AAPL']#                           open       high  ...    slow_k   slow_d# 2020-04-23 15:59:00  275.23001  275.25000  ...   4.52069  7.92871# 2020-04-23 15:58:00  275.07001  275.26999  ...  14.70578  6.82079# 2020-04-23 15:57:00  275.07001  275.16000  ...   4.55965  2.75237## [3 rows x 13 columns]df.columns# Index(['open', 'high', 'low', 'close', 'volume', 'macd1', 'macd_signal1',#        'macd_hist1', 'macd2', 'macd_signal2', 'macd_hist2', 'slow_k',#        'slow_d'],#       dtype='object')ChartsStaticInteractiveCharts support OHLC, technical indicators and custom bars.StaticStatic charts are based onmatplotliblibrary and requiremplfinancepackage to be installed.Use.as_pyplot_figure()fromtwelvedataimportTDClienttd=TDClient(apikey="YOUR_API_KEY_HERE")ts=td.time_series(symbol="MSFT",outputsize=75,interval="1day",)# 1. Returns OHLCV chartts.as_pyplot_figure()# 2. Returns OHLCV + BBANDS(close, 20, 2, SMA) + %B(close, 20, 2 SMA) + STOCH(14, 3, 3, SMA, SMA)ts.with_bbands().with_percent_b().with_stoch(slow_k_period=3).as_pyplot_figure()InteractiveInteractive charts are built on top ofplotlylibrary.Use.as_plotly_figure().show()fromtwelvedataimportTDClienttd=TDClient(apikey="YOUR_API_KEY_HERE")ts=td.time_series(symbol="DNR",outputsize=50,interval="1week",)# 1. Returns OHLCV chartts.as_plotly_figure()# 2. Returns OHLCV + EMA(close, 7) + MAMA(close, 0.5, 0.05) + MOM(close, 9) + MACD(close, 12, 26, 9)ts.with_ema(time_period=7).with_mama().with_mom().with_macd().as_plotly_figure().show()WebSocketWith the WebSocket, a duplex communication channel with the server is established.Make sure to havewebsocket_clientpackageinstalled.FeaturesReal-time low latency stream of financial quotes.You might subscribe to stocks, forex, and crypto.ExampleimporttimefromtwelvedataimportTDClientmessages_history=[]defon_event(e):# do whatever is needed with dataprint(e)messages_history.append(e)td=TDClient(apikey="YOUR_API_KEY_HERE")ws=td.websocket(symbols="BTC/USD",on_event=on_event)ws.subscribe(['ETH/BTC','AAPL'])ws.connect()whileTrue:print('messages received: ',len(messages_history))ws.heartbeat()time.sleep(10)Parameters accepted by the.websocket()object:symbolslist of symbols to subscribeon_eventfunction that invokes when event from server is receivedloggerinstance of logger, otherwise set to defaultmax_queue_sizemaximum size of queue, default12000log_levelacceptsdebugorinfo, otherwise not setApplicable methods on.websocket()object:ws.subscribe([list of symbols]): get data from the symbols passedws.unsubscribe([list of symbols]): stop receiving data from the symbols passedws.reset(): unsubscribe from all symbolsws.connect(): establish connection with WebSocket serverws.disconnect(): close connection with WebSocket serverws.heartbeat(): send heartbeat to serverImportant. Do not forget that WebSockets are only available for Twelve Data users on thePro planand above. Checkout the trialhere.AdvancedCustom endpointThis method is used to request unrepresented endpoints on this package, but which are available at Twelve Data.endpoint=td.custom_endpoint(name="quote",symbol="AAPL",)endpoint.as_json()The only required parameter isnamewhich should be identical to the endpoint used at Twelve Data. All others can be custom and will vary according to the method.DebuggingWhen the method doesn't return the desired data or throws an error, it might be helpful to understand and analyze the API query behind it.
Add.as_url()to any method or chain of methods, and it will return the list of used URLs.ts=td.time_series(symbol="AAPL",interval="1min",outputsize=10,timezone="America/New_York",).with_bbands().with_ema()ts.as_url()# ['https://api.twelvedata.com/time_series?symbol=AAPL&interval=1min&outputsize=10&dp=5&timezone=America/New_York&order=desc&prepost=false&format=JSON&apikey=demo',# 'https://api.twelvedata.com/bbands?symbol=AAPL&interval=1min&series_type=close&time_period=20&sd=2&ma_type=SMA&outputsize=10&dp=5&timezone=America/New_York&order=desc&prepost=false&format=JSON&apikey=demo',# 'https://api.twelvedata.com/ema?symbol=AAPL&interval=1min&series_type=close&time_period=9&outputsize=10&dp=5&timezone=America/New_York&order=desc&prepost=false&format=JSON&apikey=demo']API usageThis method gives an overview of the current API credits consumption.api=td.api_usage()SupportVisit our official websitecontact pageorsupport center.AnnouncementsFollow us for announcements and updates about this library.TwitterTelegramRoadmapFundamentalsWebSocketBatch requestsCustom plots coloringInteractive charts (plotly)Static charts (matplotlib)Pandas supportContributingClone repo and create a new branch:$ git checkout https://github.com/twelvedata/twelvedata -b name_for_new_branch.Make changes and test.Submit Pull Request with comprehensive description of changes.LicenseThis package is open-sourced software licensed under theMIT license.