NAV Navbar

Getting Started

Welcome to the Twelve Data! You can use this API to access world financial markets including stocks, forex, ETFs, indices, and cryptocurrencies. Most of the exchanges are available in real-time, while others have some delays. Over 20+ years of end-of-day data and a couple of years for intraday historical data.

If you are unfamiliar with APIs and requests, check this tutorial on how to make requests as part of the How-to tutorials.

code & output ${examples} can be found in this section

AuthenticationImportant

Twelve Data authenticates users by valid API keys for both API and WebSocket. It can be specified in two ways:

A demo API key is used for sample requests to familiarize yourself with the API format. Complete access to API is available with your API key, which can be obtained for free by signing up for the Basic plan. Specific endpoints are available starting only from Grow, Pro, or Enterprise plans. However, they all can be tested as trial symbols across all markets. API will return an error if the key is invalid or has insufficient permissions.

Endpoints

API endpoints are prefixed with https://api.twelvedata.com
WebSocket endpoints are prefixed with wss://ws.twelvedata.com

ParametersUseful

How to separate

Parameters are ampersand(&) separated.
E.g. ?symbol=AAPL&interval=5min&output=200

Casting

Word casing doesn‘t matter when passing parameters.
E.g. ?symbol=AAPL, ?symbol=AaPl, or ?symbol=aapl will all correctly work.

Exchanges

Symbol might be also passed in the form symbol:exchange_name.
E.g. ?symbol=RY:TSX, ?symbol=AAPL:NASDAQ

CSV

When the format parameter is set to CSV, additional filename parameter might be used to specify the custom name of the output file. E.g. ?format=CSV&filename=my_own_csv_name

Dates

To get the most use of start_date, end_date, and outputsize parameters when accessing historical data, refer to this tutorial.

Batch RequestsUseful

Batch requests might be used on top of most endpoints including technical indicators. It allows requesting multiple symbols simultaneously.

HTTP request example

https://api.twelvedata.com/time_series?symbol=AAPL,EUR/USD,ETH/BTC:Huobi,TRP:TSX&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "AAPL": {
      "meta": {
         "symbol": "AAPL",
         "interval": "1min",
         "currency": "USD",
         "exchange_timezone": "America/New_York",
         "exchange": "NASDAQ",
         "type": "Common Stock"
      },
      "values": [
         {
            "datetime": "2020-02-26 15:59:00",
            "open": "292.89001",
            "high": "293.10001",
            "low": "292.50000",
            "close": "292.64999",
            "volume": "385977"
         },
         {...}
      ],
      "status": "ok"
   },
   "EUR/USD": {
      {...}
   },
   "ETH/BTC:Huobi": {
      {...}
   }, 
   "TRP:TSX": {
      {...}
   }
}

Request

Basic call

All symbols should be comma delimited and provided in symbol parameter. E.g:
/time_series?symbol=AAPL,QQQ,EUR/USD,IXIC

Exchange specific call

In order to call symbol from the specific exchange, use symbol_ticker:exchange format. E.g:
/bbands?symbol=ETH/BTC:Huobi,TRP:TSX,INFY:BSE

General

All instruments might be called in an arbitrary order and mixes, such as stocks, forex, crypto, ETFs and indices.
Request count will be incremented according to the number of passed symbols.
Batch requests only support JSON format.
Limited to 120 symbols per request.

Response

The response consists of the main object where the key is the symbol passed and value is the normal object consisting of meta, values, status.
The response header will also include is_batch set to true if the request is batch with multiple returns symbols.

Error handling

In the case that there was an error during processing one of the symbols, the error will only be returned for that specific symbol without affecting other instrument responses.

JSON request example

https://api.twelvedata.com/time_series?symbol=AAPL,EUR/USD,IXIC&interval=1min&apikey=demo

https://api.twelvedata.com/time_series?symbol=ETH/BTC:Huobi,TRP:TSX,INFY:BSE&interval=30min&outputsize=12&apikey=demo

Errors

Twelve Data API uses a unified error response scheme. Consisting of a JSON object with code, message and status keys.

HTTP request example

https://api.twelvedata.com/time_series?symbol=AAPL&interval=0.99min&apikey=your_api_key

This request with incorrect interval set will return JSON with the following structure

{
  "code": 400,
  "message": "Invalid **interval** provided: 0.99min. Supported intervals: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 8h, 1day, 1week, 1month",
  "status": "error"
}

Possible output error codes are:

Error Code Status Meaning
400 Bad Request There is an error with one or multiple parameters.
401 Unauthorized Your API key is wrong or not valid.
403 Forbidden Your API key is valid but has no permissions to make request available on the upper plans.
404 Not Found The specified data can not be found.
414 Parameter Too Long The parameter which accepts multiple values is out of range.
429 Too Many Requests You've reached your API request limits.
500 Internal Server Error There is an error on the server-side. Try again later.

How to overcome the errors:

Roadmap

We continuously make Twelve Data the only place where all users can obtain the necessary financial data. If you have any questions or ideas about improvement, contact us.

LibrariesUseful

Here, we publish libraries created to get the most of Twelve Data. We work towards making the industry the best SDKs for the most popular languages. Large releases are coming soon. A full list can be found on GitHub.

Official libraries and Add-ins

Language URL
Python twelvedata-python
R twelvedata-r-sdk
Excel Excel Add-in
Google Sheets Google Sheets Add-on

Third-party libraries

Language URL
C# TwelveDataSharp
JavaScript twelvedata
PHP twelvedata
Go twelvedata

The same list can also be accessed at the Support Center.

Support

Please refer to the Help Center for general assistance. If your question has not been answered yet drop a message to us.

Reference Data

Reference Data returns general data that can be used to enhance your project generalization.

Stocks List

This API call returns an array of symbols available at Twelve Data API. This list is updated daily.

HTTP request example

https://api.twelvedata.com/stocks

This request will return JSON with the following structure

[
  {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "country": "United States",
    "type": "Common Stock"
  },
  {
    "symbol": "AAT",
    "name": "American Assets Trust Inc",
    "currency": "USD",
    "exchange": "NYSE",
    "mic_code": "XNYS",
    "country": "United States",
    "type": "Real Estate Investment Trust (REIT)"
  },
  {...}
]

// with &show_plan=true
{
  "data": [
    {
      "symbol": "TCS",
      "name": "Tata Consultancy Services Limited",
      "currency": "INR",
      "exchange": "NSE",
      "mic_code": "XNSE",
      "country": "India",
      "type": "Common Stock",
      "access": {
        "global": "Level A",
        "plan": "Grow"
      }
    },
    {
      "symbol": "TCS",
      "name": "Axon Enterprise Inc",
      "currency": "EUR",
      "exchange": "FSX",
      "mic_code": "XFRA",
      "country": "Germany",
      "type": "Common Stock",
      "access": {
        "global": "Level A",
        "plan": "Grow"
      }
    },
    {...}
  ],
  "status": "ok"
}

HTTP route

/stocks

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
exchange • Parameter is optional
• Filter by exchange name or mic code
mic_code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code
type • Parameter is optional
• Filter by instrument type
format • Parameter is optional
• Value can be JSON or CSV; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false
include_delisted • Parameter is optional
• Include delisted identifiers
• Boolean; Default false

Response

Key Description
symbol instrument symbol (ticker)
name full name of instrument
currency currency of the instrument according to the ISO 4217 standard
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
country country where exchange is located
type common issue type

JSON request example

https://api.twelvedata.com/stocks

https://api.twelvedata.com/stocks?symbol=AAPL

Downloadable CSV example

https://api.twelvedata.com/stocks?format=CSV

Forex Pairs List

This API call return array of forex pairs available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/forex_pairs

This request will return JSON with the following structure

[
  {
    "symbol": "EUR/USD",
    "currency_group": "Major",
    "currency_base": "Euro",
    "currency_quote": "US Dollar"
  },
  {
    "symbol": "XAU/USD",
    "currency_group": "Exotic",
    "currency_base": "Gold Spot",
    "currency_quote": "US Dollar"
  },
  {...}
]

HTTP route

/forex_pairs

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
currency_base • Parameter is optional
• Filter by currency base
currency_quote • Parameter is optional
• Filter by currency quote
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;

Response

Key Description
symbol currency pair according to ISO 4217 standard codes with slash(/) delimiter
currency_group group to which currency pair belongs to, could be: Major, Minor, Exotic and Exotic-Cross
currency_base base currency name according to ISO 4217 standard
currency_quote quote currency name according to ISO 4217 standard

JSON request example

https://api.twelvedata.com/forex_pairs

https://api.twelvedata.com/forex_pairs?symbol=EUR/USD

Downloadable CSV example

https://api.twelvedata.com/forex_pairs?format=CSV

Cryptocurrencies List

This API call return array of cryptocurrency pairs available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/cryptocurrencies

This request will return JSON with the following structure

[
  {
    "symbol": "BTC/USD",
    "available_exchanges": ["ABCC", "Allcoin", "BTC-Alpha", "BTCTurk", "Bibox", "BigONE", "Binance", "Bit-Z", "BitForex", "BitMEX", "BitMart", "BitMax", "BitStamp", "Bitex.la", "Bitfinex", "Bitibu", "Bitinka", "Bitlish", "Bitrue", "Bittrex", "Btcwinex", "C2CX", "CBX", "CEX.IO", "COINEGG", "Cobinhood", "CoinAll", "CoinField", "CoinHub", "CoinTiger", "Coinbase Pro", "Coinbene", "CoinsBank", "Coinsbit", "CryptalDash", "DragonEX", "EXX", "Exmo", "Exrates", "GDAX", "Gate.io", "Gemini", "HitBTC", "Huobi", "IDAX", "IDCM", "Independent Reserve", "Kraken", "Kryptono", "Kucoin", "LBank", "LakeBTC", "Livecoin", "OKCoin", "OKEx", "OOOBTC", "Panxora", "Poloniex", "QUOINE", "SIMEX", "Tidex", "Upbit", "YoBit", "ZB.COM", "bitFlyer", "itBit", "n.exchange", "p2pb2b", "xBTCe"],
    "currency_base": "Bitcoin",
    "currency_quote": "US Dollar"
  },
  {
    "symbol": "ETH/BTC",
    "available_exchanges": ["ABCC", "Allcoin", "BTC Indonesia", "BTC Markets", "BTC-Alpha", "BXThailand", "Bibox", "BigONE", "Bilaxy", "Binance", "Bit-Z", "BitBay", "BitForex", "BitMart", "BitStamp", "Bitbank", "Bitci.com", "BiteBTC", "Bitfinex", "Bitibu", "Bitlish", "Bittrex", "Btcwinex", "CBX", "CEX.IO", "COINEGG", "Cobinhood", "CoinAll", "CoinExchange", "CoinMex", "CoinTiger", "Coinbase Pro", "Coinbene", "Coinsbit", "EXX", "Exmo", "Exrates", "Fatbtc", "GDAX", "GOPAX", "Gate.io", "Gemini", "HitBTC", "Hotbit", "Huobi", "IDAX", "IDCM", "Kraken", "Kryptono", "Kucoin", "LBank", "LakeBTC", "Livecoin", "OKEx", "Panxora", "Poloniex", "QUOINE", "SIMEX", "STEX", "TOKOK", "Tidex", "Upbit", "Vebitcoin", "YoBit", "ZB.COM", "Zaif", "bitFlyer", "p2pb2b", "xBTCe"],
    "currency_base": "Ethereum",
    "currency_quote": "Bitcoin"
  },
  {...}
]

HTTP route

/cryptocurrencies

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
exchange • Parameter is optional
• Filter by exchange name
currency_base • Parameter is optional
• Filter by currency base
currency_quote • Parameter is optional
• Filter by currency quote
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;

Response

Key Description
symbol cryptocurrency pair codes with slash(/) delimiter
available_exchanges array of exchanges where cryptocurrency is traded
currency_base base cryptocurrency name
currency_quote quote cryptocurrency name

JSON request example

https://api.twelvedata.com/cryptocurrencies

https://api.twelvedata.com/cryptocurrencies?symbol=BTC/USD

Downloadable CSV example

https://api.twelvedata.com/cryptocurrencies?format=CSV

ETF List

This API call return array of ETFs available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/etf

This request will return JSON with the following structure

[
  {
    "symbol": "SPY",
    "name": "SPDR S&P 500 ETF Trust",
    "currency": "USD",
    "exchange": "NYSE",
    "mic_code": "XNYS",
    "country": "United States"
  },
  {
    "symbol": "VTI",
    "name": "Vanguard Total Stock Market Index Fund ETF Shares",
    "currency": "USD",
    "exchange": "NYSE",
    "mic_code": "XNYS",
    "country": "Unites States"
  },
  {...}
]

// with &show_plan=true
{
  "data": [
    {
      "symbol": "SPY",
      "name": "SPDR S&P 500 ETF Trust",
      "currency": "MXN",
      "exchange": "BMV",
      "mic_code": "XMEX",
      "country": "Mexico",
      "access": {
        "global": "Level B",
        "plan": "Pro"
      }
    },
    {
      "symbol": "SPY",
      "name": "SPDR S&P 500 ETF Trust",
      "currency": "USD",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "country": "United States",
      "access": {
        "global": "Basic",
        "plan": "Basic"
      }
    },
    {...}
  ],
  "status": "ok"
}

HTTP route

/etf

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
exchange • Parameter is optional
• Filter by exchange name or mic code
mic_code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false
include_delisted • Parameter is optional
• Include delisted identifiers
• Boolean; Default false

Response

Key Description
symbol instrument symbol (ticker)
name full name of instrument
currency currency in which instrument is traded by ISO 4217 standard
exchange exchange where ETF is traded
mic_code market identifier code (MIC) under ISO 10383 standard

JSON request example

https://api.twelvedata.com/etf

https://api.twelvedata.com/etf?symbol=QQQ

Downloadable CSV example

https://api.twelvedata.com/etf?format=CSV

Indices List

This API call return array of indices available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/indices

This request will return JSON with the following structure

[
  {
    "symbol": "IXIC",
    "name": "NASDAQ Composite",
    "country": "United States",
    "currency": "USD"
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
  },
  {
    "symbol": "SPX",
    "name": "S&P 500",
    "country": "United States",
    "currency": "USD"
    "exchange": "NYSE",
    "mic_code": "XNYS",
  },
  {...}
]

// with &show_plan=true
{
  "data": [
    {
      "symbol": "STI",
      "name": "STI Index",
      "country": "Singapore",
      "currency": "SGD",
      "exchange": "SGX",
      "mic_code": "XSES",
      "access": {
        "global": "Level B",
        "plan": "Pro"
      }
    }
  ],
  "status": "ok"
}

HTTP route

/indices

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
exchange • Parameter is optional
• Filter by exchange name or mic code
mic_code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false
include_delisted • Parameter is optional
• Include delisted identifiers
• Boolean; Default false

Response

Key Description
symbol instrument symbol (ticker)
name full name of instrument
country country where the index is located
currency currency in which instrument is traded by ISO 4217 standard
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard

JSON request example

https://api.twelvedata.com/indices

https://api.twelvedata.com/indices?symbol=IXIC

Downloadable CSV example

https://api.twelvedata.com/indices?format=CSV

ExchangesHigh Demand

This API call return array of stock, ETF or index exchanges available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/exchanges

This request will return JSON with the following structure

[
  {
    "name": "NASDAQ",
    "code": "XNGS",
    "country": "United States",
    "timezone": "America/New_York"
  },
  {
    "name": "NYSE",
    "code": "XNYS",
    "country": "United States",
    "timezone": "America/New_York"
  },
  {
    "name": "SGX",
    "code": "XSES",
    "country": "Singapore",
    "timezone": "Asia/Singapore"
    },
  {...}
]

// with &show_plan=true
{
  "data": [
    {
      "name": "SSE",
      "code": "XSHG",
      "country": "China",
      "timezone": "Asia/Shanghai",
      "access": {
        "global": "Level B",
        "plan": "Pro"
      }
    },
    {
      "name": "SZSE",
      "code": "XSHE",
      "country": "China",
      "timezone": "Asia/Shanghai",
      "access": {
        "global": "Level B",
        "plan": "Pro"
      }
    }
  ],
  "status": "ok"
}

HTTP route

/exchanges

API credits

1 per request

API parameters

Parameter Details
type • Parameter is optional
• Value can be stock, etf or index; Default stock
name • Parameter is optional
• Filter by exchange name
code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false

Response

Key Description
name name of exchange
code market identifier code (MIC) under ISO 10383 standard
country country to which stock exchange belongs to
timezone time zone where exchange is located

JSON request example

https://api.twelvedata.com/exchanges

https://api.twelvedata.com/exchanges?type=etf

Downloadable CSV example

https://api.twelvedata.com/exchanges?format=CSV

Cryptocurrency Exchanges

This API call return array of cryptocurrency exchanges available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/cryptocurrency_exchanges

This request will return JSON with the following structure

[
  {
    "name": "Binance",
  },
  {
    "name": "Upbit",
  },
  {
    "name": "Huobi",
  },
  {
    "name": "Bittrex",
  },
  {
    "name": "Bithumb",
  },
  {...}
]

HTTP route

/cryptocurrency_exchanges

API credits

1 per request

API parameters

Parameter Details
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;

Response

Key Description
name name of cryptocurrency exchange

JSON request example

https://api.twelvedata.com/cryptocurrency_exchanges

Downloadable CSV example

https://api.twelvedata.com/cryptocurrency_exchanges?format=CSV

Technical Indicators Interface

This API call return array of objects with available technical indicators. This endpoint might be used to build an abstract interface to make more convenient API calls from the application.

HTTP request example

https://api.twelvedata.com/technical_indicators

This request will return JSON with the following structure

[
  {
    "macd": {
      "enable": true,
      "full_name": "Moving Average Convergence Divergence",
      "description": "Moving Average Convergence Divergence(MACD) is a trend following momentum indicator, which works by subtracting the longer moving average from the shorter one. MACD has an unstable period ~ 100.",
      "type": "Momentum Indicators",
      "overlay": false,
      "parameters": {
        "series_type": {
          "default": "close",
          "range": ["open", "high", "low", "close"],
          "type": "string"
        },
        "fast_period": {
          "default": 12,
          "min_range": 1,
          "type": "int"
        },
        "slow_period": {
          "default": 26,
          "min_range": 1,
          "type": "int"
        },
        "signal_period": {
          "default": 9,
          "min_range": 1,
          "type": "int"
        }
      },
      "output_values": {
        "macd": {
          "default_color": "#2708A0",
          "display": "line"
        },
        "macd_signal": {
          "default_color": "#B80C09",
          "display": "line"
        },
        "macd_hist": {
          "default_color": "#B80C09",
          "display": "histogram"
        }
      }
    }
  },
  {...}
]

HTTP route

/technical_indicators

API credits

1 per request

API parameters

no input parameters

Response

Key Description
enable if the indicator is tested, approved and is recommended for use returns true, otherwise returns false
full_name full indicator name
description brief description of the indicator
type group to which indicator belongs to
overlay if indicator should be plotted over price bars returns true, otherwise returns false
parameters an array of input parameters where each object might contain:
default: specifies parameter value set by default
range: an array of available parameter values
min_range: if the parameter has lower bound in order to ensure correct calculation
max_range: if the parameter has upper bound in order to ensure correct calculation
type: type of parameter might be string, int, float or array
output_values an array of output values where each object might contain:
default_color: suggested color for displaying returns hex color code
display: how output value should be rendered, might be line, histogram, candle or points
min_range: if output value has minimum bound
max_range: if output value has maximum bound
tinting an array of tinting values used for proper indicator coloring
display: render pattern
color: returns hex color code
transparency: transparency level returns float value from 0 to 1 level
lower_bound: lower bound of tinting might be either number or one of the return parameters
upper_bound: upper bound of tinting might be either number or one of the return parameters

JSON request example

https://api.twelvedata.com/technical_indicators

This method helps to find the best matching symbol. It can be used as the base for custom lookups. The response is returned in descending order, with the most relevant instrument at the beginning.

HTTP request example

https://api.twelvedata.com/symbol_search?symbol=AA

This request will return JSON with the following structure

{
  "data": [
    {
      "symbol": "AA",
      "instrument_name": "Alcoa Corp",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "exchange_timezone": "America/New_York",
      "instrument_type": "Common Stock",
      "country": "United States",
      "currency": "USD"
    },
    {
      "symbol": "AAA",
      "instrument_name": "BetaShares Australian High Interest Cash ETF",
      "exchange": "ASX",
      "mic_code": "XASX",
      "exchange_timezone": "Australia/Sydney",
      "instrument_type": "ETF",
      "country": "Australia",
      "currency": "AUD"
    },
    {...}
  ],
  "status": "ok"
}

// with &show_plan=true
{
  "data": [
    {
      "symbol": "AA",
      "instrument_name": "Alcoa Corp",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "exchange_timezone": "America/New_York",
      "instrument_type": "Common Stock",
      "country": "United States",
      "currency": "USD",
      "access": {
        "global": "Basic",
        "plan": "Basic"
      }
    },
    {
      "symbol": "AAA",
      "instrument_name": "Listed Funds Trust - AAF First Priority CLO Bond ETF",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "exchange_timezone": "America/New_York",
      "instrument_type": "ETF",
      "country": "United States",
      "currency": "USD",
      "access": {
        "global": "Basic",
        "plan": "Basic"
      }
    },
    {...}
  ],
  "status": "ok"
}

HTTP route

/symbol_search

API credits

1 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol to search
outputsize • Parameter is optional
• Number of matches in response
• Default 30, Max 120;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false

Response

Key Description
symbol ticker symbol of instrument
instrument_name name of exchange
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
exchange_timezone time zone where exchange is located
instrument_type type of instrument
country country to which stock exchange belongs to

JSON request example

https://api.twelvedata.com/symbol_search?symbol=AA

https://api.twelvedata.com/symbol_search?symbol=XAU/

https://api.twelvedata.com/symbol_search?symbol=RY&show_plan=true

Earliest Timestamp

This method returns the first available DateTime for a given instrument at the specific interval.

HTTP request example

https://api.twelvedata.com/earliest_timestamp?symbol=AAPL&interval=1day&apikey=your_api_key

This request will return JSON with the following structure

{
  "datetime": "1980-12-12",
  "unix_time": 345427200
}

HTTP route

/earliest_timestamp

API credits

1 per request

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
datetime earliest datetime, the format depends on interval
unix_time datetime converted to UNIX timestamp

JSON request example

https://api.twelvedata.com/earliest_timestamp?symbol=AAPL&interval=1day&apikey=demo

https://api.twelvedata.com/earliest_timestamp?symbol=AAPL,MSFT&interval=1day&apikey=demo

https://api.twelvedata.com/earliest_timestamp?symbol=EUR/USD&interval=1min&apikey=demo

Market State

Check the state of all available exchanges, time to open, and time to close.

Returns all available stock exchanges by default

HTTP request example

https://api.twelvedata.com/market_state?apikey=your_api_key

This request will return JSON with the following structure

[
  {
    "name": "NYSE",
    "code": "XNYS",
    "country": "United States",
    "is_market_open": true,
    "time_after_open": "02:39:03",
    "time_to_open": "00:00:00",
    "time_to_close": "05:20:57"
  },
  {
    "name": "NYSE",
    "code": "XASE",
    "country": "United States",
    "is_market_open": true,
    "time_after_open": "02:39:03",
    "time_to_open": "00:00:00",
    "time_to_close": "05:20:57"
  },
  {
    "name": "NYSE",
    "code": "ARCX",
    "country": "United States",
    "is_market_open": true,
    "time_after_open": "02:39:03",
    "time_to_open": "00:00:00",
    "time_to_close": "05:20:57"
  },
  {
    "name": "NASDAQ",
    "code": "XNGS",
    "country": "United States",
    "is_market_open": true,
    "time_after_open": "02:39:03",
    "time_to_open": "00:00:00",
    "time_to_close": "05:20:57"
  },
  {
    "name": "NASDAQ",
    "code": "XNMS",
    "country": "United States",
    "is_market_open": true,
    "time_after_open": "02:39:03",
    "time_to_open": "00:00:00",
    "time_to_close": "05:20:57"
  },
  {...}
]

HTTP route

/market_state

API credits

1 per request

API parameters

Key Type Description
exchange string • Parameter is optional
• Takes exchange name or alpha code
code string • Parameter is optional
• Takes MIC code of exchange
country string • Parameter is optional
• Takes country name or alpha code
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
name the full name of exchange
code Market Identifier Codes (MIC) under ISO 10383 standard
country country where exchange is located
is_market_open true if market is open; false if closed
time_after_open time after market opening HH:MM:SS format; if currently closed - returns 00:00:00
time_to_open time to market opening in HH:MM:SS format; if currently open - returns 00:00:00
time_to_close time to market closing in HH:MM:SS format; if currently closed - returns 00:00:00

JSON request example

https://api.twelvedata.com/market_state?exchange=NYSE&apikey=demo

https://api.twelvedata.com/market_state?exchange=XMAD&apikey=demo

https://api.twelvedata.com/market_state?country=India&apikey=demo

Core Data

Core data return time series, quotes, rates, and other prices across equities, forex, cryptocurrencies, ETFs, indices along with other data types.

Time SeriesHigh Demand

This API call returns meta and time series for the requested instrument. Metaobject consists of general information about the requested symbol. Time series is the array of objects ordered by time descending with Open, High, Low, Close prices. Non-currency instruments also include volume information.

HTTP request example

https://api.twelvedata.com/time_series?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "interval": "1min",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "type": "Common Stock"
  },
  "values": [
    {
      "datetime": "2021-09-16 15:59:00",
      "open": "148.73500",
      "high": "148.86000",
      "low": "148.73000",
      "close": "148.85001",
      "volume": "624277"
    },
    {
      "datetime": "2021-09-16 15:58:00",
      "open": "148.72000",
      "high": "148.78000",
      "low": "148.70000",
      "close": "148.74001",
      "volume": "274622"
    },
    {
      "datetime": "2021-09-16 15:57:00",
      "open": "148.77499",
      "high": "148.79500",
      "low": "148.71001",
      "close": "148.72501",
      "volume": "254725"
    },
    {
      "datetime": "2021-09-16 15:56:00",
      "open": "148.76500",
      "high": "148.78999",
      "low": "148.72000",
      "close": "148.78000",
      "volume": "230758"
    },
    {
      "datetime": "2021-09-16 15:55:00",
      "open": "148.80000",
      "high": "148.80000",
      "low": "148.70000",
      "close": "148.76230",
      "volume": "348577"
    }
  ],
  "status": "ok"
}

HTTP route

/time_series

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here
prepost string • Parameter is optional. Only for Pro and above plans.
• Available at the 1min, 5min, 15min, and 30min intervals for all US equities.
• Open, high, low, close values are supplied without volume.
• Default false

Response

Key Description
meta json object with request general information
datetime datetime at local exchange time referring to when the bar with specified interval was opened
open price at the opening of current bar
high highest price which occurred during the current bar
low lowest price which occurred during the current bar
close close price at the end of the bar
volume trading volume which occurred during the current bar

JSON request example

https://api.twelvedata.com/time_series?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/time_series?symbol=EUR/USD&interval=1day&outputsize=12&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/time_series?symbol=BTC/USD&interval=5min&format=CSV&apikey=demo

Exchange Rate

This API call returns real-time exchange rate for currency pair. Works with forex and cryptocurrency.

HTTP request example

https://api.twelvedata.com/exchange_rate?symbol=USD/JPY&apikey=your_api_key

This request will return JSON with the following structure

{
   "symbol": "USD/JPY",
   "rate": 105.12,
   "timestamp": 1602714051
}

HTTP route

/exchange_rate

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• The currency pair you want to request can be either forex or cryptocurrency
• Slash(/) delimiter is used
E.g. EUR/USD or BTC/ETH will be correct
date string • Parameter is optional
• If not null, will use exchange rate from a specific date or time
• Format 2006-01-02 or 2006-01-02 15:04:05
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
symbol requested currency symbol
rate real-time exchange rate for the corresponding symbol
timestamp unix timestamp of the rate

JSON request example

https://api.twelvedata.com/exchange_rate?symbol=USD/JPY&apikey=demo

https://api.twelvedata.com/exchange_rate?symbol=USD/JPY&date=2022-02-22&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/exchange_rate?symbol=EUR/USD&format=CSV&apikey=demo

Currency ConversionUseful

This API call returns real-time exchange rate and converted amount for currency pair. Works with forex and cryptocurrency.

HTTP request example

https://api.twelvedata.com/currency_conversion?symbol=USD/JPY&amount=122&apikey=your_api_key

This request will return JSON with the following structure

{
   "symbol": "USD/JPY",
   "rate": 105.12,
   "amount": 12824.64,
   "timestamp": 1602714051
}

HTTP route

/currency_conversion

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• The currency pair you want to request can be either forex or cryptocurrency
• Slash(/) delimiter is used
E.g. EUR/USD or BTC/ETH will be correct
amount number • Required parameter
• Amount of base currency to be converted into quote currency.
• Supports values in the range from 0 and above
date string • Parameter is optional
• If not null, will use exchange rate from a specific date or time
• Format 2006-01-02 or 2006-01-02 15:04:05
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
symbol requested currency symbol
rate real-time exchange rate for the corresponding symbol
amount amount of converted currency
timestamp unix timestamp of the rate

JSON request example

https://api.twelvedata.com/currency_conversion?symbol=USD/JPY&amount=122&apikey=demo

https://api.twelvedata.com/currency_conversion?symbol=USD/JPY&amount=122&date=2022-02-22&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/currency_conversion?symbol=EUR/USD&amount=15&format=CSV&apikey=demo

QuoteHigh Demand

Quote endpoint is an efficient method to retrieve the latest quote of the selected instrument.

HTTP request example

https://api.twelvedata.com/quote?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "symbol": "AAPL",
  "name": "Apple Inc",
  "exchange": "NASDAQ",
  "mic_code": "XNAS",
  "currency": "USD",
  "datetime": "2021-09-16",
  "timestamp": 1631772000,
  "open": "148.44000",
  "high": "148.96840",
  "low": "147.22099",
  "close": "148.85001",
  "volume": "67903927",
  "previous_close": "149.09000",
  "change": "-0.23999",
  "percent_change": "-0.16097",
  "average_volume": "83571571",
  "rolling_1d_change": "123.123",
  "rolling_7d_change": "123.123",
  "rolling_period_change": "123.123"
  "is_market_open": false,
  "fifty_two_week": {
    "low": "103.10000",
    "high": "157.25999",
    "low_change": "45.75001",
    "high_change": "-8.40999",
    "low_change_percent": "44.37440",
    "high_change_percent": "-5.34782",
    "range": "103.099998 - 157.259995"
  },
  "extended_change": "0.09",
  "extended_percent_change": "0.05",
  "extended_price": "125.22",
  "extended_timestamp": 1649845281
}

HTTP route

/quote

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Optional parameter
• Interval of the quote
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month; Default 1day
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
volume_time_period string • Optional parameter
• Number of periods for Average Volume
• Default 9
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here
prepost string • Parameter is optional. Only for Pro and above plans.
• Available at the 1min, 5min, 15min, and 30min intervals for all US equities.
• Open, high, low, close values are supplied without volume.
• Default false
eod string • Optional parameter
• If true, then return data for closed day
rolling_period string • Optional parameter
• Number of hours for calculate rolling change at period. By default set to 24, it can be in range [1, 168].

Response

Key Description
symbol symbol passed
name name of the instrument
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
currency currency in which the equity is denominated
timestamp unix timestamp of the last price
datetime datetime in defined timezone referring to when the bar with specified interval was opened
open price at the opening of current bar
high highest price which occurred during the current bar
low lowest price which occurred during the current bar
close close price at the end of the bar
volume trading volume during the bar
previous_close close price at the end of the previous bar
change close - previous_close
percent_change (close - previous_close) / previous_close * 100
average_volume average volume of the specified period
rolling_1d_change percent change in price between the current and the backward one, where period is 1 day, available for crypto
rolling_7d_change percent change in price between the current and the backward one, where period is 7 days, available for crypto
rolling_period_change percent change in price between the current and the backward one, where period specified in request param rolling_period, available for crypto
is_market_open true if market is open; false if closed
fifty_two_week collection of 52-week metrics
extended_change diff between the regular close price and the latest extended price
extended_percent_change percent change in price between the regular close price and the latest extended price
extended_price latest extended price
extended_timestamp unix timestamp of the last extended price

JSON request example

https://api.twelvedata.com/quote?symbol=AAPL&apikey=demo

https://api.twelvedata.com/quote?symbol=EUR/USD&interval=30min&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/quote?symbol=IXIC&type=Index&interval=5min&format=CSV&apikey=demo

Real-Time PriceHigh Demand

This endpoint is a lightweight method that allows retrieving only the real-time price of the selected instrument.

HTTP request example

https://api.twelvedata.com/price?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
    "price": "200.99001"
}

HTTP route

/price

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here
prepost string • Parameter is optional. Only for Pro and above plans.
• Available at the 1min, 5min, 15min, and 30min intervals for all US equities.
• Open, high, low, close values are supplied without volume.
• Default false
dp string • Parameter is optional
• Specifies the number of decimal places for floating values
• Should be in range [0,11] inclusive; default 5

Response

Key Description
price real-time or the latest available price

JSON request example

https://api.twelvedata.com/price?symbol=AAPL&apikey=demo

https://api.twelvedata.com/price?symbol=TRP&country=Canada&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/price?symbol=USD/JPY&format=CSV&apikey=demo

End of Day Price

This endpoint returns the latest End of Day (EOD) price of an instrument.

HTTP request example

https://api.twelvedata.com/eod?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "symbol": "AAPL",
  "exchange": "NASDAQ",
  "mic_code": "XNAS",
  "currency": "USD",
  "datetime": "2021-09-16",
  "close": "148.79"
}

HTTP route

/eod

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
apikey string • Required parameter
• Your API key, which you can obtain for free here
prepost string • Parameter is optional. Only for Pro and above plans.
• Available at the 1min, 5min, 15min, and 30min intervals for all US equities.
• Open, high, low, close values are supplied without volume.
• Default false
dp string • Parameter is optional
• Specifies the number of decimal places for floating values
• Should be in range [0,11] inclusive; default 5

Response

Key Description
symbol symbol passed
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
currency currency in which instrument is denominated
datetime datetime in defined timezone referring to when the bar with specified interval was opened
close the most recent end of day close price

JSON request example

https://api.twelvedata.com/eod?symbol=AAPL&apikey=demo

https://api.twelvedata.com/eod?symbol=TRP&country=Canada&apikey=demo

Market Movers

Get the list of the top gaining or losing stocks today.

Top gainers are ordered by the highest rate of price increase since the previous day''s close. Top losers are ordered by the highest percentage of price decrease since the last day.

Data is available for all international equities, forex, crypto.

HTTP request example

https://api.twelvedata.com/market_movers/stocks?apikey=your_api_key

This request will return JSON with the following structure

{
  "values": [
    {
      "symbol": "BSET",
      "name": "Bassett Furniture Industries Inc",
      "exchange": "NASDAQ",
      "mic_code": "XNAS",
      "datetime": "2022-01-31 09:34:00",
      "last": 17.25,
      "high": 17.35,
      "low": 15.90999,
      "volume": 108297,
      "change": 3.31,
      "percent_change": 23.74462
    },
    {
      "symbol": "TWKS",
      "name": "Thoughtworks Holding, Inc.",
      "exchange": "NASDAQ",
      "mic_code": "XNAS",
      "datetime": "2022-01-31 09:34:40",
      "last": 20.09,
      "high": 19.62999,
      "low": 18.29999,
      "volume": 392376,
      "change": 3.98,
      "percent_change": 20.84861
    },
    {
      "symbol": "RMED",
      "name": "RA Medical Systems Inc",
      "exchange": "NYSE",
      "mic_code": "XNAS",
      "datetime": "2022-01-31 09:33:50",
      "last": 0.984,
      "high": 0.98519,
      "low": 0.984,
      "volume": 4480,
      "change": 0.159,
      "percent_change": 17.84511
    }
  ],
  "status": "ok"
}

HTTP routes

/market_movers/stocks
/market_movers/etf
/market_movers/mutual_funds
/market_movers/forex
/market_movers/crypto

API credits

100 per request

API parameters

Key Type Description
direction string • Parameter is optional
• Specifies direction of the snapshot gainers or losers
• By default gainers
outputsize string • Parameter is optional
• Specifies the size of the snapshot
• Can be in a range from 1 to 50; default 30
country string • Parameter is optional
• Country of the snapshot, applicable to non-currencies only
• Takes country name or alpha code; default USA
apikey string • Required parameter
• Your API key, which you can obtain for free here
dp string • Parameter is optional
• Specifies the number of decimal places for floating values
• Should be in range [0,11] inclusive; default 5

Response

Key Description
symbol the exchange symbol ticker
name the official name of the instrument
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
datetime the last updated datetime timestamp
last the latest available price for the symbol today
high the highest price for the symbol today
low the lowest price for the symbol today
volume the trading volume of the symbol today
change the value of the change since the previous day
percent_change the percentage change since the previous day

JSON request example

https://api.twelvedata.com/market_movers/stocks?country=india&outputsize=20&apikey=demo

https://api.twelvedata.com/market_movers/forex?direction=losers&apikey=demo

Mutual Funds

MFs ListUseful

This API request returns a list of mutual funds available at Twelve Data. Sorting is in descending order by total assets value. The list is updated daily.

HTTP request example

https://api.twelvedata.com/mutual_funds/list?apikey=your_api_key

This request will return JSON with the following structure

{
  "result": {
    "count": 1000,
    "list": [
      {
        "symbol": "VFIAX",
        "name": "Vanguard 500 Index Admiral",
        "country": "United States",
        "fund_family": "Vanguard",
        "fund_type": "Large Blend",
        "performance_rating": 5,
        "risk_rating": 4
      },
      {
        "symbol": "0P00016LWW",
        "name": "RBC Select Balanced Portfolio O",
        "country": "Canada",
        "fund_family": "RBC Global Asset Management Inc.",
        "fund_type": "Global Neutral Balanced",
        "performance_rating": 3,
        "risk_rating": 3
      },
      {
        "symbol": "0P00005WT4",
        "name": "Kotak Savings Fund Monthly Dividend Payout",
        "country": "India",
        "fund_family": "Kotak Mahindra Asset Management Co Ltd",
        "fund_type": "Ultrashort Bond",
        "performance_rating": 3,
        "risk_rating": 3
      },
      {...}
    ]
  },
  "status": "ok"
}

HTTP route

/mutual_funds/list

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
country • Parameter is optional
• Filter by country name or alpha code
fund_family • Parameter is optional
• Filter by investment company that manages the fund
fund_type • Parameter is optional
• Filter by the type of fund
performance_rating • Parameter is optional
• Filter by performance rating from 0 to 5
risk_rating • Parameter is optional
• Filter by risk rating from 0 to 5
page • Parameter is optional
• Page number; default 1
outputsize • Parameter is optional
• Number of records in response; default 100
apikey • Required parameter
• Your API key at the Basic plan or above

Response

Key Description
count total number of matching funds
symbol fund symbol ticker
name fund name
country country of fund incorporation
fund_family investment company that manages the fund
fund_type type of fund
performance_rating performance rating from 0 to 5
risk_rating risk rating from 0 to 5

JSON request example

https://api.twelvedata.com/mutual_funds/list?apikey=demo

https://api.twelvedata.com/mutual_funds/list?fund_family=Vanguard&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/mutual_funds/list?format=CSV&apikey=demo

MFs Family List

This API request returns a list of mutual funds families.

HTTP request example

https://api.twelvedata.com/mutual_funds/family?apikey=your_api_key

This request will return JSON with the following structure

{
  "result": {
    "India": [
      "Aberdeen Standard Fund Managers Limited",
      "Aditya Birla Sun Life AMC Ltd",
      "Aditya Birla Sun Life Insurance Company Limited",
      "Aegon Life Insurance Company Ltd.",
      "Aviva Life Insur Co. India Pvt. Ltd.",
      "Axis Asset Management Company Limited",
      "Bajaj Allianz Life Insurance Company Ltd",
      "Baring International Fund Mgrs (Ireland) Limited",
      "Baroda Asset Management India Limited"
    ],
    "United States": [
      "Aegon Asset Management UK PLC",
      "Ampega Investment GmbH",
      "Aviva SpA",
      "BBVA Asset Management SA SGIIC",
      "Caser Pensiones EGFP",
      "HSBC Investment Funds (HK) Limited",
      "Premier Portfolio Managers Limited",
      "SEI Investments Global Limited",
      "Vanguard"
    ]
  },
  "status": "ok"
}

HTTP route

/mutual_funds/family

API credits

1 per request

API parameters

Parameter Details
country • Parameter is optional
• Filter by country name or alpha code
fund_family • Parameter is optional
• Filter by investment company that manages the fund
apikey • Required parameter
• Your API key at the Basic plan or above

Response

Key Description
result all available fund families segmented by country

JSON request example

https://api.twelvedata.com/mutual_funds/family?apikey=demo

https://api.twelvedata.com/mutual_funds/family?country=US&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/mutual_funds/family?format=CSV&apikey=demo

MFs Type List

This API request returns a list of mutual funds types.

HTTP request example

https://api.twelvedata.com/mutual_funds/type?apikey=your_api_key

This request will return JSON with the following structure

{
  "result": {
    "Singapore": [
      "Property - Indirect Asia",
      "Sector Equity Water",
      "SGD Bond",
      "Singapore Equity",
      "Taiwan Large-Cap Equity"
    ],
    "United States": [
      "Asia-Pacific ex-Japan Equity",
      "EUR Flexible Allocation - Global",
      "Euro Short Bond PP",
      "Large Blend",
      "Other Allocation"
    ]
  },
  "status": "ok"
}

HTTP route

/mutual_funds/type

API credits

1 per request

API parameters

Parameter Details
country • Parameter is optional
• Filter by country name or alpha code
fund_type • Parameter is optional
• Filter by the type of fund
apikey • Required parameter
• Your API key at the Basic plan or above

Response

Key Description
result all available fund types segmented by country

JSON request example

https://api.twelvedata.com/mutual_funds/type?apikey=demo

https://api.twelvedata.com/mutual_funds/type?country=US&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/mutual_funds/type?format=CSV&apikey=demo

All dataHigh Demand

This API request returns a complete breakdown of a mutual fund, including summary, performance, risk, ratings, composition, purchase_info, and sustainability.

HTTP request example

https://api.twelvedata.com/mutual_funds/world?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "summary": {
      "symbol": "VFIAX",
      "name": "Vanguard 500 Index Fund Admiral Shares",
      "fund_family": "Vanguard",
      "fund_type": "Large Blend",
      "currency": "USD",
      "share_class_inception_date": "2000-11-13",
      "ytd_return": -0.05036,
      "expense_ratio_net": 0.0004,
      "yield": 0.0133,
      "nav": 411.2,
      "min_investment": 3000,
      "turnover_rate": 0.04,
      "net_assets": 753409982464,
      "overview": "The investment seeks to track the performance of the Standard & Poor's 500 Index that measures the investment return of large-capitalization stocks.  The fund employs an indexing investment approach designed to track the performance of the Standard & Poor's 500 Index, a widely recognized benchmark of U.S. stock market performance that is dominated by the stocks of large U.S. companies. The advisor attempts to replicate the target index by investing all, or substantially all, of its assets in the stocks that make up the index, holding each stock in approximately the same proportion as its weighting in the index.",
      "people": [
        {
          "name": "Michelle M. Louie",
          "tenure_since": "2017-11-30"
        }
      ]
    },
    "performance": {
      "trailing_returns": [
        {
          "period": "ytd",
          "share_class_return": -0.05036,
          "category_return": 0.1484,
          "rank_in_category": 42
        },
        {
          "period": "1_month",
          "share_class_return": 0.04934,
          "category_return": 0.0165,
          "rank_in_category": 31
        },
        {
          "period": "3_month",
          "share_class_return": -0.03611,
          "category_return": 0.0755,
          "rank_in_category": 27
        },
        {
          "period": "1_year",
          "share_class_return": 0.16053,
          "category_return": 0.4047,
          "rank_in_category": 51
        },
        {
          "period": "3_year",
          "share_class_return": 0.19197,
          "category_return": 0.1677,
          "rank_in_category": 27
        },
        {
          "period": "5_year",
          "share_class_return": 0.1616,
          "category_return": 0.16149,
          "rank_in_category": 26
        },
        {
          "period": "10_year",
          "share_class_return": 0.1468,
          "category_return": 0.1321,
          "rank_in_category": 0
        }
      ],
      "annual_total_returns": [
        {
          "year": 2021,
          "share_class_return": 0.28664,
          "category_return": null
        },
        {
          "year": 2020,
          "share_class_return": 0.18366,
          "category_return": 0.15827
        },
        {
          "year": 2019,
          "share_class_return": 0.31455,
          "category_return": 0.28776
        },
        {
          "year": 2018,
          "share_class_return": -0.04427,
          "category_return": -0.06269
        },
        {
          "year": 2017,
          "share_class_return": 0.21785,
          "category_return": 0.20438
        },
        {
          "year": 2016,
          "share_class_return": 0.11926,
          "category_return": 0.1036891
        },
        {
          "year": 2015,
          "share_class_return": 0.01362,
          "category_return": -0.01069
        },
        {
          "year": 2014,
          "share_class_return": 0.13642,
          "category_return": 0.1096
        },
        {
          "year": 2013,
          "share_class_return": 0.32333,
          "category_return": 0.315
        },
        {
          "year": 2012,
          "share_class_return": 0.15964,
          "category_return": 0.14961
        },
        {
          "year": 2011,
          "share_class_return": 0.02084,
          "category_return": -0.01271
        },
        {
          "year": 2010,
          "share_class_return": 0.1505,
          "category_return": 0.14006
        },
        {
          "year": 2009,
          "share_class_return": 0.2662,
          "category_return": 0.2817
        },
        {
          "year": 2008,
          "share_class_return": -0.36969,
          "category_return": -0.37791
        },
        {
          "year": 2007,
          "share_class_return": 0.0547,
          "category_return": 0.0616
        },
        {
          "year": 2006,
          "share_class_return": 0.15747,
          "category_return": 0.14167
        },
        {
          "year": 2005,
          "share_class_return": 0.04869,
          "category_return": 0.05877
        },
        {
          "year": 2004,
          "share_class_return": 0.10823,
          "category_return": 0.10024
        },
        {
          "year": 2003,
          "share_class_return": 0.28593,
          "category_return": 0.27046
        },
        {
          "year": 2002,
          "share_class_return": -0.22097,
          "category_return": -0.2225
        },
        {
          "year": 2001,
          "share_class_return": -0.11976,
          "category_return": -0.13502
        }
      ],
      "quarterly_total_returns": [
        {
          "year": 2021,
          "q1": 0.06175,
          "q2": 0.08537,
          "q3": 0.0057,
          "q4": 0.11015
        },
        {
          "year": 2020,
          "q1": -0.19611,
          "q2": 0.20543,
          "q3": 0.08918,
          "q4": 0.12146
        },
        {
          "year": 2019,
          "q1": 0.13645,
          "q2": 0.04298,
          "q3": 0.01691,
          "q4": 0.0906
        },
        {
          "year": 2018,
          "q1": -0.00768,
          "q2": 0.03422,
          "q3": 0.07699,
          "q4": -0.13532
        },
        {
          "year": 2017,
          "q1": 0.06052,
          "q2": 0.03073,
          "q3": 0.04475,
          "q4": 0.06638
        },
        {
          "year": 2016,
          "q1": 0.01337,
          "q2": 0.02445,
          "q3": 0.03844,
          "q4": 0.03821
        },
        {
          "year": 2015,
          "q1": 0.00944,
          "q2": 0.00282,
          "q3": -0.0645,
          "q4": 0.07036
        },
        {
          "year": 2014,
          "q1": 0.01794,
          "q2": 0.05221,
          "q3": 0.01120,
          "q4": 0.04922
        },
        {
          "year": 2013,
          "q1": 0.106,
          "q2": 0.02897,
          "q3": 0.05234,
          "q4": 0.10495
        },
        {
          "year": 2012,
          "q1": 0.12572,
          "q2": -0.02751,
          "q3": 0.0634,
          "q4": -0.00388
        },
        {
          "year": 2011,
          "q1": 0.05901,
          "q2": 0.00098,
          "q3": -0.13878,
          "q4": 0.11819
        },
        {
          "year": 2010,
          "q1": 0.05379,
          "q2": -0.11426,
          "q3": 0.11291,
          "q4": 0.10755
        },
        {
          "year": 2009,
          "q1": -0.10974,
          "q2": 0.15992,
          "q3": 0.15613,
          "q4": 0.06059
        },
        {
          "year": 2008,
          "q1": -0.09452,
          "q2": -0.02733,
          "q3": -0.08339,
          "q4": -0.21921
        },
        {
          "year": 2007,
          "q1": 0.00627,
          "q2": 0.06258,
          "q3": 0.0205,
          "q4": -0.03343
        },
        {
          "year": 2006,
          "q1": 0.04212,
          "q2": -0.01451,
          "q3": 0.05646,
          "q4": 0.06680
        },
        {
          "year": 2005,
          "q1": -0.02143,
          "q2": 0.01354,
          "q3": 0.03590,
          "q4": 0.02068
        },
        {
          "year": 2004,
          "q1": 0.0167,
          "q2": 0.01705,
          "q3": -0.01875,
          "q4": 0.09222
        },
        {
          "year": 2003,
          "q1": -0.03172,
          "q2": 0.15403,
          "q3": 0.02615,
          "q4": 0.12147
        },
        {
          "year": 2002,
          "q1": 0.00249,
          "q2": -0.1342,
          "q3": -0.17203,
          "q4": 0.08403
        },
        {
          "year": 2001,
          "q1": -0.11883,
          "q2": 0.05824,
          "q3": -0.14704,
          "q4": 0.10669
        }
      ],
      "load_adjusted_return": [
        {
          "period": "1_year",
          "return": 0.4076
        },
        {
          "period": "3_year",
          "return": 0.1864
        },
        {
          "period": "5_year",
          "return": 0.1761
        },
        {
          "period": "10_year",
          "return": 0.148
        }
      ]
    },
    "risk": {
      "volatility_measures": [
        {
          "period": "3_year",
          "alpha": -0.03,
          "alpha_category": -0.0158,
          "beta": 1,
          "beta_category": 0.01,
          "mean_annual_return": 1.58,
          "mean_annual_return_category": 0.0145,
          "r_squared": 100,
          "r_squared_category": 0.9547,
          "std": 18.52,
          "std_category": 0.19,
          "sharpe_ratio": 0.95,
          "sharpe_ratio_category": 0.0085,
          "treynor_ratio": 17.41,
          "treynor_ratio_category": 0.1559
        },
        {
          "period": "5_year",
          "alpha": -0.03,
          "alpha_category": -0.01289,
          "beta": 1,
          "beta_category": 0.01,
          "mean_annual_return": 1.45,
          "mean_annual_return_category": 0.0135,
          "r_squared": 100,
          "r_squared_category": 0.9492,
          "std": 14.99,
          "std_category": 0.1547,
          "sharpe_ratio": 1.08,
          "sharpe_ratio_category": 0.0098,
          "treynor_ratio": 16.46,
          "treynor_ratio_category": 0.1499
        },
        {
          "period": "10_year",
          "alpha": -0.03,
          "alpha_category": -0.0156,
          "beta": 1,
          "beta_category": 0.0101,
          "mean_annual_return": 1.23,
          "mean_annual_return_category": 0.0112,
          "r_squared": 100,
          "r_squared_category": 0.9489,
          "std": 13.59,
          "std_category": 0.1417,
          "sharpe_ratio": 1.04,
          "sharpe_ratio_category": 0.0091,
          "treynor_ratio": 14.19,
          "treynor_ratio_category": 0.125
        }
      ],
      "valuation_metrics": {
        "price_to_earnings": 26.46,
        "price_to_earnings_category": 26.32,
        "price_to_book": 4.42,
        "price_to_book_category": 4.98,
        "price_to_sales": 2.96,
        "price_to_sales_category": 2.79,
        "price_to_cashflow": 17.57,
        "price_to_cashflow_category": 17.61,
        "median_market_capitalization": 197452,
        "median_market_capitalization_category": 265875,
        "3_year_earnings_growth": 18.72,
        "3_year_earnings_growths_category": 19.53
      }
    },
    "ratings": {
      "performance_rating": 5,
      "risk_rating": 3,
      "return_rating": 4
    },
    "composition": {
      "major_market_sectors": [
        {
          "sector": "Technology",
          "weight": 0.24239
        },
        {
          "sector": "Financial Services",
          "weight": 0.142
        },
        {
          "sector": "Healthcare",
          "weight": 0.131
        },
        {
          "sector": "Consumer Cyclical",
          "weight": 0.1201
        },
        {
          "sector": "Communication Services",
          "weight": 0.1114
        },
        {
          "sector": "Industrials",
          "weight": 0.08859
        },
        {
          "sector": "Consumer Defensive",
          "weight": 0.06320
        },
        {
          "sector": "Energy",
          "weight": 0.02839
        },
        {
          "sector": "Realestate",
          "weight": 0.02579
        },
        {
          "sector": "Utilities",
          "weight": 0.0243
        },
        {
          "sector": "Basic Materials",
          "weight": 0.0227
        }
      ],
      "asset_allocation": {
        "cash": 0.0004,
        "stocks": 0.9996,
        "preferred_stocks": 0,
        "convertables": 0,
        "bonds": 0,
        "others": 0
      },
      "top_holdings": [
        {
          "symbol": "AAPL",
          "name": "Apple Inc",
          "weight": 0.0592
        },
        {
          "symbol": "MSFT",
          "name": "Microsoft Corp",
          "weight": 0.05619
        },
        {
          "symbol": "AMZN",
          "name": "Amazon.com Inc",
          "weight": 0.04059
        },
        {
          "symbol": "FB",
          "name": "Facebook Inc Class A",
          "weight": 0.0229
        },
        {
          "symbol": "GOOGL",
          "name": "Alphabet Inc Class A",
          "weight": 0.0202
        },
        {
          "symbol": "GOOG",
          "name": "Alphabet Inc Class C",
          "weight": 0.0197
        },
        {
          "symbol": "BRK.B",
          "name": "Berkshire Hathaway Inc Class B",
          "weight": 0.0144
        },
        {
          "symbol": "TSLA",
          "name": "Tesla Inc",
          "weight": 0.0144
        },
        {
          "symbol": "NVDA",
          "name": "NVIDIA Corp",
          "weight": 0.0137
        },
        {
          "symbol": "JPM",
          "name": "JPMorgan Chase & Co",
          "weight": 0.01299
        }
      ],
      "bond_breakdown": {
        "average_maturity": {
          "fund": null,
          "category": null
        },
        "average_duration": {
          "fund": null,
          "category": -1.15
        },
        "credit_quality": [
          {
            "grade": "U.S. Government",
            "weight": 0
          },
          {
            "grade": "AAA",
            "weight": 0
          },
          {
            "grade": "AA",
            "weight": 0
          },
          {
            "grade": "A",
            "weight": 0
          },
          {
            "grade": "BBB",
            "weight": 0
          },
          {
            "grade": "BB",
            "weight": 0
          },
          {
            "grade": "B",
            "weight": 0
          },
          {
            "grade": "Below B",
            "weight": 0
          },
          {
            "grade": "Not Rated",
            "weight": 0
          }
        ]
      }
    },
    "purchase_info": {
      "expenses": {
        "expense_ratio_gross": 0.0004,
        "expense_ratio_net": 0.0004
      },
      "minimums": {
        "initial_investment": 3000,
        "additional_investment": 1,
        "initial_ira_investment": null,
        "additional_ira_investment": null
      },
      "pricing": {
        "nav": 411.2,
        "12_month_low": 360.14,
        "12_month_high": 442.63,
        "last_month": 404.56
      },
      "brokerages": [
        "ADP Access",
        "ADP Access IPS Z",
        "ADP Access Open Fund Architecture",
        "ADP Access Tier 0",
        "ADP Advisor Access 3(21) Tier 0",
        "ADP Advisor Access Tier 0",
        "Allowab (non-advisory)",
        "Ameriprise Brokerage",
        "Avantax",
        "Bear Stearns",
        "Bear Stearns No-Load Transaction Fee",
        "Cetera Advisor Networks LLC",
        "Cetera Advisor Networks LLC- PAM, PRIME, Premier",
        "Cetera Advisors LLC",
        "Cetera Advisors LLC- PAM, PRIME, Premier",
        "Cetera Financial Specialists LLC- Premier",
        "Comerica Bank",
        "CommonWealth PPS",
        "Commonwealth (PPS Access Program)",
        "Commonwealth (PPS/Advisory)",
        "Commonwealth Universe",
        "DailyAccess Corporation FRIAG",
        "DailyAccess Corporation MATC",
        "DailyAccess Corporation Matrix",
        "DailyAccess Corporation Mid-Atlantic",
        "DailyAccess Corporation RTC",
        "DATALynx",
        "DWS Retirement Sevs Investment Offerings",
        "E TRADE Financial",
        "ETrade No Load Fee",
        "Federated TrustConnect",
        "Fidelity Institutional FundsNetwork",
        "Fidelity Retail FundsNetwork",
        "H Beck Inc.",
        "HD Vest",
        "HD Vest - Vest Advisor",
        "H&R Block Financial Advisors Inc",
        "JPMorgan",
        "JPMorgan INVEST",
        "JP MORGAN LOAD",
        "JP MORGAN NO-LOAD NTF",
        "JP MORGAN NO-LOAD TRANSACTION FEE",
        "Lincoln Investment Planning",
        "LPL SAM Eligible - 6.18.2020",
        "LPL SWM - 6.18.2020",
        "Matrix Financial Solutions",
        "Merrill Lynch",
        "Met Life Resources MFSP Alliance List",
        "Mid Atlantic Capital Corp",
        "Mid Atlantic Capital Group",
        "Mony Securities Corp",
        "Morgan Stanley - Brokerage Accounts",
        "Morgan Stanley Consulting Group Advisor",
        "Morgan Stanley Portfolio Management",
        "MSSB PlanPremier",
        "MSSB PlanPremierTPA",
        "MSWM Brokerage",
        "Nationwide Retirement Clear Adva",
        "Nationwide Retirement Flexible Advantage",
        "Nationwide Retirement Resource",
        "NM WMC",
        "Northwestern Mutual Inv Srvc, LLC",
        "NYLIM 401(k) Complete",
        "Pershing Retirement Plan Network",
        "Principal Advantage",
        "Protected Investors of America",
        "Pruco Securities LLC -PruUMA’s Mutual Funds",
        "Raymond James",
        "Raymond James WRAP Eligible",
        "RBC Wealth Management-Network Eligible",
        "RBC Wealth Management-Wrap Eligible",
        "Robert W. Baird & Co.",
        "Schwab All (Retail, Instl, Retirement)",
        "Schwab Existing Shareholders Only",
        "Schwab Institutional",
        "Schwab Institutional Only",
        "Schwab Retail",
        "Scottrade Load",
        "Scottrade NTF",
        "Scottrade TF",
        "Securities America Advisors",
        "Securities America Inc.",
        "Sterne, Agee & Leach, Inc.,",
        "SunGard Transaction Network",
        "Td Ameritrade, Inc.",
        "TD Ameritrade Institutional",
        "TD Ameritrade Institutional NTF",
        "TD Ameritrade Retail",
        "TD Ameritrade Retail NTF",
        "TD Ameritrade Trust Company",
        "Thrivent   Advisory Eligible",
        "Thrivent   Retail Eligible",
        "Trade PMR NTF",
        "Trade PMR Transaction Fee",
        "TradeStation Securities",
        "TRUSTlynx",
        "Vanguard Load",
        "Vanguard NTF",
        "Vanguard TF",
        "Waddell & Reed Choice MAP Flex",
        "WFA Fdntl Choice/PIM Updated 6.1.21",
        "WFA MF Advisory Updated 6.1.21",
        "WR Hambrecht Co LLC"
      ]
    },
    "sustainability": {
      "score": 22,
      "corporate_esg_pillars": {
        "environmental": 3.73,
        "social": 10.44,
        "governance": 7.86
      },
      "sustainable_investment": false,
      "corporate_aum": 0.99486
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world

API credits

1000 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
symbol all available fund types segmented by country
name fund name
fund_family investment company that manages the fund
fund_type type of the fund
currency currency of fund price
share_class_inception_date the date from which the fund started operations and the returns are calculated
ytd_return percentage of profit of the fund since the first trading day of the current calendar year
expense_ratio_net percentage of mutual fund assets steered toward a fund's operating expenses and fund management fees
yield income returned to its investors through interest and dividends generated by the fund's investments
nav last price of the fund
min_investment investment minimum
turnover_rate percentage rate at which mutual fund replaces its holdings on investment every year
net_assets total assets of a fund minus its total liabilities
overview description of the fund
people.name manager name
people.tenure_since manager tenuring date
trailing_returns.period period of trailing returns
trailing_returns.share_class_return fund returns (%) generated over a given period
trailing_returns.category_return same category average returns (%) generated over a given period
trailing_returns.rank_in_category rank of a fund in category by total returns
annual_total_returns.year year of total returns
annual_total_returns.share_class_return fund total returns (%) generated over a given year
annual_total_returns.category_return same category average total returns (%) generated over a given year
quarterly_total_returns.year year of a fund quarter return
quarterly_total_returns.q1 total return (%) of a fund in the first quarter
quarterly_total_returns.q2 total return (%) of a fund in the second quarter
quarterly_total_returns.q3 total return (%) of a fund in the third quarter
quarterly_total_returns.q4 total return (%) of a fund in the forth quarter
load_adjusted_return.period period of a load adjusted return
load_adjusted_return.return actual return (%) an investor sees after accounting for fees and sales charges are deducted from a mutual fund's performance
volatility_measures.period period of a measure
volatility_measures.alpha alpha score of a fund
volatility_measures.alpha_category average alpha score of a fund's category
volatility_measures.beta beta score of a fund
volatility_measures.beta_category average beta score of a fund's category
volatility_measures.mean_annual mean annual return of a fund
volatility_measures.mean_annual_category average mean annual return of a fund's category
volatility_measures.r_squared r-squared metric of a fund
volatility_measures.r_squared_category average r-squared metric of a fund's category
volatility_measures.std standard deviation of a fund
volatility_measures.std_category average standard deviation of a fund's category
volatility_measures.sharpe_ratio sharpe ratio of a fund
volatility_measures.sharpe_ratio_category average sharpe ratio of a fund's category
volatility_measures.treynor_ratio treynor ratio of a fund
volatility_measures.treynor_ratio_category average treynor ratio of a fund's category
valuation_metrics.price_to_earnings fund price to earnings metric
valuation_metrics.price_to_earnings_category average price to earnings metric of funds in the same category
valuation_metrics.price_to_book fund price to book metric
valuation_metrics.price_to_book_category average price to book metric of funds in the same category
valuation_metrics.price_to_sales fund price to sales metric
valuation_metrics.price_to_sales_category average price to sales metric of funds in the same category
valuation_metrics.price_to_cashflow fund price to cashflow metric
valuation_metrics.price_to_cashflow_category average price to cashflow metric of funds in the same category
valuation_metrics.median_market_capitalization median market capitalization of a fund
valuation_metrics.median_market_capitalization_category median market capitalization of funds in the same category
valuation_metrics.3_year_earnings_growth earnings growth over the last three years
valuation_metrics.3_year_earnings_growth_category earnings growth over the last three years of funds in the same category
performance_rating performance rating from 0 to 5
risk_rating risk rating from 0 to 5
return_rating return rating from 0 to 5
major_market_sectors.sector sector category of a fund exposure
major_market_sectors.weight weight (%) of a fund exposure in a sector
asset_allocation.cash percentage of overall portfolio composition in cash
asset_allocation.stocks percentage of overall portfolio composition in stocks
asset_allocation.preferred_stocks percentage of overall portfolio composition in preferred stocks
asset_allocation.convertables percentage of overall portfolio composition in convertable securities
asset_allocation.bonds percentage of overall portfolio composition in bond
asset_allocation.others percentage of overall portfolio composition in other forms of holding
top_holdings.symbol symbol ticker of a holding instrument
top_holdings.name name of a holding instrument
top_holdings.weight weight (%) of a holding instrument in overall portfolio composition
bond_breakdown.average_maturity.fund average maturity of bond holding of a fund
bond_breakdown.average_maturity.category average maturity of bond holding of funds in the same category
bond_breakdown.average_duration.fund average duration of bond holding of a fund
bond_breakdown.average_duration.category average duration of bond holding of funds in the same category
bond_breakdown.credit_quality.grade rating of bond holding of a fund from AAA to below B
bond_breakdown.credit_quality.weight weight of bond holding in fund portfolio
expenses.expense_ratio_gross annual cost of investing in a mutual fund
expenses.expense_ratio_net percentage of mutual fund assets steered toward a fund's operating expenses and fund management fees
minimums.initial_investment investment minimum
minimums.additional_investment minimum amount of additional investment
minimums.initial_ira_investment investment minimum for IRA
minimums.additional_ira_investment minimum amount of additional investment for IRA
pricing.nav last price of the fund
pricing.12_month_low lowest price of the fund over the last year
pricing.12_month_high highest price of the fund over the last year
pricing.last_month fund price at the end of the last month
brokerages list of brokerages where mutual fund can be purchased
sustainability.score asset-weighted average of normalized company-level ESG Scores for the covered holdings in the portfolio from 0 to 100
corporate_esg_pillars.environmental ESG environmental score
corporate_esg_pillars.social ESG social score
corporate_esg_pillars.governance ESG governance score
sustainable_investment indication that the fund discloses in their prospectus that they employ socially responsible or ESG principles in their investment selection processes
corporate_aum percentage of AUM used to calculate sustainability score

JSON request example

https://api.twelvedata.com/mutual_funds/world?symbol=VFIAX&apikey=demo

Summary

This API request returns a brief summary of a mutual fund.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/summary?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "summary": {
      "symbol": "VFIAX",
      "name": "Vanguard 500 Index Fund Admiral Shares",
      "fund_family": "Vanguard",
      "fund_type": "Large Blend",
      "currency": "USD",
      "share_class_inception_date": "2000-11-13",
      "ytd_return": -0.05036,
      "expense_ratio_net": 0.0004,
      "yield": 0.0133,
      "nav": 411.2,
      "min_investment": 3000,
      "turnover_rate": 0.04,
      "net_assets": 753409982464,
      "overview": "The investment seeks to track the performance of the Standard & Poor's 500 Index that measures the investment return of large-capitalization stocks.  The fund employs an indexing investment approach designed to track the performance of the Standard & Poor's 500 Index, a widely recognized benchmark of U.S. stock market performance that is dominated by the stocks of large U.S. companies. The advisor attempts to replicate the target index by investing all, or substantially all, of its assets in the stocks that make up the index, holding each stock in approximately the same proportion as its weighting in the index.",
      "people": [
        {
          "name": "Michelle M. Louie",
          "tenure_since": "2017-11-30"
        }
      ]
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/summary

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
symbol all available fund types segmented by country
name fund name
fund_family investment company that manages the fund
fund_type type of the fund
currency currency of fund price
share_class_inception_date the date from which the fund started operations and the returns are calculated
ytd_return percentage of profit of the fund since the first trading day of the current calendar year
expense_ratio_net percentage of mutual fund assets steered toward a fund's operating expenses and fund management fees
yield income returned to its investors through interest and dividends generated by the fund's investments
nav last price of the fund
min_investment investment minimum
turnover_rate percentage rate at which mutual fund replaces its holdings on investment every year
net_assets total assets of a fund minus its total liabilities
overview description of the fund
people.name manager name
people.tenure_since manager tenuring date

JSON request example

https://api.twelvedata.com/mutual_funds/world/summary?symbol=VFIAX&apikey=demo

PerformanceHigh Demand

This API request returns detailed performance of a mutual fund, including trailing, annual, quarterly, and load-adjusted returns.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/performance?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "performance": {
      "trailing_returns": [
        {
          "period": "ytd",
          "share_class_return": -0.05036,
          "category_return": 0.1484,
          "rank_in_category": 42
        },
        {
          "period": "1_month",
          "share_class_return": 0.04934,
          "category_return": 0.0165,
          "rank_in_category": 31
        },
        {
          "period": "3_month",
          "share_class_return": -0.03611,
          "category_return": 0.0755,
          "rank_in_category": 27
        },
        {
          "period": "1_year",
          "share_class_return": 0.16053,
          "category_return": 0.4047,
          "rank_in_category": 51
        },
        {
          "period": "3_year",
          "share_class_return": 0.19197,
          "category_return": 0.1677,
          "rank_in_category": 27
        },
        {
          "period": "5_year",
          "share_class_return": 0.1616,
          "category_return": 0.16149,
          "rank_in_category": 26
        },
        {
          "period": "10_year",
          "share_class_return": 0.1468,
          "category_return": 0.1321,
          "rank_in_category": 0
        }
      ],
      "annual_total_returns": [
        {
          "year": 2021,
          "share_class_return": 0.28664,
          "category_return": null
        },
        {
          "year": 2020,
          "share_class_return": 0.18366,
          "category_return": 0.15827
        },
        {
          "year": 2019,
          "share_class_return": 0.31455,
          "category_return": 0.28776
        },
        {
          "year": 2018,
          "share_class_return": -0.04427,
          "category_return": -0.06269
        },
        {
          "year": 2017,
          "share_class_return": 0.21785,
          "category_return": 0.20438
        },
        {
          "year": 2016,
          "share_class_return": 0.11926,
          "category_return": 0.1036891
        },
        {
          "year": 2015,
          "share_class_return": 0.01362,
          "category_return": -0.01069
        },
        {
          "year": 2014,
          "share_class_return": 0.13642,
          "category_return": 0.1096
        },
        {
          "year": 2013,
          "share_class_return": 0.32333,
          "category_return": 0.315
        },
        {
          "year": 2012,
          "share_class_return": 0.15964,
          "category_return": 0.14961
        },
        {
          "year": 2011,
          "share_class_return": 0.02084,
          "category_return": -0.01271
        },
        {
          "year": 2010,
          "share_class_return": 0.1505,
          "category_return": 0.14006
        },
        {
          "year": 2009,
          "share_class_return": 0.2662,
          "category_return": 0.2817
        },
        {
          "year": 2008,
          "share_class_return": -0.36969,
          "category_return": -0.37791
        },
        {
          "year": 2007,
          "share_class_return": 0.0547,
          "category_return": 0.0616
        },
        {
          "year": 2006,
          "share_class_return": 0.15747,
          "category_return": 0.14167
        },
        {
          "year": 2005,
          "share_class_return": 0.04869,
          "category_return": 0.05877
        },
        {
          "year": 2004,
          "share_class_return": 0.10823,
          "category_return": 0.10024
        },
        {
          "year": 2003,
          "share_class_return": 0.28593,
          "category_return": 0.27046
        },
        {
          "year": 2002,
          "share_class_return": -0.22097,
          "category_return": -0.2225
        },
        {
          "year": 2001,
          "share_class_return": -0.11976,
          "category_return": -0.13502
        }
      ],
      "quarterly_total_returns": [
        {
          "year": 2021,
          "q1": 0.06175,
          "q2": 0.08537,
          "q3": 0.0057,
          "q4": 0.11015
        },
        {
          "year": 2020,
          "q1": -0.19611,
          "q2": 0.20543,
          "q3": 0.08918,
          "q4": 0.12146
        },
        {
          "year": 2019,
          "q1": 0.13645,
          "q2": 0.04298,
          "q3": 0.01691,
          "q4": 0.0906
        },
        {
          "year": 2018,
          "q1": -0.00768,
          "q2": 0.03422,
          "q3": 0.07699,
          "q4": -0.13532
        },
        {
          "year": 2017,
          "q1": 0.06052,
          "q2": 0.03073,
          "q3": 0.04475,
          "q4": 0.06638
        },
        {
          "year": 2016,
          "q1": 0.01337,
          "q2": 0.02445,
          "q3": 0.03844,
          "q4": 0.03821
        },
        {
          "year": 2015,
          "q1": 0.00944,
          "q2": 0.00282,
          "q3": -0.0645,
          "q4": 0.07036
        },
        {
          "year": 2014,
          "q1": 0.01794,
          "q2": 0.05221,
          "q3": 0.01120,
          "q4": 0.04922
        },
        {
          "year": 2013,
          "q1": 0.106,
          "q2": 0.02897,
          "q3": 0.05234,
          "q4": 0.10495
        },
        {
          "year": 2012,
          "q1": 0.12572,
          "q2": -0.02751,
          "q3": 0.0634,
          "q4": -0.00388
        },
        {
          "year": 2011,
          "q1": 0.05901,
          "q2": 0.00098,
          "q3": -0.13878,
          "q4": 0.11819
        },
        {
          "year": 2010,
          "q1": 0.05379,
          "q2": -0.11426,
          "q3": 0.11291,
          "q4": 0.10755
        },
        {
          "year": 2009,
          "q1": -0.10974,
          "q2": 0.15992,
          "q3": 0.15613,
          "q4": 0.06059
        },
        {
          "year": 2008,
          "q1": -0.09452,
          "q2": -0.02733,
          "q3": -0.08339,
          "q4": -0.21921
        },
        {
          "year": 2007,
          "q1": 0.00627,
          "q2": 0.06258,
          "q3": 0.0205,
          "q4": -0.03343
        },
        {
          "year": 2006,
          "q1": 0.04212,
          "q2": -0.01451,
          "q3": 0.05646,
          "q4": 0.06680
        },
        {
          "year": 2005,
          "q1": -0.02143,
          "q2": 0.01354,
          "q3": 0.03590,
          "q4": 0.02068
        },
        {
          "year": 2004,
          "q1": 0.0167,
          "q2": 0.01705,
          "q3": -0.01875,
          "q4": 0.09222
        },
        {
          "year": 2003,
          "q1": -0.03172,
          "q2": 0.15403,
          "q3": 0.02615,
          "q4": 0.12147
        },
        {
          "year": 2002,
          "q1": 0.00249,
          "q2": -0.1342,
          "q3": -0.17203,
          "q4": 0.08403
        },
        {
          "year": 2001,
          "q1": -0.11883,
          "q2": 0.05824,
          "q3": -0.14704,
          "q4": 0.10669
        }
      ],
      "load_adjusted_return": [
        {
          "period": "1_year",
          "return": 0.4076
        },
        {
          "period": "3_year",
          "return": 0.1864
        },
        {
          "period": "5_year",
          "return": 0.1761
        },
        {
          "period": "10_year",
          "return": 0.148
        }
      ]
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/performance

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
trailing_returns.period period of trailing returns
trailing_returns.share_class_return fund returns (%) generated over a given period
trailing_returns.category_return same category average returns (%) generated over a given period
trailing_returns.rank_in_category rank of a fund in category by total returns
annual_total_returns.year year of total returns
annual_total_returns.share_class_return fund total returns (%) generated over a given year
annual_total_returns.category_return same category average total returns (%) generated over a given year
quarterly_total_returns.year year of a fund quarter return
quarterly_total_returns.q1 total return (%) of a fund in the first quarter
quarterly_total_returns.q2 total return (%) of a fund in the second quarter
quarterly_total_returns.q3 total return (%) of a fund in the third quarter
quarterly_total_returns.q4 total return (%) of a fund in the forth quarter
load_adjusted_return.period period of a load adjusted return
load_adjusted_return.return actual return (%) an investor sees after accounting for fees and sales charges are deducted from a mutual fund's performance

JSON request example

https://api.twelvedata.com/mutual_funds/world/performance?symbol=VFIAX&apikey=demo

Risk

This API request returns core metrics to measure the risk of investing in a mutual fund.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/risk?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "risk": {
      "volatility_measures": [
        {
          "period": "3_year",
          "alpha": -0.03,
          "alpha_category": -0.0158,
          "beta": 1,
          "beta_category": 0.01,
          "mean_annual_return": 1.58,
          "mean_annual_return_category": 0.0145,
          "r_squared": 100,
          "r_squared_category": 0.9547,
          "std": 18.52,
          "std_category": 0.19,
          "sharpe_ratio": 0.95,
          "sharpe_ratio_category": 0.0085,
          "treynor_ratio": 17.41,
          "treynor_ratio_category": 0.1559
        },
        {
          "period": "5_year",
          "alpha": -0.03,
          "alpha_category": -0.01289,
          "beta": 1,
          "beta_category": 0.01,
          "mean_annual_return": 1.45,
          "mean_annual_return_category": 0.0135,
          "r_squared": 100,
          "r_squared_category": 0.9492,
          "std": 14.99,
          "std_category": 0.1547,
          "sharpe_ratio": 1.08,
          "sharpe_ratio_category": 0.0098,
          "treynor_ratio": 16.46,
          "treynor_ratio_category": 0.1499
        },
        {
          "period": "10_year",
          "alpha": -0.03,
          "alpha_category": -0.0156,
          "beta": 1,
          "beta_category": 0.0101,
          "mean_annual_return": 1.23,
          "mean_annual_return_category": 0.0112,
          "r_squared": 100,
          "r_squared_category": 0.9489,
          "std": 13.59,
          "std_category": 0.1417,
          "sharpe_ratio": 1.04,
          "sharpe_ratio_category": 0.0091,
          "treynor_ratio": 14.19,
          "treynor_ratio_category": 0.125
        }
      ],
      "valuation_metrics": {
        "price_to_earnings": 26.46,
        "price_to_earnings_category": 26.32,
        "price_to_book": 4.42,
        "price_to_book_category": 4.98,
        "price_to_sales": 2.96,
        "price_to_sales_category": 2.79,
        "price_to_cashflow": 17.57,
        "price_to_cashflow_category": 17.61,
        "median_market_capitalization": 197452,
        "median_market_capitalization_category": 265875,
        "3_year_earnings_growth": 18.72,
        "3_year_earnings_growths_category": 19.53
      }
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/risk

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
volatility_measures.period period of a measure
volatility_measures.alpha alpha score of a fund
volatility_measures.alpha_category average alpha score of a fund's category
volatility_measures.beta beta score of a fund
volatility_measures.beta_category average beta score of a fund's category
volatility_measures.mean_annual mean annual return of a fund
volatility_measures.mean_annual_category average mean annual return of a fund's category
volatility_measures.r_squared r-squared metric of a fund
volatility_measures.r_squared_category average r-squared metric of a fund's category
volatility_measures.std standard deviation of a fund
volatility_measures.std_category average standard deviation of a fund's category
volatility_measures.sharpe_ratio sharpe ratio of a fund
volatility_measures.sharpe_ratio_category average sharpe ratio of a fund's category
volatility_measures.treynor_ratio treynor ratio of a fund
volatility_measures.treynor_ratio_category average treynor ratio of a fund's category
valuation_metrics.price_to_earnings fund price to earnings metric
valuation_metrics.price_to_earnings_category average price to earnings metric of funds in the same category
valuation_metrics.price_to_book fund price to book metric
valuation_metrics.price_to_book_category average price to book metric of funds in the same category
valuation_metrics.price_to_sales fund price to sales metric
valuation_metrics.price_to_sales_category average price to sales metric of funds in the same category
valuation_metrics.price_to_cashflow fund price to cashflow metric
valuation_metrics.price_to_cashflow_category average price to cashflow metric of funds in the same category
valuation_metrics.median_market_capitalization median market capitalization of a fund
valuation_metrics.median_market_capitalization_category median market capitalization of funds in the same category
valuation_metrics.3_year_earnings_growth earnings growth over the last three years
valuation_metrics.3_year_earnings_growth_category earnings growth over the last three years of funds in the same category

JSON request example

https://api.twelvedata.com/mutual_funds/world/risk?symbol=VFIAX&apikey=demo

Ratings

This API request returns ratings of a mutual fund.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/ratings?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "ratings": {
      "performance_rating": 5,
      "risk_rating": 3,
      "return_rating": 4
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/ratings

API credits

1000 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
performance_rating performance rating from 0 to 5
risk_rating risk rating from 0 to 5
return_rating return rating from 0 to 5

JSON request example

https://api.twelvedata.com/mutual_funds/world/ratings?symbol=VFIAX&apikey=demo

CompositionHigh Demand

This API request returns portfolio composition of a mutual fund, including sectors, holding details, weighted exposure, and others.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/composition?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "composition": {
      "major_market_sectors": [
        {
          "sector": "Technology",
          "weight": 0.24239
        },
        {
          "sector": "Financial Services",
          "weight": 0.142
        },
        {
          "sector": "Healthcare",
          "weight": 0.131
        },
        {
          "sector": "Consumer Cyclical",
          "weight": 0.1201
        },
        {
          "sector": "Communication Services",
          "weight": 0.1114
        },
        {
          "sector": "Industrials",
          "weight": 0.08859
        },
        {
          "sector": "Consumer Defensive",
          "weight": 0.06320
        },
        {
          "sector": "Energy",
          "weight": 0.02839
        },
        {
          "sector": "Realestate",
          "weight": 0.02579
        },
        {
          "sector": "Utilities",
          "weight": 0.0243
        },
        {
          "sector": "Basic Materials",
          "weight": 0.0227
        }
      ],
      "asset_allocation": {
        "cash": 0.0004,
        "stocks": 0.9996,
        "preferred_stocks": 0,
        "convertables": 0,
        "bonds": 0,
        "others": 0
      },
      "top_holdings": [
        {
          "symbol": "AAPL",
          "name": "Apple Inc",
          "weight": 0.0592
        },
        {
          "symbol": "MSFT",
          "name": "Microsoft Corp",
          "weight": 0.05619
        },
        {
          "symbol": "AMZN",
          "name": "Amazon.com Inc",
          "weight": 0.04059
        },
        {
          "symbol": "FB",
          "name": "Facebook Inc Class A",
          "weight": 0.0229
        },
        {
          "symbol": "GOOGL",
          "name": "Alphabet Inc Class A",
          "weight": 0.0202
        },
        {
          "symbol": "GOOG",
          "name": "Alphabet Inc Class C",
          "weight": 0.0197
        },
        {
          "symbol": "BRK.B",
          "name": "Berkshire Hathaway Inc Class B",
          "weight": 0.0144
        },
        {
          "symbol": "TSLA",
          "name": "Tesla Inc",
          "weight": 0.0144
        },
        {
          "symbol": "NVDA",
          "name": "NVIDIA Corp",
          "weight": 0.0137
        },
        {
          "symbol": "JPM",
          "name": "JPMorgan Chase & Co",
          "weight": 0.01299
        }
      ],
      "bond_breakdown": {
        "average_maturity": {
          "fund": null,
          "category": null
        },
        "average_duration": {
          "fund": null,
          "category": -1.15
        },
        "credit_quality": [
          {
            "grade": "U.S. Government",
            "weight": 0
          },
          {
            "grade": "AAA",
            "weight": 0
          },
          {
            "grade": "AA",
            "weight": 0
          },
          {
            "grade": "A",
            "weight": 0
          },
          {
            "grade": "BBB",
            "weight": 0
          },
          {
            "grade": "BB",
            "weight": 0
          },
          {
            "grade": "B",
            "weight": 0
          },
          {
            "grade": "Below B",
            "weight": 0
          },
          {
            "grade": "Not Rated",
            "weight": 0
          }
        ]
      }
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/composition

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
major_market_sectors.sector sector category of a fund exposure
major_market_sectors.weight weight (%) of a fund exposure in a sector
asset_allocation.cash percentage of overall portfolio composition in cash
asset_allocation.stocks percentage of overall portfolio composition in stocks
asset_allocation.preferred_stocks percentage of overall portfolio composition in preferred stocks
asset_allocation.convertables percentage of overall portfolio composition in convertable securities
asset_allocation.bonds percentage of overall portfolio composition in bond
asset_allocation.others percentage of overall portfolio composition in other forms of holding
top_holdings.symbol symbol ticker of a holding instrument
top_holdings.name name of a holding instrument
top_holdings.weight weight (%) of a holding instrument in overall portfolio composition
bond_breakdown.average_maturity.fund average maturity of bond holding of a fund
bond_breakdown.average_maturity.category average maturity of bond holding of funds in the same category
bond_breakdown.average_duration.fund average duration of bond holding of a fund
bond_breakdown.average_duration.category average duration of bond holding of funds in the same category
bond_breakdown.credit_quality.grade rating of bond holding of a fund from AAA to below B
bond_breakdown.credit_quality.weight weight of bond holding in fund portfolio

JSON request example

https://api.twelvedata.com/mutual_funds/world/composition?symbol=VFIAX&apikey=demo

Purchase Info

This API request returns essential information on purchasing a mutual fund, including minimums, pricing, and available brokerages.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/purchase_info?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "purchase_info": {
      "expenses": {
        "expense_ratio_gross": 0.0004,
        "expense_ratio_net": 0.0004
      },
      "minimums": {
        "initial_investment": 3000,
        "additional_investment": 1,
        "initial_ira_investment": null,
        "additional_ira_investment": null
      },
      "pricing": {
        "nav": 411.2,
        "12_month_low": 360.14,
        "12_month_high": 442.63,
        "last_month": 404.56
      },
      "brokerages": [
        "ADP Access",
        "ADP Access IPS Z",
        "ADP Access Open Fund Architecture",
        "ADP Access Tier 0",
        "ADP Advisor Access 3(21) Tier 0",
        "ADP Advisor Access Tier 0",
        "Allowab (non-advisory)",
        "Ameriprise Brokerage",
        "Avantax",
        "Bear Stearns",
        "Bear Stearns No-Load Transaction Fee",
        "Cetera Advisor Networks LLC",
        "Cetera Advisor Networks LLC- PAM, PRIME, Premier",
        "Cetera Advisors LLC",
        "Cetera Advisors LLC- PAM, PRIME, Premier",
        "Cetera Financial Specialists LLC- Premier",
        "Comerica Bank",
        "CommonWealth PPS",
        "Commonwealth (PPS Access Program)",
        "Commonwealth (PPS/Advisory)",
        "Commonwealth Universe",
        "DailyAccess Corporation FRIAG",
        "DailyAccess Corporation MATC",
        "DailyAccess Corporation Matrix",
        "DailyAccess Corporation Mid-Atlantic",
        "DailyAccess Corporation RTC",
        "DATALynx",
        "DWS Retirement Sevs Investment Offerings",
        "E TRADE Financial",
        "ETrade No Load Fee",
        "Federated TrustConnect",
        "Fidelity Institutional FundsNetwork",
        "Fidelity Retail FundsNetwork",
        "H Beck Inc.",
        "HD Vest",
        "HD Vest - Vest Advisor",
        "H&R Block Financial Advisors Inc",
        "JPMorgan",
        "JPMorgan INVEST",
        "JP MORGAN LOAD",
        "JP MORGAN NO-LOAD NTF",
        "JP MORGAN NO-LOAD TRANSACTION FEE",
        "Lincoln Investment Planning",
        "LPL SAM Eligible - 6.18.2020",
        "LPL SWM - 6.18.2020",
        "Matrix Financial Solutions",
        "Merrill Lynch",
        "Met Life Resources MFSP Alliance List",
        "Mid Atlantic Capital Corp",
        "Mid Atlantic Capital Group",
        "Mony Securities Corp",
        "Morgan Stanley - Brokerage Accounts",
        "Morgan Stanley Consulting Group Advisor",
        "Morgan Stanley Portfolio Management",
        "MSSB PlanPremier",
        "MSSB PlanPremierTPA",
        "MSWM Brokerage",
        "Nationwide Retirement Clear Adva",
        "Nationwide Retirement Flexible Advantage",
        "Nationwide Retirement Resource",
        "NM WMC",
        "Northwestern Mutual Inv Srvc, LLC",
        "NYLIM 401(k) Complete",
        "Pershing Retirement Plan Network",
        "Principal Advantage",
        "Protected Investors of America",
        "Pruco Securities LLC -PruUMA’s Mutual Funds",
        "Raymond James",
        "Raymond James WRAP Eligible",
        "RBC Wealth Management-Network Eligible",
        "RBC Wealth Management-Wrap Eligible",
        "Robert W. Baird & Co.",
        "Schwab All (Retail, Instl, Retirement)",
        "Schwab Existing Shareholders Only",
        "Schwab Institutional",
        "Schwab Institutional Only",
        "Schwab Retail",
        "Scottrade Load",
        "Scottrade NTF",
        "Scottrade TF",
        "Securities America Advisors",
        "Securities America Inc.",
        "Sterne, Agee & Leach, Inc.,",
        "SunGard Transaction Network",
        "Td Ameritrade, Inc.",
        "TD Ameritrade Institutional",
        "TD Ameritrade Institutional NTF",
        "TD Ameritrade Retail",
        "TD Ameritrade Retail NTF",
        "TD Ameritrade Trust Company",
        "Thrivent   Advisory Eligible",
        "Thrivent   Retail Eligible",
        "Trade PMR NTF",
        "Trade PMR Transaction Fee",
        "TradeStation Securities",
        "TRUSTlynx",
        "Vanguard Load",
        "Vanguard NTF",
        "Vanguard TF",
        "Waddell & Reed Choice MAP Flex",
        "WFA Fdntl Choice/PIM Updated 6.1.21",
        "WFA MF Advisory Updated 6.1.21",
        "WR Hambrecht Co LLC"
      ]
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/purchase_info

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
expenses.expense_ratio_gross annual cost of investing in a mutual fund
expenses.expense_ratio_net percentage of mutual fund assets steered toward a fund's operating expenses and fund management fees
minimums.initial_investment investment minimum
minimums.additional_investment minimum amount of additional investment
minimums.initial_ira_investment investment minimum for IRA
minimums.additional_ira_investment minimum amount of additional investment for IRA
pricing.nav last price of the fund
pricing.12_month_low lowest price of the fund over the last year
pricing.12_month_high highest price of the fund over the last year
pricing.last_month fund price at the end of the last month
brokerages list of brokerages where mutual fund can be purchased

JSON request example

https://api.twelvedata.com/mutual_funds/world/purchase_info?symbol=VFIAX&apikey=demo

Sustainability

This API request returns brief information on mutual fund sustainability and ESG.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/sustainability?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "sustainability": {
      "score": 22,
      "corporate_esg_pillars": {
        "environmental": 3.73,
        "social": 10.44,
        "governance": 7.86
      },
      "sustainable_investment": false,
      "corporate_aum": 0.99486
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/sustainability

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
sustainability.score asset-weighted average of normalized company-level ESG Scores for the covered holdings in the portfolio from 0 to 100
corporate_esg_pillars.environmental ESG environmental score
corporate_esg_pillars.social ESG social score
corporate_esg_pillars.governance ESG governance score
sustainable_investment indication that the fund discloses in their prospectus that they employ socially responsible or ESG principles in their investment selection processes
corporate_aum percentage of AUM used to calculate sustainability score

JSON request example

https://api.twelvedata.com/mutual_funds/world/sustainability?symbol=VFIAX&apikey=demo

Fundamentals

Fundamental data covers a broad range of datasets for US-based and international stock, ETFs, and mutual funds. Including, but not limited to financials, profiles, transactions, and more.

Returns a logo of company, cryptocurrency, or forex pair.

HTTP request example

https://api.twelvedata.com/logo?symbol=AAPL&apikey=your_api_key

https://api.twelvedata.com/logo?symbol=BTC/USD&apikey=your_api_key

https://api.twelvedata.com/logo?symbol=EUR/USD&apikey=your_api_key

This request will return JSON with the following structure

// Equity
{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "url": "https://api.twelvedata.com/logo/apple.com"
}

// Crypto
{
  "meta": {
    "symbol": "BTC/USD",
  },
  "logo_base": "https://logo.twelvedata.com/crypto/btc.png",
  "logo_quote": "https://logo.twelvedata.com/crypto/usd.png"
}

// Forex
{
  "meta": {
    "symbol": "EUR/USD"
  },
  "logo_base": "https://logo.twelvedata.com/forex/eur.png",
  "logo_quote": "https://logo.twelvedata.com/forex/usd.png"
}

HTTP route

/logo

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Type Description
url string link to download the logo

JSON request example

https://api.twelvedata.com/logo?symbol=AAPL&apikey=demo

https://api.twelvedata.com/logo?symbol=BTC/USD&apikey=demo

https://api.twelvedata.com/logo?symbol=EUR/USD&apikey=demo

ProfileUseful

Returns general information about the company.

HTTP request example

https://api.twelvedata.com/profile?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "symbol": "AAPL",
  "name": "Apple Inc",
  "exchange": "NASDAQ",
  "mic_code": "XNAS",
  "sector": "Technology",
  "industry": "Consumer Electronics",
  "employees": 147000,
  "website": "http://www.apple.com",
  "description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide. It also sells various related services. The company offers iPhone, a line of smartphones; Mac, a line of personal computers; iPad, a line of multi-purpose tablets; and wearables, home, and accessories comprising AirPods, Apple TV, Apple Watch, Beats products, HomePod, iPod touch, and other Apple-branded and third-party accessories. It also provides AppleCare support services; cloud services store services; and operates various platforms, including the App Store, that allow customers to discover and download applications and digital content, such as books, music, video, games, and podcasts. In addition, the company offers various services, such as Apple Arcade, a game subscription service; Apple Music, which offers users a curated listening experience with on-demand radio stations; Apple News+, a subscription news and magazine service; Apple TV+, which offers exclusive original content; Apple Card, a co-branded credit card; and Apple Pay, a cashless payment service, as well as licenses its intellectual property. The company serves consumers, and small and mid-sized businesses; and the education, enterprise, and government markets. It sells and delivers third-party applications for its products through the App Store. The company also sells its products through its retail and online stores, and direct sales force; and third-party cellular network carriers, wholesalers, retailers, and resellers. Apple Inc. was founded in 1977 and is headquartered in Cupertino, California.",
  "type": "Common Stock",
  "CEO": "Mr. Timothy D. Cook",
  "address": "One Apple Park Way",
  "city": "Cupertino",
  "zip": "95014",
  "state": "CA",
  "country": "US",
  "phone": "408-996-1010"
}

HTTP route

/profile

API credits

10 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Type Description
symbol string Ticker of the company
name string Name of the company
exchange string Exchange name where the company is listed
mic_code string Market Identifier Code (MIC) under ISO 10383 standard
sector string Sector at which the company operates
industry string Industry at which company operates
employees number Number of employees in the company
website string Website of the company
description string Description of the company activities
type string Issue type of the stock
CEO string Name of the CEO of the company
address string Street address of the company if presented
city string City of the company if presented
zip string ZIP code of the company if presented
state string State of the company if presented
country string Country of the company if presented
phone string Phone number of the company if presented

JSON request example

https://api.twelvedata.com/profile?symbol=AAPL&apikey=demo

Dividends

Returns the amount of dividends paid out for the last 10+ years.

HTTP request example

https://api.twelvedata.com/dividends?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "dividends": [
    {
      "payment_date": "2021-08-06",
      "amount": 0.22
    }
  ]
}

HTTP route

/dividends

API credits

20 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
range string • Parameter is optional
last - the last dividend - default
1m - one month
3m - three months
6m - six months
ytd - year-to-date
1y - one year
2y - two years
5y - 5 years
full - complete history
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Type Description
payment_date string Stands for the payment date
amount number Stands for the payment amount

JSON request example

https://api.twelvedata.com/dividends?symbol=AAPL&apikey=demo

Splits

Returns the date and the split factor of shares of the company for the last 10+ years.

HTTP request example

https://api.twelvedata.com/splits?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "splits": [
    {
      "date": "2020-08-31",
      "description": "4-for-1 split",
      "ratio": 0.25,
      "from_factor": 4,
      "to_factor": 1
    }
  ]
}

HTTP route

/splits

API credits

20 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
range string • Parameter is optional
last - the last split - default
1m - one month
3m - three months
6m - six months
ytd - year-to-date
1y - one year
2y - two years
5y - 5 years
full - complete history
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Type Description
date string Stands for the split date
description string Specification of the split event
ratio number The ratio by which the number of a company's outstanding shares of stock are increased following a stock split. For example, a 4-for-1 split results in four times as many outstanding shares, with each share selling at one forth of its pre-split price
from_factor number To factor of the split
to_factor number From factor of the split

JSON request example

https://api.twelvedata.com/splits?symbol=AAPL&apikey=demo

Earnings

This API call returns earnings data for a given company, including EPS estimate and EPS actual. Earnings are available for complete company history.

HTTP request example

https://api.twelvedata.com/earnings?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "earnings":[
    {
       "date": "2020-04-30",
       "time": "After Hours",
       "eps_estimate": 2.09,
       "eps_actual": 2.55,
       "difference": 0.46,
       "surprise_prc": 22.01
    },
    {
       "date": "2020-01-28",
       "time": "After Hours",
       "eps_estimate": 4.54,
       "eps_actual": 4.99,
       "difference": 0.45,
       "surprise_prc": 9.91
    },
    {
       "date": "2019-10-30",
       "time": "After Hours",
       "eps_estimate": 2.84,
       "eps_actual": 3.03,
       "difference": 0.19,
       "surprise_prc": 6.69
    },
    {
       "date": "2010-07-30",
       "time": "After Hours",
       "eps_estimate": 2.10,
       "eps_actual": 2.18,
       "difference": 0.08,
       "surprise_prc": 3.81
    },
    {
       "date": "2019-04-30",
       "time": "After Hours",
       "eps_estimate": 2.37,
       "eps_actual": 2.46,
       "difference": 0.09,
       "surprise_prc": 3.8
    },
    {...}
  ],
  "status":"ok"
}

HTTP route

/earnings

API credits

20 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
period string • Parameter is optional
• Type of earning, returns only 1 record
• When is not empty, dates and outputsize parameters are ignored
• Accepts: latest and next
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 1000
• Default 10 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Description
date date of earning release
time can be either of the following values: Pre Market, After Hours, Time Not Supplied, Transfer Agent
eps_estimate analyst estimate of the future company earning
eps_actual actual value of reported earning
difference delta between eps_actual and eps_estimate
surprise_prc surprise in the percentage of the eps_actual related to eps_estimate

JSON request example

https://api.twelvedata.com/earnings?symbol=AAPL&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/earnings?symbol=AAPL&apikey=demo&format=CSV

Earnings Calendar

This API method returns earning data as a calendar for a given date range. By default today’s earning is returned. To call custom period, use start_date and end_date parameters.

HTTP request example

https://api.twelvedata.com/earnings_calendar?apikey=your_api_key

This request will return JSON with the following structure

{
    "earnings":{
        "2020-05-08":[
            {...},
            {
                "symbol": "BR",
                "name": "Broadridge Financial Solutions Inc",
                "currency": "USD",
                "exchange": "NYSE",
                "mic_code": "XNYS",
                "country": "United States",
                "time": "Time Not Supplied",
                "eps_estimate": 1.72,
                "eps_actual": 1.67,
                "difference": -0.05,
                "surprise_prc": -2.9
            },
            {
                "symbol": "LPL",
                "name": "LG Display Co Ltd",
                "currency": "USD",
                "exchange": "NYSE",
                "mic_code": "XNYS",
                "country": "United States",
                "time": "Time Not Supplied",
                "eps_estimate": -0.45,
                "eps_actual": -0.23,
                "difference": 0.22,
                "surprise_prc": 48.22
            },
            {...}
        ],
        "2020-05-07":[
            {...},
            {
                "symbol": "AAON",
                "name": "AAON Inc",
                "currency": "USD",
                "exchange": "NASDAQ",
                "mic_code": "XNAS",
                "country": "United States",
                "time": "Time Not Supplied",
                "eps_estimate": 0.35,
                "eps_actual": 0.41,
                "difference": 0.06,
                "surprise_prc": 17.14
            },
            {
                "symbol": "JOBS",
                "name": "51job Inc",
                "currency": "USD",
                "exchange": "NASDAQ",
                "mic_code": "XNAS",
                "country": "United States",
                "time": "Time Not Supplied",
                "eps_estimate": 2.44,
                "eps_actual": 3.27,
                "difference": 0.83,
                "surprise_prc": 34.02
            },
            {...}
        ],
        {...}
    },
    "status":"ok"
}

HTTP route

/earnings_calendar

API credits

40 per request

API parameters

Key Type Description
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Description
symbol instrument symbol (ticker)
name full name of instrument
currency currency in which instrument is traded by ISO 4217 standard
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
country country where exchange is located
time can be either of the following values: Pre Market, After Hours, Time Not Supplied, Transfer Agent
eps_estimate analyst estimate of the future company earning
eps_actual actual value of reported earning
difference delta between eps_actual and eps_estimate
surprise_prc surprise in percentage of the eps_actual related to eps_estimate

JSON request example

https://api.twelvedata.com/earnings_calendar?apikey=demo

Downloadable CSV example

https://api.twelvedata.com/earnings_calendar?apikey=demo&format=CSV

IPO Calendar

This endpoint returns past, today, or upcoming IPOs.

HTTP request example

https://api.twelvedata.com/ipo_calendar?apikey=your_api_key

This request will return JSON with the following structure

{
  "2021-09-03": [
    {
      "symbol": "DWACU",
      "name": "Digital World Acquisition Corp.",
      "exchange": "NASDAQ",
      "mic_code": "XNAS",
      "price_range_low": 10,
      "price_range_high": 10,
      "offer_price": null,
      "currency": "USD",
      "shares": null
    },
    {
      "symbol": "9869",
      "name": "Helens Intl Hldg Co Ltd",
      "exchange": "HKEX",
      "mic_code": "XHKG",
      "price_range_low": null,
      "price_range_high": null,
      "offer_price": null,
      "currency": "HKD",
      "shares": null
    },
    {
      "symbol": "BMR",
      "name": "Ballymore Resources Ltd",
      "exchange": "ASX",
      "mic_code": "XASX",
      "price_range_low": 0.1548,
      "price_range_high": 0.1548,
      "offer_price": 0.2,
      "currency": "AUD",
      "shares": null
    }
  ]
}

HTTP route

/ipo_calendar

API credits

40 per request

API parameters

Key Type Description
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Type Description
symbol string Ticker of the company
name string Name of the company
exchange string Exchange name where the company is listed
mic_code string Market Identifier Code (MIC) under ISO 10383 standard
price_range_low number The lower bound of stock price range if available
price_range_high number The upper bound of stock price range if available
offer_price number Initial offer price if available
currency string Currency of the stock
shares number Number of shares, if available

JSON request example

https://api.twelvedata.com/ipo_calendar?apikey=your_api_key

StatisticsHigh Demand

Returns current overview of company’s main statistics including valuation metrics and financials.

HTTP request example

https://api.twelvedata.com/statistics?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "statistics": {
    "valuations_metrics": {
      "market_capitalization": 2546807865344,
      "enterprise_value": 2620597731328,
      "trailing_pe": 30.162493,
      "forward_pe": 26.982489,
      "peg_ratio": 1.4,
      "price_to_sales_ttm": 7.336227,
      "price_to_book_mrq": 39.68831,
      "enterprise_to_revenue": 7.549,
      "enterprise_to_ebitda": 23.623
    },
    "financials": {
      "fiscal_year_ends": "2020-09-26",
      "most_recent_quarter": "2021-06-26",
      "profit_margin": 0.25004,
      "operating_margin": 0.28788,
      "return_on_assets_ttm": 0.19302,
      "return_on_equity_ttm": 1.27125,
      "income_statement": {
        "revenue_ttm": 347155005440,
        "revenue_per_share_ttm": 20.61,
        "quarterly_revenue_growth": 0.364,
        "gross_profit_ttm": 104956000000,
        "ebitda": 110934999040,
        "net_income_to_common_ttm": 86801997824,
        "diluted_eps_ttm": 5.108,
        "quarterly_earnings_growth_yoy": 0.932
      },
      "balance_sheet": {
        "revenue_ttm": 347155005440,
        "total_cash_mrq": 61696000000,
        "total_cash_per_share_mrq": 3.732,
        "total_debt_mrq": 135491002368,
        "total_debt_to_equity_mrq": 210.782,
        "current_ratio_mrq": 1.062,
        "book_value_per_share_mrq": 3.882
      },
      "cash_flow": {
        "operating_cash_flow_ttm": 104414003200,
        "levered_free_cash_flow_ttm": 80625876992
      }
    },
    "stock_statistics": {
      "shares_outstanding": 16530199552,
      "float_shares": 16513305231,
      "avg_10_volume": 72804757,
      "avg_30_volume": 77013078,
      "shares_short": 93105968,
      "short_ratio": 1.19,
      "short_percent_of_shares_outstanding": 0.0056,
      "percent_held_by_insiders": 0.00071000005,
      "percent_held_by_institutions": 0.58474
    },
    "stock_price_summary": {
      "fifty_two_week_low": 103.1,
      "fifty_two_week_high": 157.26,
      "fifty_two_week_change": 0.375625,
      "beta": 1.201965,
      "day_50_ma": 148.96686,
      "day_200_ma": 134.42506
    },
    "dividends_and_splits": {
      "forward_annual_dividend_rate": 0.88,
      "forward_annual_dividend_yield": 0.0057,
      "trailing_annual_dividend_rate": 0.835,
      "trailing_annual_dividend_yield": 0.0053832764,
      "5_year_average_dividend_yield": 1.27,
      "payout_ratio": 0.16309999,
      "dividend_date": "2021-08-12",
      "ex_dividend_date": "2021-08-06",
      "last_split_factor": "4-for-1 split",
      "last_split_date": "2020-08-31"
    }
  }
}

HTTP route

/statistics

API credits

50 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
name string Name of the company
market_capitalization number Refers to the market value of the company's outstanding shares
enterprise_value number Refers to enterprise value (EV) of the company, often used as a more comprehensive alternative to market capitalization
trailing_pe number Refers to the trailing price-to-earnings (P/E). It is calculated by taking the current stock price and dividing it by the trailing earnings per share (EPS) for the past 12 months
forward_pe number Refers to the forward price-to-earnings ratio. It is calculated by dividing the current share price by the estimated future earnings per share
peg_ratio number The price/earnings to growth (PEG) ratio is a price-to-earnings ratio divided by the growth rate of the earnings
price_to_sales_ttm number The price-to-sales (P/S) ratio is a valuation ratio that compares the market capitalization to its revenues over the last 12 months
price_to_book_mrq number The price-to-book (P/B) ratio is equal to the current share price divided by the book value of all shares (BVPS) over the last quarter
enterprise_to_revenue number The enterprise value-to-revenue multiple (EV/R) is a measure that compares enterprise value to revenue
enterprise_to_ebitda number The enterprise value-to-ebitda multiple (EV/EBITDA) is a measure that compares enterprise value to EBITDA
fiscal_year_ends string Refers to the completion of the last 12-month accounting period
most_recent_quarter string The most recent quarter (MRQ) refers to the fiscal quarter that most recently ended
profit_margin number Refers to gross profit margin. Calculated by dividing net income by sales revenue
operating_margin number Operating margin is calculated by dividing operating income by net sales
return_on_assets_ttm number Return on assets (ROA) is calculated by dividing net income by total assets
return_on_equity_ttm number Return on equity (ROE) is calculated by dividing net income by average shareholders' equity
revenue_ttm number Refers to total revenue over the last 12 months
revenue_per_share_ttm number Refers to revenue per share over the last 12 months
quarterly_revenue_growth number Refers to quarterly revenue growth year over year
gross_profit_ttm number Refers to gross profit over the last 12 months
ebitda number Refers to EBITDA (earnings before interest, taxes, depreciation, and amortization) measure; EBITDA is not calculated for banks.
net_income_to_common_ttm number Refers to net income applicable to common shares over the last 12 months
diluted_eps_ttm number Refers to diluted EPS measure over the last 12 months
quarterly_earnings_growth_yoy number Refers to quarterly earnings growth year over year
total_cash_mrq number Refers to total cash measure for the most recent quarter
total_cash_per_share_mrq number Refers to total cash per share measure for the most recent quarter
total_debt_mrq number Refers to total debt measure for the most recent quarter
total_debt_to_equity_mrq number Refers to total debt to equity measure for the most recent quarter
current_ratio_mrq number Refers to current ratio (total assets / total liabilities) ratio for the most recent quarter
book_value_per_share_mrq number Refers to book value per share (BVPS) ratio for the most recent quarter
operating_cash_flow_ttm number Refers to operating cash flow measure over the last 12 months
levered_free_cash_flow_ttm number Refers to levered free cash flow measure over the last 12 months
shares_outstanding number Refers for the shares outstanding currently held by all its shareholders
float_shares number Refers to floating stock is the number of public shares a company has available for trading on the open market
avg_10_volume number Refers to the average 10 days volume
avg_30_volume number Refers to the average 30 days volume
shares_short number Refers to the number of shares that have been shorted
short_ratio number Refers to short ratio measure
short_percent_of_shares_outstanding number Refers to the number of shorted shares divided by the number of shares outstanding
percent_held_by_insiders number Refers to the percentage of shares held by the company insiders
percent_held_by_institutions number Refers to the percentage of shares held by the institutions
fifty_two_week_low number Refers to the lowest price at which stock traded during a year
fifty_two_week_high number Refers to the highest price at which stock traded during a year
fifty_two_week_change number Refers to the change between lowest and highest prices during a year
beta number Refers to beta measure relative to the primary benchmark (index) of the country
day_50_ma number Refers to the 50-day simple moving average
day_200_ma number Refers to the 200-day simple moving average
forward_annual_dividend_rate number Refers to the forward dividend yield estimation in the currency of instrument
forward_annual_dividend_yield number Refers to the forward dividend yield percentage relative to stock price
trailing_annual_dividend_rate number Refers to the trailing dividend yield rate in the currency of instrument over the last 12 months
trailing_annual_dividend_yield number Refers to the trailing dividend yield percentage relative to stock price
5_year_average_dividend_yield number Refers to the average 5 years dividend yield
payout_ratio number Refers to payout ratio, showing the proportion of earnings a company pays its shareholders in the form of dividends
dividend_date number Refers to the last dividend payout date
ex_dividend_date number Refers to the last ex-dividend payout date
last_split_factor number Specification of the last split event
last_split_date number Refers for the last split date

JSON request example

https://api.twelvedata.com/statistics?symbol=AAPL&apikey=demo

Insider Transactions

Returns trading information performed by insiders.

HTTP request example

https://api.twelvedata.com/insider_transactions?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "insider_transactions": [
    {
      "full_name": "ADAMS KATHERINE L",
      "position": "General Counsel",
      "date_reported": "2021-05-03",
      "is_direct": true,
      "shares": 17000,
      "value": 2257631,
      "description": "Sale at price 132.57 - 133.93 per share."
    },
    {
      "full_name": "MAESTRI LUCA",
      "position": "Chief Financial Officer",
      "date_reported": "2021-05-03",
      "is_direct": true,
      "shares": 121072,
      "value": 16079338,
      "description": "Sale at price 132.58 - 133.93 per share."
    },
    {
      "full_name": "O'BRIEN DEIRDRE",
      "position": "Officer",
      "date_reported": "2021-04-16",
      "is_direct": true,
      "shares": 18216,
      "value": 2441126,
      "description": "Sale at price 134.01 per share."
    },
    {
      "full_name": "KONDO CHRISTOPHER",
      "position": "Officer",
      "date_reported": "2021-04-15",
      "is_direct": true,
      "shares": 17603,
      "value": 0,
      "description": ""
    }
  ]
}

HTTP route

/insider_transactions

API credits

200 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
full_name string Full name of an individual, including first name, middle name, last name, and suffix
position string Job position of insider
date_reported string Date the transaction was reported
is_direct bool true if direct, false if indirect
shares number As per report the number of shares acquired or disposed of the transaction
value number Represents the value of transaction, calculated as price multiplied by the volume
description string Exact price or price range of the transaction if available

JSON request example

https://api.twelvedata.com/insider_transactions?symbol=AAPL&apikey=demo

Income StatementHigh Demand

Returns complete income statement of a company and shows the company’s revenues and expenses during a period (annual or quarter).

HTTP request example

https://api.twelvedata.com/income_statement?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York",
    "period": "Quarterly"
  },
  "income_statement": [
    {
      "fiscal_date": "2021-12-31",
      "quarter": 1,
      "sales": 123945000000,
      "cost_of_goods": 69702000000,
      "gross_profit": 54243000000,
      "operating_expense": {
        "research_and_development": 6306000000,
        "selling_general_and_administrative": 6449000000,
        "other_operating_expenses": null
      },
      "operating_income": 41488000000,
      "non_operating_interest": {
        "income": 650000000,
        "expense": 694000000
      },
      "other_income_expense": -203000000,
      "pretax_income": 41241000000,
      "income_tax": 6611000000,
      "net_income": 34630000000,
      "eps_basic": 2.11,
      "eps_diluted": 2.1,
      "basic_shares_outstanding": 16391724000,
      "diluted_shares_outstanding": 16391724000,
      "ebitda": 44632000000,
      "net_income_continuous_operations": null,
      "minority_interests": null,
      "preferred_stock_dividends": null
    }
  ]
}

HTTP route

/income_statement

API credits

100 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
period string • Parameter is optional
• Values should be annual or quarterly
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
fiscal_date string Date of the income statement release
quarter string Fiscal quarter. Visible when &period=quarterly
sales number Refers to total reported revenue
cost_of_goods number Refers to cost of revenue
gross_profit number Refers to net gross profit: sales - cost_of_goods
research_and_development number Refers to research & development (R&D) expenses
selling_general_and_administrative number Refers to selling, general and administrative (SG&A) expenses
other_operating_expenses number Refers to other operating expenses
operating_income number Refers to net operating income: gross_profit - research_and_development - selling_general_and_administrative
income number Refers to non-operating interest income
expense number Refers to non-operating interest expense
other_income_expense number Refers to other incomes or expenses
pretax_income number Refers to earnings before tax: operating_income + net_non_operating_interest - other_income_expense
income_tax number Refers to a tax provision
net_income number Refers to net income: pretax_income - income_tax
eps_basic number Refers to earnings per share (EPS)
eps_diluted number Refers to diluted earnings per share (EPS)
basic_shares_outstanding number Refers for the shares outstanding held by all its shareholders
diluted_shares_outstanding number Refers to the total number of shares a company would have if all dilutive securities were exercised and converted into shares
ebitda number Refers to EBITDA (earnings before interest, taxes, depreciation, and amortization) measure
net_income_continuous_operations number Refers to the after-tax earnings that a business has generated from its operational activities
minority_interests number Refers to amount of minority interests paid out
preferred_stock_dividends number Refers to dividend that is allocated to and paid on a company's preferred shares

JSON request example

https://api.twelvedata.com/income_statement?symbol=AAPL&apikey=demo

Balance SheetHigh Demand

Returns complete balance sheet of a company showing the summary of assets, liabilities, and shareholders’ equity.

HTTP request example

https://api.twelvedata.com/balance_sheet?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York",
    "period": "Quarterly"
  },
  "balance_sheet": [
    {
      "fiscal_date": "2021-09-30",
      "assets": {
        "current_assets": {
          "cash": 17305000000,
          "cash_equivalents": 17635000000,
          "cash_and_cash_equivalents": 34940000000,
          "other_short_term_investments": 27699000000,
          "accounts_receivable": 26278000000,
          "other_receivables": 25228000000,
          "inventory": 6580000000,
          "prepaid_assets": null,
          "restricted_cash": null,
          "assets_held_for_sale": null,
          "hedging_assets": null,
          "other_current_assets": 14111000000,
          "total_current_assets": 134836000000
        },
        "non_current_assets": {
          "properties": 0,
          "land_and_improvements": 20041000000,
          "machinery_furniture_equipment": 78659000000,
          "construction_in_progress": null,
          "leases": 11023000000,
          "accumulated_depreciation": -70283000000,
          "goodwill": null,
          "investment_properties": null,
          "financial_assets": null,
          "intangible_assets": null,
          "investments_and_advances": 127877000000,
          "other_non_current_assets": 48849000000,
          "total_non_current_assets": 216166000000
        },
        "total_assets": 351002000000
      },
      "liabilities": {
        "current_liabilities": {
          "accounts_payable": 54763000000,
          "accrued_expenses": null,
          "short_term_debt": 15613000000,
          "deferred_revenue": 7612000000,
          "tax_payable": null,
          "pensions": null,
          "other_current_liabilities": 47493000000,
          "total_current_liabilities": 125481000000
        },
        "non_current_liabilities": {
          "long_term_provisions": null,
          "long_term_debt": 109106000000,
          "provision_for_risks_and_charges": 24689000000,
          "deferred_liabilities": null,
          "derivative_product_liabilities": null,
          "other_non_current_liabilities": 28636000000,
          "total_non_current_liabilities": 162431000000
        },
        "total_liabilities": 287912000000
      },
      "shareholders_equity": {
        "common_stock": 57365000000,
        "retained_earnings": 5562000000,
        "other_shareholders_equity": 163000000,
        "total_shareholders_equity": 63090000000,
        "additional_paid_in_capital": null,
        "treasury_stock": null,
        "minority_interest": null
      }
    }
  ]
}

HTTP route

/balance_sheet

API credits

100 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
period string • Parameter is optional
• Values should be annual or quarterly
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
fiscal_date string Date of the balance sheet release
quarter string Fiscal quarter. Visible when &period=quarterly
cash number Cash includes currency, bank accounts, and undeposited checks
cash_equivalents number Represents cash equivalents that have high credit quality and are highly liquid
cash_and_cash_equivalents number Combined value of cash and cash equivalents when company doesn't report a breakdown
other_short_term_investments number Represents other short term investments
accounts_receivable number Represents the balance of money due to a firm for goods or services delivered or used but not yet paid for by customers
other_receivables number Represents other receivables
inventory number Represents the goods available for sale and raw materials used to produce goods available for sale
prepaid_assets number Represents expense that has already been paid for, but which has not yet been consumed
restricted_cash number Represents money that is held for a specific purpose and thus not available to the company for immediate or general business use
assets_held_for_sale number Represents assets which company plans to sell
hedging_assets number Represents money that is spent on hedging assets
other_current_assets number Represents other current assets
total_current_assets number All current assets values in a total
properties number Represents property owned
land_and_improvements number Represents land and improvements owned
machinery_furniture_equipment number Represents office equipment, furniture, and vehicles owned
construction_in_progress number Represents the cost of construction work, which is not yet completed
leases number Represents operating and financial leases
accumulated_depreciation number Represents the cumulative depreciation of an asset that has been recorded
goodwill number Represents the value of a brand name, solid customer base, good customer relations, good employee relations, and proprietary technology
investment_properties number Represents real estate property purchased with the intention of earning a return on the investment
financial_assets number Represents liquid asset that gets its value from a contractual right or ownership claim
intangible_assets number Represents the patents, trademarks, and other intellectual properties
investments_and_advances number Represents available for sale financial securities
other_non_current_assets number Represents other long-term assets
total_non_current_assets number All long-term assets values in total
total_assets number The sum of total_current_assets + total_non_current_assets
accounts_payable number Refers to an account within the general ledger that represents an obligation to pay off a short-term debt to creditors or suppliers
accrued_expenses number Represents payments that a company is obligated to pay in the future for which goods and services have already been delivered
short_term_debt number Represents current debt and capital lease obligations
deferred_revenue number Represents advance payments a company receives for products or services that are to be delivered or performed in the future
tax_payable number Represents taxes due to the government within one year
pensions number Represents to pensions to be paid out
other_current_liabilities number Represents other current liabilities
total_current_liabilities number Represents total current assets
long_term_provisions number Represents money set aside for employee benefits such as gratuity
long_term_debt number Represents amount of outstanding debt that has a maturity of 12 months or longer
provision_for_risks_and_charges number Represents funds set aside as assets to pay for anticipated future losses
deferred_liabilities number Represents revenue producing activity for which revenue has not yet been recognized, and is not expected to be recognized in the next 12 months
derivative_product_liabilities number
other_non_current_liabilities number Represents other non-current liabilities
total_non_current_liabilities number Represents total non-current liabilities
total_liabilities number The sum of total_current_liabilities + total_non_current_liabilities
common_stock number Represents net worth of investors shares, which is equal to the total_assets - total_liabilities
retained_earnings number Refers to the profits earned minus dividends paid
other_shareholders_equity number Represents other not affecting retained earnings gains and looses
total_shareholders_equity number Represents the net worth of a company, which is the amount that would be returned to shareholders if a company's total assets were liquidated, and all of its debts were repaid

JSON request example

https://api.twelvedata.com/balance_sheet?symbol=AAPL&apikey=demo

Cash FlowHigh Demand

Returns complete cash flow of a company showing the net amount of cash and cash equivalents being transferred into and out of business.

HTTP request example

https://api.twelvedata.com/cash_flow?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York",
    "period": "Quarterly"
  },
  "cash_flow": [
    {
      "fiscal_date": "2021-12-31",
      "quarter": 1,
      "operating_activities": {
        "net_income": 34630000000,
        "depreciation": 2697000000,
        "deferred_taxes": 682000000,
        "stock_based_compensation": 2265000000,
        "other_non_cash_items": 167000000,
        "accounts_receivable": -13746000000,
        "accounts_payable": 19813000000,
        "other_assets_liabilities": 458000000,
        "operating_cash_flow": 46966000000
      },
      "investing_activities": {
        "capital_expenditures": -2803000000,
        "net_intangibles": null,
        "net_acquisitions": null,
        "purchase_of_investments": -34913000000,
        "sale_of_investments": 21984000000,
        "other_investing_activity": -374000000,
        "investing_cash_flow": -16106000000
      },
      "financing_activities": {
        "long_term_debt_issuance": null,
        "long_term_debt_payments": 0,
        "short_term_debt_issuance": -1000000000,
        "common_stock_issuance": null,
        "common_stock_repurchase": -20478000000,
        "common_dividends": -3732000000,
        "other_financing_charges": -2949000000,
        "financing_cash_flow": -28159000000
      },
      "end_cash_position": 38630000000,
      "income_tax_paid": 5235000000,
      "interest_paid": 531000000,
      "free_cash_flow": 49769000000
    }
  ]
}

HTTP route

/cash_flow

API credits

100 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
period string • Parameter is optional
• Values should be annual or quarterly
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
fiscal_date string Date of the cash flow release
quarter string Fiscal quarter. Visible when &period=quarterly
net_income number Returns net income (NI). Calculated as sales minus cost of goods sold
depreciation number Represents depreciation and amortization measure
deferred_taxes number Stands for taxes that are owed but are not due to be paid until a future date
stock_based_compensation number Refers to share-based compensation as the way of paying employees, executives, and directors of a company with equity in the business
other_non_cash_items number Represents other non-cash items
accounts_receivable number Represents the balance of money due to a firm for goods or services delivered or used but not yet paid for by customers
accounts_payable number Refers to an account within the general ledger that represents an obligation to pay off a short-term debt to creditors or suppliers
other_assets_liabilities number Represents cumulative changes in inventory, other current assets, other current liabilities, and other working capital
operating_cash_flow number Returns operating cash flow (OCF) measure representing a total amount of cash generated by company's normal business operations
capital_expenditures number Capital expenditures (CapEx) are funds used by a company to acquire, upgrade, and maintain physical assets (PPE)
net_intangibles number Represents purchase of a not physical asset
net_acquisitions number Refers to net amount of business purchase and sale
purchase_of_investments number Represents how much money has been used in making investments, including purchases of physical assets, investments in securities
sale_of_investments number Represents how much money has been generated from the sale of securities or assets
other_investing_activity number Represents other investing activity
investing_cash_flow number Returns total amount of cash flow used in investments
long_term_debt_issuance number Refers to the issuance of any financial obligations that extend beyond a 12 months period
long_term_debt_payments number Refers to the payments of any financial obligations that extend beyond a 12 months period
short_term_debt_issuance number Refers to the issuance of any financial obligations that are expected to be paid off within a year
common_stock_issuance number Represents a transaction whereby a company issues its own shares to the marketplace
common_stock_repurchase number Represents a transaction whereby a company buys back its own shares from the marketplace
common_dividends number Returns value of payment doled out by a company to its stockholders in the form of periodic distributions of cash
other_financing_charges number Represents other financing charges
financing_cash_flow number Returns cash flow from financing activities (CFF), which shows the net flows of cash that are used to fund the company
end_cash_position number Returns the amount of cash a company has when adding the change in cash and beginning cash balance for the current fiscal period
income_tax_paid number Refers to supplemental data about income tax paid
interest_paid number Refers to supplemental data about interest paid
free_cash_flow number Represents the cash a company generates after accounting for cash outflows to support operations and maintain its capital assets

JSON request example

https://api.twelvedata.com/cash_flow?symbol=AAPL&apikey=demo

Options Expiration

Return the expiration dates of an option contract.

HTTP request example

https://api.twelvedata.com/options/expiration?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "dates": [
    "2021-09-17",
    "2021-09-24",
    "2021-10-01",
    "2021-10-08",
    "2021-10-15",
    "2021-10-22",
    "2021-11-19",
    "2021-12-17",
    "2022-01-21",
    "2022-03-18",
    "2022-04-14",
    "2022-06-17",
    "2022-09-16",
    "2023-01-20",
    "2023-03-17",
    "2023-06-16",
    "2023-09-15"
  ]
}

HTTP route

/options/expiration

API credits

200 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
dates array Returns an array of future expiration dates in ascending order

JSON request example

https://api.twelvedata.com/options/expiration?symbol=AAPL&apikey=demo

Options Chain

Returns a listing of all available options contracts for given security. It shows all listed puts, calls, their expiration, strike prices, and pricing information for a single underlying asset within a given maturity period.

HTTP request example

https://api.twelvedata.com/options/chain?symbol=AAPL&expiration_date=2022-01-21&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "calls": [
    {
      "contract_name": "AAPL Option Call 21-01-2022 145",
      "option_id": "AAPL220121C00145000",
      "last_trade_date": "2021-09-13 14:53:00",
      "strike": 145,
      "last_price": 11.95,
      "bid": 11.95,
      "ask": 12.15,
      "change": -3.2700005,
      "percent_change": -21.48489,
      "volume": 1318,
      "open_interest": 48688,
      "implied_volatility": 0.2850108120727538,
      "in_the_money": true
    }
  ],
  "puts": [
    {
      "contract_name": "AAPL Option Put 21-01-2022 150",
      "option_id": "AAPL220121P00150000",
      "last_trade_date": "2021-09-13 14:52:00",
      "strike": 150,
      "last_price": 10.25,
      "bid": 10.2,
      "ask": 10.4,
      "change": 2.4499998,
      "percent_change": 31.410254,
      "volume": 3588,
      "open_interest": 41797,
      "implied_volatility": 0.27579459564208975,
      "in_the_money": true
    }
  ]
}

HTTP route

/options/chain

API credits

50 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
expiration_date string • Required parameter, if option_id is not specified
• Expiration date of an option contract
• Could be requested via /options/expiration endpoint
• Format 2006-01-02
option_id string • Required parameter, if expiration_date is not specified
• Contract name of an option
• Format AAPL220121C00505000
side string • Parameter is optional
• Specifies calls or puts side of an option
• Works only when expiration_date parameter is set
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
contract_name string Expanded components of an options symbol
option_id string Option symbol as per OCC (Options Clearing Corporation) symbology
last_trade_date string Refers to the last trade datetime of an option
strike number Returns strike price of an option at which it can be exercised
last_price number Returns price of the last trade if available
bid number Bid price of the last trade if available
ask number Ask price of the last trade if available
change number Change of current price compared to previous day close
percent_change number Change of current price compared to previous day close in percentage
volume number Refers to the number of trades completed in a day
open_interest number Refers to the number of contracts that are held by traders and investors in active positions, ready to be traded
implied_volatility number Represents implied volatility (IV) in percentage
in_the_money bool true if in-the-money (ITM), false if out of the money (OTM)

JSON request example

https://api.twelvedata.com/options/chain?symbol=AAPL&expiration_date=2022-01-21&apikey=demo

Key ExecutivesUseful

Returns individuals at the highest level of management of an organization.

HTTP request example

https://api.twelvedata.com/key_executives?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "key_executives": [
    {
      "name": "Mr. Timothy D. Cook",
      "title": "CEO & Director",
      "age": 59,
      "year_born": 1961,
      "pay": 14769259
    },
    {
      "name": "Mr. Luca  Maestri",
      "title": "CFO & Sr. VP",
      "age": 56,
      "year_born": 1964,
      "pay": 4595583
    },
    {
      "name": "Mr. Jeffrey E. Williams",
      "title": "Chief Operating Officer",
      "age": 56,
      "year_born": 1964,
      "pay": 4594137
    }
  ]
}

HTTP route

/key_executives

API credits

1000 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
name string Full name of an executive, including first name, middle name, last name, and suffix
title string Refers to job title
age number Current age of an executive if available
year_born number Year of birth of an executive if available
pay number Total salary of an executive if available

JSON request example

https://api.twelvedata.com/key_executives?symbol=AAPL&apikey=demo

Institutional Holders

Returns the amount of the company’s available stock owned by institutions (pension funds, insurance companies, investment firms, private foundations, endowments, or other large entities that manage funds on behalf of others).

HTTP request example

https://api.twelvedata.com/institutional_holders?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "institutional_holders": [
    {
      "entity_name": "Vanguard Group, Inc. (The)",
      "date_reported": "2021-06-30",
      "shares": 1264936543,
      "value": 173245708929,
      "percent_held": 0.0765
    },
    {
      "entity_name": "Blackrock Inc.",
      "date_reported": "2021-06-30",
      "shares": 1028698316,
      "value": 140890521359,
      "percent_held": 0.0622
    },
    {
      "entity_name": "Berkshire Hathaway, Inc",
      "date_reported": "2021-06-30",
      "shares": 887135554,
      "value": 121502085475,
      "percent_held": 0.0537
    }
  ]
}

HTTP route

/institutional_holders

API credits

1500 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
entity_name string Refers to the legal name of the institution
date_reported string Refers to date reported
shares number Refers to the number of shares owned
value number Total value of shares owned, calculated by multiplying shares by the current price
percent_held number Represents the percentage of shares outstanding that are owned by the financial institution

JSON request example

https://api.twelvedata.com/institutional_holders?symbol=AAPL&apikey=demo

Fund Holders

Returns the amount of the company’s available stock owned by mutual fund holders.

HTTP request example

https://api.twelvedata.com/fund_holders?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "fund_holders": [
    {
      "entity_name": "Vanguard Total Stock Market Index Fund",
      "date_reported": "2021-06-30",
      "shares": 447734657,
      "value": 61321738622,
      "percent_held": 0.0271
    },
    {
      "entity_name": "Vanguard 500 Index Fund",
      "date_reported": "2021-06-30",
      "shares": 325785979,
      "value": 44619647683,
      "percent_held": 0.0197
    },
    {
      "entity_name": "SPDR S&P 500 ETF Trust",
      "date_reported": "2021-06-30",
      "shares": 161505783,
      "value": 22119832039,
      "percent_held": 0.0098
    }
  ]
}

HTTP route

/fund_holders

API credits

1500 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
entity_name string Refers to the legal name of the fund
date_reported string Refers to date reported
shares number Refers to the number of shares owned
value number Total value of shares owned, calculated by multiplying shares by the current price
percent_held number Represents the percentage of shares outstanding that are owned by the fund

JSON request example

https://api.twelvedata.com/fund_holders?symbol=AAPL&apikey=demo

Direct HoldersNew

Returns the amount of the stocks owned directly and recorded in the company's share registry.

HTTP request example

https://api.twelvedata.com/direct_holders?symbol=4261&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "4261",
    "name": "Theeb Rent A Car Company",
    "currency": "SAR",
    "exchange": "Tadawul",
    "mic_code": "XSAU",
    "exchange_timezone": "Asia/Riyadh"
  },
  "direct_holders": [
    {
      "entity_name": "Growth Opportunities Co. For Trading",
      "date_reported": "2022-04-17",
      "shares": 2145700,
      "value": 154490400,
      "percent_held": null
    },
    {
      "entity_name": "Dhabib Nayef Mohammed Ahmed Al",
      "date_reported": "2022-04-17",
      "shares": 210700,
      "value": 15170400,
      "percent_held": null
    },
    {
      "entity_name": "Dhabib Mohammed Ahmed Abdullah Al",
      "date_reported": "2022-04-17",
      "shares": 10461900,
      "value": 753256800,
      "percent_held": null
    },
    {
      "entity_name": "Dhabib Mohammed Mahmoud Abdullah Al",
      "date_reported": "2022-04-17",
      "shares": 849981,
      "value": 61198632,
      "percent_held": null
    },
    {
      "entity_name": "Dhabib Hamood Abdullah Ibrahim Al",
      "date_reported": "2022-04-17",
      "shares": 5813600,
      "value": 418579200,
      "percent_held": null
    }
  ]
}

HTTP route

/direct_holders

API credits

1500 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
entity_name string Refers to the legal name of the fund
date_reported string Refers to date reported
shares number Refers to the number of shares owned
value number Total value of shares owned, calculated by multiplying shares by the current price
percent_held number Represents the percentage of shares outstanding that are owned by the fund

JSON request example

https://api.twelvedata.com/direct_holders?symbol=4261&apikey=demo

AnalysisNew

Earnings EstimateUseful

This API endpoint returns analysts' estimate for a company's future quarterly and annual earnings per share (EPS).

HTTP request example

https://api.twelvedata.com/earnings_estimate?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "earnings_estimate": [
    {
      "date": "2022-09-30",
      "period": "current_quarter",
      "number_of_analysts": 27,
      "avg_estimate": 1.26,
      "low_estimate": 1.13,
      "high_estimate": 1.35,
      "year_ago_eps": 1.24
    },
    {
      "date": "2022-12-31",
      "period": "next_quarter",
      "number_of_analysts": 23,
      "avg_estimate": 2.12,
      "low_estimate": 2.01,
      "high_estimate": 2.29,
      "year_ago_eps": 2.1
    },
    {
      "date": "2022-09-30",
      "period": "current_year",
      "number_of_analysts": 37,
      "avg_estimate": 6.1,
      "low_estimate": 5.96,
      "high_estimate": 6.4,
      "year_ago_eps": 5.61
    },
    {
      "date": "2023-09-30",
      "period": "next_year",
      "number_of_analysts": 37,
      "avg_estimate": 6.44,
      "low_estimate": 5.79,
      "high_estimate": 7.06,
      "year_ago_eps": 6.1
    }
  ],
  "status": "ok"
}

HTTP route

/earnings_estimate

API credits

20 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
period defines period of estimation, can be current_quarter, next_quarter, current_year, or next_year
number_of_analysts number of analysts that made the estimation
avg_estimate average estimation across analysts
low_estimate lowest estimation given by an analyst
high_estimate highest estimation given by an analyst
year_ago_eps average estimation of this period’s earnings given a year ago

JSON request example

https://api.twelvedata.com/earnings_estimate?symbol=aapl&apikey=demo

Revenue Estimate

This API endpoint returns analysts' estimate for a company's future quarterly and annual sales (total revenue).

HTTP request example

https://api.twelvedata.com/revenue_estimate?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "revenue_estimate": [
    {
      "date": "2022-09-30",
      "period": "current_quarter",
      "number_of_analysts": 24,
      "avg_estimate": 88631500000,
      "low_estimate": 85144300000,
      "high_estimate": 92794900000,
      "year_ago_sales": 83360000000,
      "sales_growth": 0.06
    },
    {
      "date": "2022-12-31",
      "period": "next_quarter",
      "number_of_analysts": 20,
      "avg_estimate": 127693000000,
      "low_estimate": 122868000000,
      "high_estimate": 132979000000,
      "year_ago_sales": null,
      "sales_growth": null
    },
    {
      "date": "2022-09-30",
      "period": "current_year",
      "number_of_analysts": 36,
      "avg_estimate": 392509000000,
      "low_estimate": 389326000000,
      "high_estimate": 396977000000,
      "year_ago_sales": 365817000000,
      "sales_growth": 0.07
    },
    {
      "date": "2023-09-30",
      "period": "next_year",
      "number_of_analysts": 36,
      "avg_estimate": 411466000000,
      "low_estimate": 387836000000,
      "high_estimate": 441307000000,
      "year_ago_sales": 392509000000,
      "sales_growth": 0.05
    }
  ],
  "status": "ok"
}

HTTP route

/revenue_estimate

API credits

20 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
dp • Number of decimal places for floating values
• Should be in range [0,11] inclusive. Default 5
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
period defines period of estimation, can be current_quarter, next_quarter, current_year, or next_year
number_of_analysts number of analysts that made the estimation
avg_estimate average estimation across analysts
low_estimate lowest estimation given by an analyst
high_estimate highest estimation given by an analyst
year_ago_sales total revenue received a year ago relative to period
sales_growth estimated sales growth of the period in relation to year-ago sales in prc (%)

JSON request example

https://api.twelvedata.com/revenue_estimate?symbol=aapl&apikey=demo

EPS Trend

This API endpoint returns a breakdown of the estimated historical EPS changes at a given period.

HTTP request example

https://api.twelvedata.com/eps_trend?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "eps_trend": [
    {
      "date": "2022-09-30",
      "period": "current_quarter",
      "current_estimate": 1.26,
      "7_days_ago": 1.26,
      "30_days_ago": 1.31,
      "60_days_ago": 1.32,
      "90_days_ago": 1.33
    },
    {
      "date": "2022-12-31",
      "period": "next_quarter",
      "current_estimate": 2.12,
      "7_days_ago": 2.11,
      "30_days_ago": 2.18,
      "60_days_ago": 2.19,
      "90_days_ago": 2.19
    },
    {
      "date": "2022-09-30",
      "period": "current_year",
      "current_estimate": 6.1,
      "7_days_ago": 6.1,
      "30_days_ago": 6.13,
      "60_days_ago": 6.14,
      "90_days_ago": 6.14
    },
    {
      "date": "2023-09-30",
      "period": "next_year",
      "current_estimate": 6.44,
      "7_days_ago": 6.44,
      "30_days_ago": 6.51,
      "60_days_ago": 6.55,
      "90_days_ago": 6.56
    }
  ],
  "status": "ok"
}

HTTP route

/eps_trend

API credits

20 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
period defines period of estimation, can be current_quarter, next_quarter, current_year, or next_year
current_estimate actual EPS estimation for the period
7_days_ago EPS estimation value 7 days ago
30_days_ago EPS estimation value 30 days ago
60_days_ago EPS estimation value 60 days ago
90_days_ago EPS estimation value 90 days ago

JSON request example

https://api.twelvedata.com/eps_trend?symbol=aapl&apikey=demo

EPS Revisions

This API endpoint returns analysts’ revisions of a company's future quarterly and annual earnings per share (EPS) over the last week and month.

HTTP request example

https://api.twelvedata.com/eps_revisions?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "eps_revision": [
    {
      "date": "2022-09-30",
      "period": "current_quarter",
      "up_last_week": 1,
      "up_last_month": 5,
      "down_last_week": 0,
      "down_last_month": 0
    },
    {
      "date": "2022-12-31",
      "period": "next_quarter",
      "up_last_week": 1,
      "up_last_month": 5,
      "down_last_week": 0,
      "down_last_month": 0
    },
    {
      "date": "2022-09-30",
      "period": "current_year",
      "up_last_week": 1,
      "up_last_month": 10,
      "down_last_week": 0,
      "down_last_month": 1
    },
    {
      "date": "2023-09-30",
      "period": "next_year",
      "up_last_week": 1,
      "up_last_month": 10,
      "down_last_week": 0,
      "down_last_month": 1
    }
  ],
  "status": "ok"
}

HTTP route

/eps_revisions

API credits

20 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
period defines period of estimation, can be current_quarter, next_quarter, current_year, or next_year
up_last_week number of up revisions over the last 7 days
up_last_month number of up revisions over the last 30 days
down_last_week number of down revisions over the last 7 days
down_last_month number of down revisions over the last 30 days

JSON request example

https://api.twelvedata.com/eps_revisions?symbol=aapl&apikey=demo

Growth Estimates

This API endpoint returns consensus analyst estimates over the company's growth rates for various periods.

HTTP request example

https://api.twelvedata.com/growth_estimates?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "growth_estimates": {
    "current_quarter": 0.016,
    "next_quarter": 0.01,
    "current_year": 0.087,
    "next_year": 0.055999998,
    "next_5_years_pa": 0.094799995,
    "past_5_years_pa": 0.23867
  },
  "status": "ok"
}

HTTP route

/growth_estimates

API credits

20 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
current_quarter projected growth of the current quarter in prc (%)
next_quarter projected growth of the next quarter in prc (%)
current_year projected growth of the current year in prc (%)
next_year projected growth of the next year in prc (%)
next_5_years_pa projected growth during the next 5 years in prc (%) per annum
past_5_years_pa actual growth over the last 5 years in prc (%) per annum

JSON request example

https://api.twelvedata.com/growth_estimates?symbol=aapl&apikey=demo

RecommendationsHigh Demand

This API endpoint returns the average of all analyst recommendations and classifies them as Strong Buy, Buy, Hold, or Sell. Also, it returns a recommendation score.

HTTP request example

https://api.twelvedata.com/recommendations?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "trends": {
    "current_month": {
      "strong_buy": 11,
      "buy": 21,
      "hold": 6,
      "sell": 0,
      "strong_sell": 0
    },
    "previous_month": {
      "strong_buy": 14,
      "buy": 24,
      "hold": 8,
      "sell": 0,
      "strong_sell": 0
    },
    "2_months_ago": {
      "strong_buy": 14,
      "buy": 24,
      "hold": 8,
      "sell": 0,
      "strong_sell": 0
    },
    "3_months_ago": {
      "strong_buy": 13,
      "buy": 20,
      "hold": 8,
      "sell": 0,
      "strong_sell": 0
    }
  },
  "rating": 8.2,
  "status": "ok"
}

HTTP route

/recommendations

API credits

100 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
strong_buy number of analysts that give a strong buy recommendation
buy number of analysts that give a buy recommendation
hold number of analysts that give a hold recommendation
sell number of analysts that give a sell recommendation
strong_sell number of analysts that give a strong sell recommendation
rating rating from 0 to 10 represents overall analysts’ recommendation. 0 to 2 - strong sell, 2 to 4 - sell, 4 to 6 - hold, 6 to 8 - buy, 8 to 10 - strong buy.

JSON request example

https://api.twelvedata.com/recommendations?symbol=aapl&apikey=demo

Price TargetHigh Demand

This API endpoint returns the analysts' projection of a security's future price.

HTTP request example

https://api.twelvedata.com/price_target?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "price_target": {
    "high": 220,
    "median": 185,
    "low": 136,
    "average": 184.01,
    "current": 169.5672
  },
  "status": "ok"
}

HTTP route

/price_target

API credits

75 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
high highest price target given by an analyst
median median price target given across analysts
low lowest price target given by an analyst
average average price target given across analysts
current current price from of a security

JSON request example

https://api.twelvedata.com/price_target?symbol=aapl&apikey=demo

Analyst Ratings - Light

This API endpoint returns a lightweight version of ratings issued by analyst firms. Works for US and international markets.

HTTP request example

https://api.twelvedata.com/analyst_ratings/light?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "ratings": [
    {
      "date": "2022-08-19",
      "firm": "Keybanc",
      "rating_change": "Maintains",
      "rating_current": "Overweight",
      "rating_prior": "Overweight"
    },
    {
      "date": "2022-08-17",
      "firm": "Credit Suisse",
      "rating_change": "Upgrade",
      "rating_current": "Outperform",
      "rating_prior": "Neutral"
    },
    {
      "date": "2022-08-17",
      "firm": "Wedbush",
      "rating_change": "Maintains",
      "rating_current": "Outperform",
      "rating_prior": "Outperform"
    }
  ],
  "status": "ok"
}

HTTP route

/analyst_ratings/light

API credits

75 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
rating_change • Parameter is optional
• Filter by rating change action: Maintains, Upgrade, Downgrade, Initiates or Reiterates
outputsize • Parameter is optional
• Number of records in response; default 30
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
date date when the rating was released
firm firm that issued the ranking
rating_change defines the action of the firm to ranking, could be Maintains, Upgrade, Downgrade, Initiates or Reiterates
rating_current current firm's ranking of the instrument
rating_prior prior firm's ranking of the instrument

JSON request example

https://api.twelvedata.com/analyst_ratings/light?symbol=aapl&apikey=demo

https://api.twelvedata.com/analyst_ratings/light?symbol=infy&country=india&apikey=demo

Analyst Ratings - US Equities

This API endpoint returns complete information on ratings issued by analyst firms. Works only for US equities.

HTTP request example

https://api.twelvedata.com/analyst_ratings/us_equities?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "ratings": [
    {
      "date": "2022-08-19",
      "firm": "Keybanc",
      "analyst_name": "Brandon Nispel",
      "rating_change": "Maintains",
      "rating_current": "Overweight",
      "rating_prior": "Overweight",
      "time": "08:29:48",
      "action_price_target": "Raises",
      "price_target_current": 185,
      "price_target_prior": 177
    },
    {
      "date": "2022-08-17",
      "firm": "Credit Suisse",
      "analyst_name": "Shannon Cross",
      "rating_change": "Upgrade",
      "rating_current": "Outperform",
      "rating_prior": "Neutral",
      "time": "08:14:09",
      "action_price_target": "Announces",
      "price_target_current": 201,
      "price_target_prior": null
    },
    {
      "date": "2022-08-17",
      "firm": "Wedbush",
      "analyst_name": "Daniel Ives",
      "rating_change": "Maintains",
      "rating_current": "Outperform",
      "rating_prior": "Outperform",
      "time": "10:22:55",
      "action_price_target": "Raises",
      "price_target_current": 220,
      "price_target_prior": 200
    }
  ],
  "status": "ok"
}

HTTP route

/analyst_ratings/us_equities

API credits

200 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
exchange • Parameter is optional
• Filter by exchange name or mic code
rating_change • Parameter is optional
• Filter by rating change action: Maintains, Upgrade, Downgrade, Initiates, Reiterates, Assumes, or Reinstates
outputsize • Parameter is optional
• Number of records in response; default 30
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
date date when the rating was released
firm firm that issued the ranking
analyst_name name of an analyst
rating_change defines the action of the firm to ranking, could be Maintains, Upgrade, Downgrade, Initiates, Reiterates, Assumes, or Reinstates
rating_current current firm's ranking of the instrument
rating_prior prior firm's ranking of the instrument
time time when the rating was released or updated
action_price_target action that firm took towards target price
price_target_current current firm's price target for the instrument
price_target_prior prior firm's price target for the instrument

JSON request example

https://api.twelvedata.com/analyst_ratings/us_equities?symbol=aapl&apikey=demo

WebSocket

Connect & Authorize

# Pass API key as connection parameter
wss://ws.twelvedata.com/v1/{$route}?apikey=your_api_key

# Or pass API key separately in header
wss://ws.twelvedata.com/v1/{$route}
X-TD-APIKEY: your_api_key

WebSocket will automatically send the data to you once a new piece of data is available on the exchange. In the beginning, you need to establish a connection between the server and the client. Then all data is controlled by sending event messages to the server. WebSocket is opposed to the API, where the data has to be explicitly requested from the server.

You may use the API key to connect to the Twelve Data Distributed WebSocket System (TDDWS). This system will manage all your requests to all available instruments across different exchanges. You can establish up to 3 connections (typically used in production, stage, and local environments) across the whole lifespan of the application; if you open more, the previous connections will be closed.

You may subscribe to all symbols available at Twelve Data; meanwhile, the format remains the same as the API unless there are constraints in the endpoint. Moreover, you may combine symbols across different types, and TDDWS will manage the routing. There are some limitations, though:

Please note that full access to WebSocket is available for the users on the Pro plan and above. However, testing can be done on the Basic and Grow tier plans with only one connection and up to 8 simultaneous symbols subscriptions among the permitted list.

Resources
You can try out streaming via WebSocket Playground located in the personal dashboard. On Basic and Grow plans, only trial symbols can be used; on Pro plan and above, any instrument can be streamed.

Trial symbols
WebSocket FAQ
How to stream data tutorial

Real-time priceUseful

This method allows you to get real-time price streaming from the exchange. Equities also have day volume information.

Subscribe to stream

# You may subscribe to multiple symbols by calling subscribe action. 
# Additionally, you can pass the exchange name after the colon(:).
{
  "action": "subscribe", 
  "params": {
    "symbols": "AAPL,RY,RY:TSX,EUR/USD,BTC/USD"
  }
}
# Alternatively, if you need to get data from the ambiguos symbol you may use the extended format
{ "action": "subscribe", 
  "params": {
    "symbols": [{
        "symbol": "AAPL",
        "exchange": "NASDAQ"
      }, {
        "symbol": "RY", 
        "mic_code": "XNYS"
      }, {
        "symbol": "DJI",
        "type": "Index"
      }
]}}

Response

Success subscription response:
{
  "event": "subscribe-status",
  "status": "ok",
  "success": [
    {"symbol":"AAPL","exchange":"NASDAQ","country":"United States","type":"Common Stock"},
    {"symbol":"RY","exchange":"NYSE","country":"United States","type":"Common Stock"},
    {"symbol":"RY","exchange":"TSX","country":"Canada","type":"Common Stock"},
    {"symbol":"EUR/USD","exchange":"FOREX","country":"","type":"Physical Currency"},
    {"symbol":"BTC/USD","exchange":"FOREX","country":"","type":"Physical Currency"}
  ],
  "fails": []
}
Price event data response:
{
  "event": "price",
  "symbol": "AAPL",
  "currency": "USD",
  "exchange": "NASDAQ",
  "type": "Common Stock",
  "timestamp": 1592249566,
  "price": 342.0157,
  "day_volume": 27631112
}
Bid/Ask data response; only precious metals:
{
  "event": "price",
  "symbol": "XAU/USD",
  "currency": "USD",
  "currency_base": "Gold Spot",
  "currency_quote": "US Dollar",
  "type": "Physical Currency",
  "timestamp": 1647950462,
  "price": 1925.18,
  "bid": 1925.05,
  "ask": 1925.32
}

Route

/quotes/price

WebSocket credits

1 per symbol, API credits are not used

Response

There are two general return event types: status and price.

Status events return the information about the events itself, which symbols were successfully subscribed/unsubscribed, etc.

Price events return the real-time tick prices for particular instruments. The body will include the meta information, UNIX timestamp, and the price itself. Price events return the real-time tick prices, with the following structure:

field* description
event type of event
symbol symbol ticker of instrument
type general instrument type
timestamp timestamp in UNIX format
price real-time price for the underlying instrument
day_volume volume of the instrument for the current trading day

*Some additional meta response field will be received, depending on the class of the instrument.

Further steps

At this stage you might decide that you no longer want to be subscribed for particular symbols, therefore you have two options:

  1. Manually unsubscribe from symbols. This is done with the same format as the subscription, but with action set to "action": "unsubscribe".
  2. Reset subscription. This will reset your current connection from all subscriptions.
    Send the {"action": "reset"} event.

We also recommend sending {"action": "heartbeat"} events to the server every 10 seconds or so. This will make sure to keep your connection stable.

Advanced

Complex DataUseful

With this endpoint, you may construct a complex request across multiple instruments, intervals, and data methods at the same time. Only JSON POST requests are accepted. The number of simultaneous requests is only limited according to your plan.

The content structure consists of 2 main parts. The first one are the general parameters that apply to all listed methods by default. The second one are the methods objects.

HTTP request example

https://api.twelvedata.com/complex_data?apikey=your_api_key
--header "Content-Type: application/json" \
--request POST \
--data '{
    "symbols": ["AAPL", "MSFT", "GOOG"],
    "intervals": ["5min", "1day"],
    "outputsize": 25,
    "methods": [
        "time_series",
        {
            "name": "ema",
            "time_period": 12
        },
        "quote",
        {
            "name": "adx",
            "order": "ASC"
        }
    ]
}'

This request will return JSON with the following structure

{
  "data": [
    {"meta": {"symbol" : "AAPL", "interval": "5min", ...}, "values": [...], "status": "ok"},
    {"meta": {"symbol" : "AAPL", "interval": "1day", ...}, "values": [...], "status": "ok"},
    {"meta": {"symbol" : "MSFT", "interval": "5min", ...}, "values": [...], "status": "ok"},
    {"meta": {"symbol" : "MSFT", "interval": "1day", ...}, "values": [...], "status": "ok"},
    {"meta": {"symbol" : "GOOG", "interval": "5min", ...}, "values": [...], "status": "ok"},
    ...
    {"meta": {"symbol" : "GOOG", "interval": "1day", ...}, "values": [...], "status": "ok"}
  ],
  "status": "ok"
}

Example of error in the one of the responses

{
  "data": [
    {"code": 400, "message": "**symbol** not found...", "meta":  {"symbol" : "...", "interval": "..", "exchange": "..."}, "status": "error"},
    ...
    {"meta": {"symbol" : "...", "interval": "...", ...}, "values": [...], "status": "ok"}
  ],
  "status": "ok"
}

POST route

/complex_data

API credits

1 per returned symbol object

Common Parameters

Parameter Details
intervals
array
• Array of intervals: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
outputsize
int
• Number of data points to retrieve
• Default 30
start_date
string
• Format 2006-01-02 or 2006-01-02 15:04:05
• If timezone is given then, start_date will be used in the specified location
end_date
string
• Format 2006-01-02 or 2006-01-02 15:04:05
• If timezone is given then, end_date will be used in the specified location
dp
int
• Number of decimal places for floating values
• Should be in range [0,11] inclusive. Default 5
order
string
• Sorting order of the output series
• Supports: ASC, DESC; Default DESC
timezone
string
• Timezone at which output datetime will be displayed
• Supports: Exchange, UTC or timezone according to IANA Time Zone Database

General Parameters

Parameter Details
symbols
array
• Array of symbols
• Format: symbol:exchange:country, where exchange and country are optional
• Batch listing is not supported
apikey
string
• Required parameter
• Your personal API key, which you can obtain for free here
• Type string
methods
string or object
• Accepts: time_series, quote, price or any of the technical indicators.
• Could be either a string with method name, then default parameters are taken. Alternatively, with object you might specify custom parameters.
common parameters • Any of the parameters listed above

Method Parameters

Parameter Details
name
string or object
• Name of endpoint
common parameters • Any of the parameters listed above

Response

The successful response body contains data array and status=ok. The array has the same format as the single API call, except when the error occurs where the additional meta-object is included.

API Usage

This endpoint will provide information on the current usage of Twelve Data API.

HTTP request example

https://api.twelvedata.com/api_usage?apikey=your_api_key

This request will return JSON with the following structure

{
  "timestamp": "2020-03-16 09:05:16",
  "current_usage": 4003,
  "plan_limit": 4181
}

HTTP route

/api_usage

API credits

1 per request

API parameters

Parameter Details
apikey • Required parameter
• Your personal API key, which you can obtain for free here
• Type string
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;

Response

Key Description
timestamp current timestamp in UTC timezone
current_usage number of requests made in last minute
plan_limit your personal API limit (requests/minute) depending on the plan

JSON request example

https://api.twelvedata.com/api_usage?apikey=your_api_key

Downloadable CSV example

https://api.twelvedata.com/api_usage?apikey=your_api_key&format=CSV

Technical Indicators

Technical indicators return real-time and historical values of the demanded indicator at the selected interval. If you don‘t see the necessary technical indicator, you may request it to be added.

Chaikin A/D Line(AD) calculates the Advance/Decline of an asset. This indicator belongs to the group of Volume Indicators.

This API call returns "meta" and "time_series" values of AD. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/ad?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "AD - Chaikin A/D Line"
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "ad":"2262629.83773"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "ad":"2271951.53983"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "ad":"2344317.27255"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "ad":"2288433.82567"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "ad":"2467325.82567"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/ad

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
ad ad value

JSON request example

https://api.twelvedata.com/ad?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/ad?symbol=INFY&exchange=BSE&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/ad?symbol=AAPL&interval=30min&format=CSV&apikey=demo

ADD

Composite of values of two specified time series.

This API call returns "meta" and "time_series" values of ADD. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/add?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "ADD - Arithmetic Addition",
         "series_type_1": "open",
         "series_type_2": "close"
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "add":"402.10798"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "add":"401.97"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "add":"401.98001"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "add":"402.2934"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "add":"402.83"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/add

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
series_type_1 string • Parameter is optional
• Price type used as the first part of technical indicator
• Default open
Code Name
0 close
1 open
2 high
3 low
4 volume
series_type_2 string • Parameter is optional
• Price type used as the second part of technical indicator
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
add add value

JSON request example

https://api.twelvedata.com/add?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/add?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/add?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

ADOSC

Chaikin A/D Oscillator(ADOSC) is an indicator, which finds the relationship between increasing and decreasing volume with price fluctuations. The Chaikin Oscillator measures the momentum of the Accumulation/Distribution Line(ADL) using two Exponential Moving Averages of varying length to the line(MACD).

This API call returns "meta" and "time_series" values of ADOSC. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/adosc?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "ADOSC - Chaikin A/D Oscillator",
         "fast_period": 12,
         "slow_period": 26
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "adosc":"-233315.15185"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "adosc":"-214691.54601"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "adosc":"-188747.38536"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "adosc":"-160255.93296"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "adosc":"-115869.53282"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/adosc

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
fast_period number • Parameter is optional
• Number of periods for fast moving average. Takes values in the range from 1 to 800
• Default 12
slow_period number • Parameter is optional
• Number of periods for slow moving average. Takes values in the range from 1 to 800
• Default 26
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
adosc adosc value

JSON request example

https://api.twelvedata.com/adosc?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/adosc?symbol=INFY&exchange=BSE&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/adosc?symbol=AAPL&interval=30min&format=CSV&apikey=demo

ADXHigh Demand

Average Directional Index(ADX) is used to decide if the price trend is strong.

This API call returns "meta" and "time_series" values of ADX. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/adx?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "ADX - Average Directional Index",
         "time_period": 14
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "adx":"49.22897"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "adx":"47.73058"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "adx":"44.90916"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "adx":"41.9312"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "adx":"38.83754"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/adx

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 14
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
adx adx value

JSON request example

https://api.twelvedata.com/adx?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/adx?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/adx?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

ADXR

Average Directional Movement Index Rating(ADXR) is a smoothed version of the ADX indicator. ADXR quantifies momentum change in the ADX.

This API call returns "meta" and "time_series" values of ADXR. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/adxr?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "ADXR - Average Directional Movement Index Rating",
         "time_period": 14
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "adxr":"37.43665"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "adxr":"36.83599"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "adxr":"35.58524"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "adxr":"34.41498"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "adxr":"33.21139"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/adxr

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 14
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
adxr adxr value

JSON request example

https://api.twelvedata.com/adxr?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/adxr?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/adxr?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

APO

Absolute Price Oscillator(APO) calculates the difference between two price moving averages.

This API call returns "meta" and "time_series" values of APO. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/apo?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "APO - Absolute Price Oscillator",
         "fast_period": 12,
         "ma_type": "SMA",
         "series_type": "close",
         "slow_period": 26
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "apo":"-0.54508"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "apo":"-0.47169"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "apo":"-0.39004"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "apo":"-0.3087"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "apo":"-0.23315"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/apo

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
fast_period number • Parameter is optional
• Number of periods for fast moving average. Takes values in the range from 1 to 800
• Default 12
ma_type string • Parameter is optional
• Type of Moving Average to be used
• Default SMA
Code Name
0 SMA
1 EMA
2 WMA
3 DEMA
4 TEMA
5 TRIMA
6 KAMA
7 MAMA
8 T3MA
series_type string • Parameter is optional
• Price type on which technical indicator is calculated
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
slow_period number • Parameter is optional
• Number of periods for slow moving average. Takes values in the range from 1 to 800
• Default 26
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
apo apo value

JSON request example

https://api.twelvedata.com/apo?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/apo?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/apo?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

AROON

Aroon Indicator(AROON) is used to identify if the price is trending. It can also spot the beginning of a new trend and its strength.

This API call returns "meta" and "time_series" values of AROON. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/aroon?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "AROON - Aroon Indicator",
         "time_period": 14
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "aroon_down":"92.85714",
         "aroon_up":"0.0"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "aroon_down":"100.0",
         "aroon_up":"7.14286"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "aroon_down":"100.0",
         "aroon_up":"0.0"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "aroon_down":"100.0",
         "aroon_up":"0.0"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "aroon_down":"100.0",
         "aroon_up":"7.14286"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/aroon

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 14
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
aroon_down aroon_down value
aroon_up aroon_up value

JSON request example

https://api.twelvedata.com/aroon?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/aroon?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/aroon?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

AROONOSC

Aroon Oscillator(AROONOSC) uses classic Aroon(Aroon Up and Aroon down) to measure the strength of persisting trends and whether they will continue.

This API call returns "meta" and "time_series" values of AROONOSC. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/aroonosc?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "AROONOSC - Aroon Oscillator",
         "time_period": 14
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "aroonosc":"-92.85714"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "aroonosc":"-92.85714"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "aroonosc":"-100.0"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "aroonosc":"-100.0"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "aroonosc":"-92.85714"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/aroonosc

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 14
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
aroonosc aroonosc value

JSON request example

https://api.twelvedata.com/aroonosc?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/aroonosc?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/aroonosc?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

ATR

Average True Range(ATR) is used to measure market volatility by decomposing all asset prices over a specified time period.

This API call returns "meta" and "time_series" values of ATR. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/atr?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "ATR - Average True Range",
         "time_period": 14
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "atr":"0.19828"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "atr":"0.18246"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "atr":"0.17419"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "atr":"0.17528"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "atr":"0.17133"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/atr

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 14
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
atr atr value

JSON request example

https://api.twelvedata.com/atr?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/atr?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/atr?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

AVG

Average(AVG) calculates the average value of series in a given time period. Widely used to calculate the 9-day average volume.

This API call returns "meta" and "time_series" values of AVG. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/avg?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "AVG - Average",
         "series_type": "close",
         "time_period": 9
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "avg":"201.53871"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "avg":"201.69205"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "avg":"201.85111"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "avg":"202.03185"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "avg":"202.20237"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/avg

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
series_type string • Parameter is optional
• Price type on which technical indicator is calculated
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 9
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
avg avg value

JSON request example

https://api.twelvedata.com/avg?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/avg?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/avg?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

AVGPRICE

Average Price(AVGPRICE) uses the formula: (open + high + low + close) / 4.

This API call returns "meta" and "time_series" values of AVGPRICE. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/avgprice?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "AVGPRICE - Average Price"
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "avgprice":"201.02449"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "avgprice":"200.98375"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "avgprice":"201.005"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "avgprice":"201.1117"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "avgprice":"201.43"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/avgprice

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
avgprice avgprice value

JSON request example

https://api.twelvedata.com/avgprice?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/avgprice?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/avgprice?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

BBANDSHigh Demand

Bollinger Bands®(BBANDS) are volatility bands located above and below a moving average. The volatility size parameter depends on standard deviation.

This API call returns "meta" and "time_series" values of BBANDS. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/bbands?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "BBANDS - Bollinger Bands®",
         "ma_type": "SMA",
         "sd": 2,
         "series_type": "close",
         "time_period": 20
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "upper_band":"203.36511",
         "middle_band":"202.04999",
         "lower_band":"200.73486"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "upper_band":"203.39936",
         "middle_band":"202.13499",
         "lower_band":"200.87061"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "upper_band":"203.38227",
         "middle_band":"202.22324",
         "lower_band":"201.0642"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "upper_band":"203.32938",
         "middle_band":"202.30173",
         "lower_band":"201.27409"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "upper_band":"203.23305",
         "middle_band":"202.38007",
         "lower_band":"201.52709"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/bbands

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
ma_type string • Parameter is optional
• Type of Moving Average to be used
• Default SMA
Code Name
0 SMA
1 EMA
2 WMA
3 DEMA
4 TEMA
5 TRIMA
6 KAMA
7 MAMA
8 T3MA
sd number • Parameter is optional
• Number of standard deviations. Must be at least 1
• Default 2
series_type string • Parameter is optional
• Price type on which technical indicator is calculated
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 20
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
lower_band lower_band value
middle_band middle_band value
upper_band upper_band value

JSON request example

https://api.twelvedata.com/bbands?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/bbands?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/bbands?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

BETA

Statistic Beta function.

This API call returns "meta" and "time_series" values of BETA. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/beta?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "BETA - Beta",
         "series_type_1": "open",
         "series_type_2": "close",
         "time_period": 9
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "beta":"-0.05742"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "beta":"-0.31826"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "beta":"-0.60342"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "beta":"-0.4949"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "beta":"-0.24952"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/beta

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
series_type_1 string • Parameter is optional
• Price type used as the first part of technical indicator
• Default open
Code Name
0 close
1 open
2 high
3 low
4 volume
series_type_2 string • Parameter is optional
• Price type used as the second part of technical indicator
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 9
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
beta beta value

JSON request example

https://api.twelvedata.com/beta?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/beta?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/beta?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

BOP

Balance of Power(BOP) measures the relative strength between buyers and sellers by assessing the ability of move price to an extreme level.

This API call returns "meta" and "time_series" values of BOP. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/bop?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "BOP - Balance of Power"
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "bop":"0.27231"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "bop":"-0.32758"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "bop":"0.0"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "bop":"-0.38215"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "bop":"-0.91305"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/bop

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
bop bop value

JSON request example

https://api.twelvedata.com/bop?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/bop?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/bop?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

CCI

Commodity Channel Index(CCI) is a universal indicator that can help to identify new trends and assess current critical conditions.

This API call returns "meta" and "time_series" values of CCI. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/cci?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "CCI - Commodity Channel Index",
         "time_period": 20
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "cci":"-122.30794"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "cci":"-152.88827"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "cci":"-180.08234"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "cci":"-206.65411"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "cci":"-225.40021"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/cci

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 20
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
cci cci value

JSON request example

https://api.twelvedata.com/cci?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/cci?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/cci?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

CEIL

Vector CEIL(CEIL) transforms input data with the mathematical ceil function.

This API call returns "meta" and "time_series" values of CEIL. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/ceil?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "CEIL - Vector CEIL",
         "series_type": "close"
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "ceil":"202.0"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "ceil":"201.0"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "ceil":"202.0"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "ceil":"202.0"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "ceil":"202.0"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/ceil

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
series_type string • Parameter is optional
• Price type on which technical indicator is calculated
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
ceil ceil value

JSON request example

https://api.twelvedata.com/ceil?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/ceil?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/ceil?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

CMO

Chande Momentum Oscillator(CMO) is used to show overbought and oversold conditions.

This API call returns "meta" and "time_series" values of CMO. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/cmo?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "CMO - Chande Momentum Oscillator",
         "series_type": "close",
         "time_period": 9
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "cmo":"-71.24979"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "cmo":"-91.96597"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "cmo":"-91.27229"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "cmo":"-91.16542"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "cmo":"-90.41306"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/cmo

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
series_type string • Parameter is optional
• Price type on which technical indicator is calculated
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 9
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
cmo cmo value

JSON request example

https://api.twelvedata.com/cmo?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/cmo?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/cmo?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

COPPOCK

Coppock Curve(COPPOCK) is usually used to detect long-term trend changes, typically on monthly charts.

This API call returns "meta" and "time_series" values of COPPOCK. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/coppock?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "COPPOCK - Coppock Curve",
         "long_roc_period": 14,
         "series_type": "close",
         "short_roc_period": 11,
         "wma_period": 10
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "coppock":"-1.37253"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "coppock":"-1.28978"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "coppock":"-1.14204"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "coppock":"-0.97805"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "coppock":"-0.78209"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/coppock

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
long_roc_period number • Parameter is optional
• Number of periods for long term rate of change. Takes values in the range from 1 to 800
• Default 14
series_type string • Parameter is optional
• Price type on which technical indicator is calculated
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
short_roc_period number • Parameter is optional
• Number of periods for short term rate of change. Takes values in the range from 1 to 800
• Default 11
wma_period number • Parameter is optional
• Number of periods for weighted moving average. Takes values in the range from 1 to 800
• Default 10
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
coppock coppock value

JSON request example

https://api.twelvedata.com/coppock?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/coppock?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/coppock?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

CORREL

Measures linear correlation between two time series. Takes values in the range from -1 to 1, where -1 is total negative correlation, 0 is no correlation, and 1 is total positive correlation.

This API call returns "meta" and "time_series" values of CORREL. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/correl?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "CORREL - Pearson's Correlation Coefficient",
         "series_type_1": "open",
         "series_type_2": "close",
         "time_period": 9
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "correl":"0.93282"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "correl":"0.94333"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "correl":"0.94225"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "correl":"0.9415"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "correl":"0.93658"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/correl

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
series_type_1 string • Parameter is optional
• Price type used as the first part of technical indicator
• Default open
Code Name
0 close
1 open
2 high
3 low
4 volume
series_type_2 string • Parameter is optional
• Price type used as the second part of technical indicator
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 9
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
correl correl value

JSON request example

https://api.twelvedata.com/correl?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/correl?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/correl?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

CRSI

ConnorsRSI(CRSI) is used to show the oversold and overbought levels of the RSI values.

This API call returns "meta" and "time_series" values of CRSI. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/crsi?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "CRSI - ConnorsRSI",
         "percent_rank_period": 100,
         "rsi_period": 3,
         "series_type": "close",
         "up_down_length": 2
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "crsi":"74.76102"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "crsi":"16.46438"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "crsi":"25.13687"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "crsi":"14.47102"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "crsi":"11.14242"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/crsi

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
percent_rank_period number • Parameter is optional
• Number of periods used to calculate PercentRank. Takes values in the range from 1 to 800
• Default 100
rsi_period number • Parameter is optional
• Number of periods for RSI used to calculate price momentum. Takes values in the range from 1 to 800
• Default 3
series_type string • Parameter is optional
• Price type on which technical indicator is calculated
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
up_down_length number • Parameter is optional
• Number of periods for RSI used to calculate up/down trend. Takes values in the range from 1 to 800
• Default 2
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
crsi crsi value

JSON request example

https://api.twelvedata.com/crsi?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/crsi?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/crsi?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

DEMA

Double Exponential Moving Average(DEMA) is used to eliminate lag. It does this by taking two Exponential Moving Averages(EMA).

This API call returns "meta" and "time_series" values of DEMA. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/dema?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "DEMA - Double Exponential Moving Average",
         "series_type": "close",
         "time_period": 9
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "dema":"200.93371"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "dema":"200.98742"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "dema":"201.13274"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "dema":"201.30494"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "dema":"201.5495"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/dema

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
series_type string • Parameter is optional
• Price type on which technical indicator is calculated
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 9
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
dema dema value

JSON request example

https://api.twelvedata.com/dema?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/dema?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/dema?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

DIV

Division of values of two specified time series.

This API call returns "meta" and "time_series" values of DIV. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/div?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "DIV - Arithmetic Division",
         "series_type_1": "open",
         "series_type_2": "close"
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "div":"1.00201"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "div":"1.00144"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "div":"1.0008"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "div":"1.00113"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "div":"1.00343"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/div

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
series_type_1 string • Parameter is optional
• Price type used as the first part of technical indicator
• Default open
Code Name
0 close
1 open
2 high
3 low
4 volume
series_type_2 string • Parameter is optional
• Price type used as the second part of technical indicator
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
div div value

JSON request example

https://api.twelvedata.com/div?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/div?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/div?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

DPO

Detrended Price Oscillator(DPO) is used to separate price from the trend, in order to more clearly identify the length of cycles.

This API call returns "meta" and "time_series" values of DPO. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/dpo?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "DPO - Detrended Price Oscillator",
         "centered": false,
         "series_type": "close",
         "time_period": 21
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "dpo":"0.36828"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "dpo":"0.49811"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "dpo":"0.424"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "dpo":"0.35406"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "dpo":"0.25089"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/dpo

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
centered boolean • Parameter is optional
• Specifies if there should be a shift to match the current price
• Default false
series_type string • Parameter is optional
• Price type on which technical indicator is calculated
• Default close
Code Name
0 close
1 open
2 high
3 low
4 volume
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 21
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
meta json object with request general information
datetime datetime in local market time for equities and in UTC for forex and cryptocurrencies referring to when the bar with specified interval was opened
dpo dpo value

JSON request example

https://api.twelvedata.com/dpo?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/dpo?symbol=ETH/BTC&exchange=Huobi&interval=1day&outputsize=24&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/dpo?symbol=EUR/USD&interval=30min&format=CSV&apikey=demo

DX

Directional Movement Index(DX) identifies which direction the price is moving.

This API call returns "meta" and "time_series" values of DX. "meta" object consist of general information about the requested technical indicator. "time_series" is the array of objects ordered by time descending updated in real-time.

HTTP request example

https://api.twelvedata.com/dx?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "meta":{
      "symbol": "AAPL",
      "interval": "1min",
      "currency": "USD",
      "exchange_timezone": "America/New_York",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "type": "Common Stock",
      "indicator": {
         "name": "DX - Directional Movement Index",
         "time_period": 14
      }
   },
   "values":[
      {
         "datetime":"2019-08-09 15:59:00",
         "dx":"68.70803"
      },
      {
         "datetime":"2019-08-09 15:58:00",
         "dx":"84.40905"
      },
      {
         "datetime":"2019-08-09 15:57:00",
         "dx":"83.62259"
      },
      {
         "datetime":"2019-08-09 15:56:00",
         "dx":"82.14874"
      },
      {
         "datetime":"2019-08-09 15:55:00",
         "dx":"81.69497"
      },
      {...}
   ],
   "status":"ok"
}

HTTP route

/dx

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
time_period number • Parameter is optional
• Number of periods to average over. Takes values in the range from 1 to 800
• Default 14
type string • Parameter is optional
• Type to which instrument belongs
• Supports: Stock, Index, ETF, REIT
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here