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:
- At query string, as
&apikey=your_api_key - At header, as
Authorization="apikey your_api_key"
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&outputsize=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,QBNK
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,QBNK&interval=1min&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:
- 400 Follow message instructions in response. Usually, it will arise if one of the input parameters is set incorrectly. Try to read over API Documentation and modify the parameter.
- 401 Invalid API key is used. If you don't have one yet - get it here.
- 403 Upgrade your API key to an upper plan here.
- 404 Query parameters are set too strict and accordingly, data can not be loaded. Try to set less rigid parameters values.
- 414 Arises when the parameter accepts an array of values and length of the array is larger than the maximum number allowed. Follow the message instructions and set the parameter accordingly.
- 429 API key minute limit is reached. Either wait for a while or increase your API key limits here
- 500 Very rare to appear, signifying some server-side errors. In this case, contact us and we will settle down the issue.
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",
"figi_code": "BBG000B9Y5X2"
},
{
"symbol": "AAT",
"name": "American Assets Trust Inc",
"currency": "USD",
"exchange": "NYSE",
"mic_code": "XNYS",
"country": "United States",
"type": "Real Estate Investment Trust (REIT)",
"figi_code": "BBG00161BCW4"
},
{...}
]
// with &show_plan=true
{
"data": [
{
"symbol": "TCS",
"name": "Tata Consultancy Services Limited",
"currency": "INR",
"exchange": "NSE",
"mic_code": "XNSE",
"country": "India",
"type": "Common Stock",
"figi_code": "BBG000Q0WGC6",
"access": {
"global": "Level A",
"plan": "Grow"
}
},
{
"symbol": "TCS",
"name": "Axon Enterprise Inc",
"currency": "EUR",
"exchange": "FSX",
"mic_code": "XFRA",
"country": "Germany",
"type": "Common Stock",
"figi_code": "BBG000FB37K7",
"access": {
"global": "Level A",
"plan": "Grow"
}
},
{...}
],
"status": "ok"
}
HTTP route
API credits
1 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Parameter is optional • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| figi_code | financial instrument global identifier (FIGI) |
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
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
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
Funds List
This API call return array of funds available at Twelve Data API. This list is daily updated.
HTTP request example
https://api.twelvedata.com/funds
This request will return JSON with the following structure
{
"result": {
"count": 84799,
"list": [
{
"symbol": "DIVI",
"name": "AdvisorShares Athena High Dividend ETF",
"country": "United States",
"currency": "USD",
"exchange": "NYSE",
"type": "ETF",
"figi_code": "BBG00161BCW4"
},
{
"symbol": "GBTC",
"name": "Grayscale Bitcoin Trust (BTC)",
"country": "United States",
"currency": "USD",
"exchange": "NYSE",
"type": "ETF",
"figi_code": "BBG00D0YL155"
}
{...}
],
},
"status": "ok"
}
// with &show_plan=true
{
"result": {
"count": 84799,
"list": [
{
"symbol": "DIVI",
"name": "AdvisorShares Athena High Dividend ETF",
"country": "United States",
"currency": "USD",
"exchange": "NYSE",
"type": "ETF",
"figi_code": "BBG00161BCW4"
"access": {
"global": "Level A",
"plan": "Grow"
}
},
{
"symbol": "GBTC",
"name": "Grayscale Bitcoin Trust (BTC)",
"country": "United States",
"currency": "USD",
"exchange": "NYSE",
"type": "ETF",
"figi_code": "BBG00D0YL155"
"access": {
"global": "Level A",
"plan": "Grow"
}
},
{...}
]
},
"status": "ok"
}
HTTP route
API credits
1 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Parameter is optional • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| exchange | • Parameter is optional • Filter by exchange name or mic code |
| country | • Parameter is optional • Filter by country name or alpha code |
| type | • The asset class to which the instrument belongs • Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant |
| 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
|
| page | • Parameter is optional • Page number; default 1
|
| outputsize | • Parameter is optional • Number of records in response; default 5000
|
Response
| Key | Description |
|---|---|
| count | total number of matching instruments |
| 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 |
| type | group to which instrument belongs to |
| figi_code | financial instrument global identifier (FIGI) |
JSON request example
https://api.twelvedata.com/funds
https://api.twelvedata.com/funds?symbol=0P00000AMH
Downloadable CSV example
https://api.twelvedata.com/funds?format=CSV
Bonds List
This API call return array of bonds available at Twelve Data API. This list is daily updated.
HTTP request example
https://api.twelvedata.com/bonds
This request will return JSON with the following structure
{
"result": {
"count": 84799,
"list": [
{
"symbol": "0P00000AMG",
"name": "Morgan Stanley Investment Funds - Sustainable Asia Equity Fund B",
"country": "United States",
"currency": "USD",
"exchange": "OTC",
"type": "Mutual Fund"
},
{
"symbol": "0P00000AMH",
"name": "Morgan Stanley Investment Funds - Sustainable Emerging Markets Equity Fund B",
"country": "United States",
"currency": "USD",
"exchange": "OTC",
"type": "Mutual Fund"
},
{...}
],
"status": "ok"
}
}
// with &show_plan=true
{
"result": {
"count": 100,
"list": [
{
"symbol": "AJXA",
"name": "Great Ajax Corp",
"country": "United States",
"currency": "USD",
"exchange": "NYSE",
"type": "Exchange-Traded Note",
"access": {
"global": "Basic",
"plan": "Basic"
}
},
{
"symbol": "AMJL",
"name": "X-Links Monthly Pay 2xLeveraged Alerian MLP Index ETN",
"country": "United States",
"currency": "USD",
"exchange": "NYSE",
"type": "Exchange-Traded Note",
"access": {
"global": "Basic",
"plan": "Basic"
}
},
{...}
]
},
"status": "ok"
}
HTTP route
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 |
| country | • Parameter is optional • Filter by country name or alpha code |
| type | • The asset class to which the instrument belongs • Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant |
| 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
|
| page | • Parameter is optional • Page number; default 1
|
| outputsize | • Parameter is optional • Number of records in response; default 5000
|
Response
| Key | Description |
|---|---|
| count | total number of matching instruments |
| 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 |
| type | group to which instrument belongs to |
JSON request example
https://api.twelvedata.com/bonds
https://api.twelvedata.com/bonds?symbol=AJXA
Downloadable CSV example
https://api.twelvedata.com/bonds?format=CSV
ETFs 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/etfs
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",
"figi_code": "BBG000BDTF76"
},
{
"symbol": "VTI",
"name": "Vanguard Total Stock Market Index Fund ETF Shares",
"currency": "USD",
"exchange": "NYSE",
"mic_code": "XNYS",
"country": "Unites States",
"figi_code": "BBG000HRBDF4"
},
{...}
]
// with &show_plan=true
{
"data": [
{
"symbol": "SPY",
"name": "SPDR S&P 500 ETF Trust",
"currency": "MXN",
"exchange": "BMV",
"mic_code": "XMEX",
"country": "Mexico",
"figi_code": ""
"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",
"figi_code": "BBG000BDTF76",
"access": {
"global": "Basic",
"plan": "Basic"
}
},
{...}
],
"status": "ok"
}
HTTP route
API credits
1 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Parameter is optional • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| figi_code | financial instrument global identifier (FIGI) |
JSON request example
https://api.twelvedata.com/etfs
https://api.twelvedata.com/etfs?symbol=QQQ
Downloadable CSV example
https://api.twelvedata.com/etfs?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": "QBNK",
"name": "QE Banks and Financial Services",
"country": "Qatar",
"currency": "QAR"
"exchange": "QE",
"mic_code": "DSMD",
},
{
"symbol": "HSI",
"name": "HANG SENG INDEX",
"country": "Hong Kong",
"currency": "HKD"
"exchange": "HKEX",
"mic_code": "XHKG",
},
{...}
]
// 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
API credits
1 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Parameter is optional • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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=QBNK
Downloadable CSV example
https://api.twelvedata.com/indices?format=CSV
Commodities List
This API call return array of commodity pairs available at Twelve Data API. This list is daily updated.
HTTP request example
https://api.twelvedata.com/commodities
This request will return JSON with the following structure
[
{
"symbol": "XAG/AUD",
"name": "Silver Spot",
"category": "Precious Metal",
"description": ""
},
{
"symbol": "XAG/CAD",
"name": "Silver Spot",
"category": "Precious Metal",
"description": ""
},
{...}
]
HTTP route
API credits
1 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Parameter is optional • Filter by symbol |
| category | • Parameter is optional • Filter by category of commodity |
| 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 |
| name | full name of the instrument |
| category | category of commodity |
| description | short description of the commodity |
JSON request example
https://api.twelvedata.com/commodities
https://api.twelvedata.com/commodities?symbol=XAU/USD
Downloadable CSV example
https://api.twelvedata.com/commodities?format=CSV
Cross listings
This API call return array of cross listed symbols. This list is daily updated.
HTTP request example
https://api.twelvedata.com/cross_listings?symbol=NVDA&mic_code=XNGS&apikey=your_api_key
This request will return JSON with the following structure
{
"result": {
"count": 7,
"list": [
{
"symbol": "NVDA",
"name": "NVIDIA Corp",
"exchange": "NASDAQ",
"mic_code": "XNGS",
},
{
"symbol": "0R1I",
"name": "NVIDIA Corp",
"exchange": "LSE",
"mic_code": "XLON",
}
]
}
}
HTTP route
API credits
40 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | ticker symbol of instrument |
| exchange | • Parameter is optional • exchange where instrument is traded |
| mic_code | • Parameter is optional • market identifier code (MIC) under ISO 10383 standard |
| country | • Parameter is optional • country to which stock exchange belongs to |
Response
| Key | Description |
|---|---|
| symbol | ticker symbol of instrument |
| name | name of exchange |
| exchange | exchange where instrument is traded |
| mic_code | market identifier code (MIC) under ISO 10383 standard |
JSON request example
https://api.twelvedata.com/cross_listings?symbol=NVDA&mic_code=XNGS&apikey=your_api_key
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
API credits
1 per request
API parameters
| Parameter | Details |
|---|---|
| type | • The asset class to which the instrument belongs • Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant |
| 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
Exchange schedule
This API call return exchanges details and trading hours.
HTTP request example
https://api.twelvedata.com/exchange_schedule?apikey=your_api_key
This request will return JSON with the following structure
{
"data": [
{
"title": "NASDAQ/NGS (Global Select Market)",
"name": "NASDAQ",
"code": "XNYS",
"country": "United states",
"time_zone": "America/New_York",
"sessions": [
{"open_time": "04:00:00", "close_time": "09:30:00", "session_name": "Pre market", "session_type": "pre"},
{"open_time": "09:30:00", "close_time": "16:00:00", "session_name": "Market", "session_type": "quotes"},
{"open_time": "16:00:00", "close_time": "20:00:00", "session_name": "Post market", "session_type": "post"}
]
},
{...}
]
}
HTTP route
API credits
100 per request
API parameters
| Parameter | Details |
|---|---|
| date | • Parameter is optional • If present, return schedule for the selected date, else - common schedule. Could be the exact date, e.g. 2021-10-27, or in human language today or yesterday. |
| mic_name | • Parameter is optional • Filter by exchange name |
| 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 |
Response
| Key | Description |
|---|---|
| title | official name of exchange |
| 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 |
| sessions | exchange trading hours |
JSON request example
https://api.twelvedata.com/exchange_schedule?apikey=your_api_key
https://api.twelvedata.com/exchange_schedule?date=today&apikey=your_api_key
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
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
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
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
Instrument Type
Returns a list of instrument types
HTTP request example
https://api.twelvedata.com/instrument_type?apikey=your_api_key
This request will return JSON with the following structure
{
"result": [
"Agricultural Product",
"American Depositary Receipt",
"Bond",
"Bond Fund",
"Closed-end Fund",
"Common Stock",
"Depositary Receipt",
"Digital Currency",
"Energy Resource",
"ETF",
"Exchange-Traded Note",
"Global Depositary Receipt",
"Index",
"Industrial Metal",
"Limited Partnership",
"Livestock",
"Mutual Fund",
"Physical Currency",
"Precious Metal",
"Preferred Stock",
"REIT",
"Right",
"Structured Product",
"Trust",
"Unit",
"Warrant"
],
"status": "ok"
}
HTTP route
API credits
1 per request
JSON request example
https://api.twelvedata.com/instrument_type?apikey=your_api_key
Countries
Returns a list of countries
HTTP request example
https://api.twelvedata.com/countries?apikey=your_api_key
This request will return JSON with the following structure
{
"data": [
{
"iso2": "AF",
"iso3": "AFG",
"numeric": 4,
"name": "Afghanistan",
"official_name": "The Islamic Republic of Afghanistan",
"capital": "Kabul",
"currency": "AFN"
},
{
"iso2": "AX",
"iso3": "ALA",
"numeric": 248,
"name": "Åland Islands",
"official_name": "Åland",
"capital": "Mariehamn",
"currency": "EUR"
},
{
"iso2": "AL",
"iso3": "ALB",
"numeric": 8,
"name": "Albania",
"official_name": "The Republic of Albania",
"capital": "Tirana",
"currency": "ALL"
}
]
}
HTTP route
API credits
1 per request
Response
| Key | Description |
|---|---|
| iso2 | two-letter country code defined in ISO 3166 |
| iso3 | three-letter country code defined in ISO 3166 |
| numeric | numeric country code defined in ISO 3166 |
| name | the full name of country |
| official_name | official name of country |
| capital | capital of country |
| currency | currency of country |
JSON request example
https://api.twelvedata.com/countries?apikey=your_api_key
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
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 pointsmin_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 levellower_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
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
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, ... |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| timezone | string | • Parameter is optional
• Timezone at which output datetime will be displayed • Supports: ◦ Exchange for local exchange time
◦ UTC for datetime at universal UTC standard
◦ Timezone name according to the IANA Time Zone Database. E.g. America/New_York, Asia/Singapore. Full list of timezones can be found here ↗.
Take note that the IANA Timezone name is case-sensitive • Type string; Default Exchange
|
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
Symbol SearchHigh Demand
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
API credits
1 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Symbol to search |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
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
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, ... |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 • The asset class to which the instrument belongs • Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant |
| 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
|
| dp | string | • Parameter is optional
• Specifies the number of decimal places for floating values • Should be in range [0,11] inclusive • Type int; Default 5
|
| order | string | • Parameter is optional
• Sorting order of the output • Supports ASC, DESC; Default DESC
|
| timezone | string | • Parameter is optional
• Timezone at which output datetime will be displayed • Supports: ◦ Exchange for local exchange time
◦ UTC for datetime at universal UTC standard
◦ Timezone name according to the IANA Time Zone Database. E.g. America/New_York, Asia/Singapore. Full list of timezones can be found here ↗.
Take note that the IANA Timezone name is case-sensitive • Type string; Default Exchange
|
| date | string | • Parameter is optional
• Specifies the exact date to get the data for • Could be the exact date, e.g. 2021-10-27, or in human language today or yesterday
|
|
start_date
end_date |
string | • Parameters are optional
• Can be used separately and together • Format 2006-01-02 or 2006-01-02 15:04:05
◦ Forex and Cryptocurrencies - UTC
◦ Stocks - where exchange is located (e.g. for AAPL it will be America/New_York)
• Both parameters take into account if timezone parameter is provided.
If timezone is given then, start_date and end_date will be used in the specified location
|
| previous_close | string | • Parameter is optional
• If true, adds previous bar close price value to the current object
• Only applicable to /time_series endpoint
• Type bool; Default false
|
| adjust | string | • Parameter is optional
• Adjusting mode for prices • Supports all, splits, dividends, none • Default is splits |
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
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 |
| dp | string | • Parameter is optional
• Specifies the number of decimal places for floating values • Should be in range [0,11] inclusive • Type int; Default 5
|
| timezone | string | • Parameter is optional
• Timezone at which output datetime will be displayed • Supports: ◦ Exchange for local exchange time
◦ UTC for datetime at universal UTC standard
◦ Timezone name according to the IANA Time Zone Database. E.g. America/New_York, Asia/Singapore. Full list of timezones can be found here ↗.
Take note that the IANA Timezone name is case-sensitive • Type string; Default Exchange
|
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
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 |
| dp | string | • Parameter is optional
• Specifies the number of decimal places for floating values • Should be in range [0,11] inclusive • Type int; Default 5
|
| timezone | string | • Parameter is optional
• Timezone at which output datetime will be displayed • Supports: ◦ Exchange for local exchange time
◦ UTC for datetime at universal UTC standard
◦ Timezone name according to the IANA Time Zone Database. E.g. America/New_York, Asia/Singapore. Full list of timezones can be found here ↗.
Take note that the IANA Timezone name is case-sensitive • Type string; Default Exchange
|
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
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, ... |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 • The asset class to which the instrument belongs • Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant |
| 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]. |
| dp | string | • Parameter is optional
• Specifies the number of decimal places for floating values • Should be in range [0,11] inclusive • Type int; Default 5
|
| timezone | string | • Parameter is optional
• Timezone at which output datetime will be displayed • Supports: ◦ Exchange for local exchange time
◦ UTC for datetime at universal UTC standard
◦ Timezone name according to the IANA Time Zone Database. E.g. America/New_York, Asia/Singapore. Full list of timezones can be found here ↗.
Take note that the IANA Timezone name is case-sensitive • Type string; Default Exchange
|
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=QBNK&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
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, ... |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 • The asset class to which the instrument belongs • Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant |
| 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
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, ... |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 • The asset class to which the instrument belongs • Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant |
| date | string | • Parameter is optional • If not null, then return data from a specific date • Format 2006-01-02 |
| 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
|
| price_greater_than | string | Parameter is optional • Takes values with price grater than specified value |
| 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,
"exchange": "NASDAQ",
"mic_code": "XNAS"
},
{
"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,
"exchange": "TSX",
"mic_code": "XTSE"
},
{
"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,
"exchange": "BSE",
"mic_code": "XBOM"
},
{...}
]
},
"status": "ok"
}
HTTP route
API credits
1 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Parameter is optional • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| exchange | exchange name where the fund is listed |
| mic_code | market identifier code (MIC) under ISO 10383 standard |
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
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
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
API credits
1000 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Symbol ticker of mutual fund |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
API credits
200 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Symbol ticker of mutual fund |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
API credits
200 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Symbol ticker of mutual fund |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
API credits
1000 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Symbol ticker of mutual fund |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
ETFs
ETFs ListUseful
This API request returns a list of exchange traded 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/etfs/list?apikey=your_api_key
This request will return JSON with the following structure
{
"result": {
"count": 1000,
"list": [
{
"symbol": "IVV",
"name": "iShares Core S&P 500 ETF",
"country": "United States",
"mic_code": "XNAS",
"fund_family": "iShares",
"fund_type": "Large Blend",
},
{...}
]
},
"status": "ok"
}
HTTP route
API credits
1 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Parameter is optional • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| page | • Parameter is optional • Page number; default 1
|
| outputsize | • Parameter is optional • Number of records in response; default 50
|
| 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 |
| mic_code | market identifier code (MIC) under ISO 10383 standard |
| fund_family | investment company that manages the fund |
| fund_type | type of fund |
JSON request example
https://api.twelvedata.com/etfs/list?apikey=demo
https://api.twelvedata.com/etfs/list?fund_family=Vanguard&apikey=demo
Downloadable CSV example
https://api.twelvedata.com/etfs/list?format=CSV&apikey=demo
ETFs Family List
This API request returns a list of exchange traded funds families.
HTTP request example
https://api.twelvedata.com/etfs/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
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/etfs/family?apikey=demo
https://api.twelvedata.com/etfs/family?country=US&apikey=demo
Downloadable CSV example
https://api.twelvedata.com/etfs/family?format=CSV&apikey=demo
ETFs Type List
This API request returns a list of exchange traded funds types.
HTTP request example
https://api.twelvedata.com/etfs/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
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/etfs/type?apikey=demo
https://api.twelvedata.com/etfs/type?country=US&apikey=demo
Downloadable CSV example
https://api.twelvedata.com/etfs/type?format=CSV&apikey=demo
All dataHigh Demand
This API request returns a complete breakdown of a etf, including summary, performance, risk and composition.
HTTP request example
https://api.twelvedata.com/etfs/world?symbol=IVV&apikey=your_api_key
This request will return JSON with the following structure
{
"etf": {
"summary": {
"symbol": "IVV",
"name": "iShares Core S&P 500 ETF",
"fund_family": "iShares",
"fund_type": "Large Blend",
"currency": "USD",
"share_class_inception_date": "2000-11-13",
"ytd_return": -0.0537,
"expense_ratio_net": -0.004,
"yield": 0.0133,
"nav": 413.24,
"last_price": 413.24,
"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."
},
"performance": {
"trailing_returns": [
{
"period": "ytd",
"share_class_return": -0.0751,
"category_return": 0.1484
}
],
"annual_total_returns": [
{
"year": "2021",
"share_class_return": 0.2866,
"category_return": null
}
]
},
"risk": {
"volatility_measures": [
{
"period": "3_year",
"alpha": -0.03,
"alpha_category": -0.02,
"beta": 1,
"beta_category": 0.01,
"mean_annual_return": 1.58,
"mean_annual_return_category": 0.01,
"r_squared": 100,
"r_squared_category": 0.95,
"std": 18.52,
"std_category": 0.19,
"sharpe_ratio": 0.95,
"sharpe_ratio_category": 0.01,
"treynor_ratio": 17.41,
"treynor_ratio_category": 0.16
}
],
"valuation_metrics": {
"price_to_earnings": 26.46,
"price_to_book": 4.42,
"price_to_sales": 2.96,
"price_to_cashflow": 17.57
}
},
"composition": {
"major_market_sectors": [
{
"sector": "Technology",
"weight": 0.2424
}
],
"country_allocation": [
{
"country": "United Kingdom",
"allocation": 0.9855
},
{
"country": "India",
"allocation": 0.0045
}
],
"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
}
],
"bond_breakdown": {
"average_maturity": {
"fund": 6.65,
"category": 7.81
},
"average_duration": {
"fund": 5.72,
"category": 5.64
},
"credit_quality": [
{
"grade": "AAA",
"weight": 0
}
]
}
}
},
"status": "ok"
}
HTTP route
API credits
800 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Symbol ticker of etf |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 etf 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 |
| last_price | last price of the fund |
| min_investment | investment minimum |
| turnover_rate | percentage rate at which etf 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 |
| 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 |
| 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 |
| major_market_sectors.sector | sector category of a fund exposure |
| major_market_sectors.weight | weight (%) of a fund exposure in a sector |
| country_allocation.country | country name |
| country_allocation.allocation | percentages of a fund's net assets distributed to securities of the country |
| 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/etfs/world?symbol=QQQ&apikey=demo
Summary
This API request returns a brief summary of a etf.
HTTP request example
https://api.twelvedata.com/etfs/world/summary?symbol=IVV&apikey=your_api_key
This request will return JSON with the following structure
{
"etf": {
"summary": {
"symbol": "IVV",
"name": "iShares Core S&P 500 ETF",
"fund_family": "iShares",
"fund_type": "Large Blend",
"currency": "USD",
"share_class_inception_date": "2000-11-13",
"ytd_return": -0.0537,
"expense_ratio_net": -0.004,
"yield": 0.0133,
"nav": 413.24,
"last_price": 413.24,
"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."
}
},
"status": "ok"
}
HTTP route
API credits
200 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Symbol ticker of etf |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 etf 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 |
| last_price | last price of the fund |
| min_investment | investment minimum |
| turnover_rate | percentage rate at which etf 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/etfs/world/summary?symbol=QQQ&apikey=demo
PerformanceHigh Demand
This API request returns detailed performance of a etf, including trailing and annual returns.
HTTP request example
https://api.twelvedata.com/etfs/world/performance?symbol=IVV&apikey=your_api_key
This request will return JSON with the following structure
{
"etf": {
"performance": {
"performance": {
"trailing_returns": [
{
"period": "ytd",
"share_class_return": -0.0751,
"category_return": 0.1484
}
],
"annual_total_returns": [
{
"year": "2021",
"share_class_return": 0.2866,
"category_return": null
}
]
}
}
},
"status": "ok"
}
HTTP route
API credits
200 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Symbol ticker of etf |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| 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 |
JSON request example
https://api.twelvedata.com/etfs/world/performance?symbol=QQQ&apikey=demo
Risk
This API request returns core metrics to measure the risk of investing in a etf.
HTTP request example
https://api.twelvedata.com/etfs/world/risk?symbol=IVV&apikey=your_api_key
This request will return JSON with the following structure
{
"etf": {
"risk": {
"volatility_measures": [
{
"period": "3_year",
"alpha": -0.03,
"alpha_category": -0.02,
"beta": 1,
"beta_category": 0.01,
"mean_annual_return": 1.58,
"mean_annual_return_category": 0.01,
"r_squared": 100,
"r_squared_category": 0.95,
"std": 18.52,
"std_category": 0.19,
"sharpe_ratio": 0.95,
"sharpe_ratio_category": 0.01,
"treynor_ratio": 17.41,
"treynor_ratio_category": 0.16
}
],
"valuation_metrics": {
"price_to_earnings": 26.46,
"price_to_book": 4.42,
"price_to_sales": 2.96,
"price_to_cashflow": 17.57
}
}
},
"status": "ok"
}
HTTP route
API credits
200 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Symbol ticker of etf |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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/etfs/world/risk?symbol=QQQ&apikey=demo
CompositionHigh Demand
This API request returns portfolio composition of a etf, including sectors, holding details, weighted exposure, and others.
HTTP request example
https://api.twelvedata.com/etfs/world/composition?symbol=IVV&apikey=your_api_key
This request will return JSON with the following structure
{
"etf": {
"composition": {
"major_market_sectors": [
{
"sector": "Technology",
"weight": 0.2424
}
],
"country_allocation": [
{
"country": "United Kingdom",
"allocation": 0.9855
},
{
"country": "India",
"allocation": 0.0045
}
],
"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
}
],
"bond_breakdown": {
"average_maturity": {
"fund": 6.65,
"category": 7.81
},
"average_duration": {
"fund": 5.72,
"category": 5.64
},
"credit_quality": [
{
"grade": "AAA",
"weight": 0
}
]
}
}
},
"status": "ok"
}
HTTP route
API credits
200 per request
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Symbol ticker of etf |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| country_allocation.country | country name |
| country_allocation.allocation | percentages of a fund's net assets distributed to securities of the country |
| 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/etfs/world/composition?symbol=QQQ&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.
Logo
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
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",
"address2": "Cupertino, CA 95014",
"city": "Cupertino",
"zip": "95014",
"state": "CA",
"country": "US",
"phone": "408-996-1010"
}
HTTP route
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| address2 | string | Secondary 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": [
{
"ex_date": "2021-08-06",
"amount": 0.22
}
]
}
HTTP route
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 optionallast - the last dividend - default1m - one month3m - three months6m - six monthsytd - year-to-date1y - one year2y - two years5y - 5 yearsfull - 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 |
|---|---|---|
| ex_date | string | Stands for the ex date |
| amount | number | Stands for the payment amount |
JSON request example
https://api.twelvedata.com/dividends?symbol=AAPL&apikey=demo
Dividends calendar
This API method returns dividend data as a calendar for a given date range. To call custom period, use start_date and end_date parameters.
HTTP request example
https://api.twelvedata.com/dividends_calendar?apikey=your_api_key
This request will return JSON with the following structure
[
{
"symbol": "MSFT",
"mic_code": "XNGS",
"exchange": "NASDAQ",
"amount": 0.75,
"ex_date": "2024-02-14"
},
{
"symbol": "AAPL",
"mic_code": "XNGS",
"exchange": "NASDAQ",
"amount": 0.24,
"ex_date": "2024-02-09"
},
{
"symbol": "MSFT",
"mic_code": "XNGS",
"exchange": "NASDAQ",
"amount": 0.75,
"ex_date": "2023-11-15"
},
{
"symbol": "AAPL",
"mic_code": "XNGS",
"exchange": "NASDAQ",
"amount": 0.24,
"ex_date": "2023-11-10"
},
]
HTTP route
API credits
40 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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
|
| outputsize | number | • Parameter is optional • Number of data points to retrieve • Supports values in the range from 1 to 500• Default 100 when no date parameters are set, otherwise set to maximum |
| page | string | • Parameter is optional • Page number; default 1
|
| 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 |
| mic_code | string | Market Identifier Code (MIC) under ISO 10383 standard |
| exchange | string | Exchange name where the company is listed |
| ex_date | string | Stands for the ex date |
| amount | number | Stands for the payment amount |
JSON request example
https://api.twelvedata.com/dividends_calendar?apikey=your_api_key
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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 optionallast - the last split - default1m - one month3m - three months6m - six monthsytd - year-to-date1y - one year2y - two years5y - 5 yearsfull - 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
Splits calendar
This API method returns split data as a calendar for a given date range. To call custom period, use start_date and end_date parameters.
HTTP request example
https://api.twelvedata.com/splits_calendar?apikey=your_api_key
This request will return JSON with the following structure
[
{
"date": "2024-04-23",
"symbol": "AAPL",
"mic_code": "XNGS",
"exchange": "NASDAQ",
"description": "1-for-1 split",
"ratio": 1,
"from_factor": 1,
"to_factor": 1
},
{
"date": "2024-02-23",
"symbol": "LYT",
"mic_code": "XNCM",
"exchange": "NASDAQ",
"description": "1-for-60 split",
"ratio": 60,
"from_factor": 1,
"to_factor": 60
},
{
"date": "2024-02-21",
"symbol": "HAUS",
"mic_code": "BATS",
"exchange": "CBOE",
"description": "1-for-10 split",
"ratio": 10,
"from_factor": 1,
"to_factor": 10
},
{
"date": "2024-02-21",
"symbol": "TRBA",
"mic_code": "XSTU",
"exchange": "XSTU",
"description": "1-for-5 split",
"ratio": 5,
"from_factor": 1,
"to_factor": 5
}
]
HTTP route
API credits
40 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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
|
| outputsize | number | • Parameter is optional • Number of data points to retrieve • Supports values in the range from 1 to 500• Default 100 when no date parameters are set, otherwise set to maximum |
| page | string | • Parameter is optional • Page number; default 1
|
| 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 |
| symbol | string | Ticker of the company |
| mic_code | string | Market Identifier Code (MIC) under ISO 10383 standard |
| exchange | string | Exchange name where the company is listed |
| 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_calendar?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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 • The asset class to which the instrument belongs • Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant |
| 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 |
| dp | string | • Parameter is optional
• Specifies the number of decimal places for floating values • Should be in range [0,11] inclusive • Type int; Default 2
|
|
start_date
end_date |
string | • Parameters are optional
• Can be used separately and together • Format 2006-01-02 or 2006-01-02 15:04:05
|
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
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 |
| dp | string | • Parameter is optional
• Specifies the number of decimal places for floating values • Should be in range [0,11] inclusive • Type int; Default 2
|
|
start_date
end_date |
string | • Parameters are optional
• Can be used separately and together • Format 2006-01-02 or 2006-01-02 15:04:05
|
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
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",
"gross_margin": 46.57807
"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_90_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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| gross_margin | number | The portion of a company's revenue left over after direct costs are subtracted |
| 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_90_volume | number | Refers to the average 90 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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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,
"year": 2022,
"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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 | number | Fiscal quarter. Visible when &period=quarterly
|
| year | number | Fiscal year. 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
Income Statement Consolidated
Returns consolidated income statement of a company and expenses during a period (annual or quarter).
HTTP request example
https://api.twelvedata.com/income_statement/consolidated?symbol=AAPL&apikey=your_api_key
This request will return JSON with the following structure
{
"income_statement": [
{
"fiscal_date": "2023-09-30",
"revenue": {
"total_revenue": 383285000000,
"operating_revenue": 383285000000
},
"gross_profit": {
"gross_profit_value": 169148000000,
"cost_of_revenue": {
"cost_of_revenue_value": 214137000000,
"excise_taxes": 214137000000,
"reconciled_cost_of_revenue": 214137000000
}
},
"operating_income": {
"operating_income_value": 114301000000,
"total_operating_income_as_reported": 114301000000,
"operating_expense": 54847000000,
"other_operating_expenses": 114301000000,
"total_expenses": 268984000000
},
"net_income": {
"net_income_value": 96995000000,
"net_income_common_stockholders": 96995000000,
"net_income_including_noncontrolling_interests": 96995000000,
"net_income_from_tax_loss_carryforward": 96995000000,
"net_income_extraordinary": 96995000000,
"net_income_discontinuous_operations": 96995000000,
"net_income_continuous_operations": 96995000000,
"net_income_from_continuing_operation_net_minority_interest": 96995000000,
"net_income_from_continuing_and_discontinued_operation": 96995000000,
"normalized_income": 96995000000,
"minority_interests": 96995000000
},
"earnings_per_share": {
"diluted_eps": 6.13,
"basic_eps": 6.16,
"continuing_and_discontinued_diluted_eps": 6.16,
"continuing_and_discontinued_basic_eps": 6.16,
"normalized_diluted_eps": 6.16,
"normalized_basic_eps": 6.16,
"reported_normalized_diluted_eps": 6.16,
"reported_normalized_basic_eps": 6.16,
"diluted_eps_other_gains_losses": 6.16,
"tax_loss_carryforward_diluted_eps": 6.16,
"diluted_accounting_change": 6.16,
"diluted_extraordinary": 6.16,
"diluted_discontinuous_operations": 6.16,
"diluted_continuous_operations": 6.16,
"basic_eps_other_gains_losses": 6.16,
"tax_loss_carryforward_basic_eps": 6.16,
"basic_accounting_change": 6.16,
"basic_extraordinary": 6.16,
"basic_discontinuous_operations": 6.16,
"basic_continuous_operations": 6.16,
"diluted_ni_avail_to_common_stockholders": 96995000000,
"average_dilution_earnings": 96995000000
},
"expenses": {
"total_expenses": 268984000000,
"selling_general_and_administration_expense": 24932000000,
"selling_and_marketing_expense": 24932000000,
"general_and_administrative_expense": 24932000000,
"other_general_and_administrative_expense": 24932000000,
"depreciation_amortization_depletion_income_statement": 29915000000,
"research_and_development_expense": 29915000000,
"insurance_and_claims_expense": 29915000000,
"rent_and_landing_fees": 29915000000,
"salaries_and_wages_expense": 29915000000,
"rent_expense_supplemental": 29915000000,
"provision_for_doubtful_accounts": 29915000000
},
"interest_income_and_expense": {
"interest_income": 3750000000,
"interest_expense": 3933000000,
"net_interest_income": -183000000,
"net_non_operating_interest_income_expense": -183000000,
"interest_expense_non_operating": 3933000000,
"interest_income_non_operating": 3750000000
},
"other_income_and_expenses": {
"other_income_expense": -382000000,
"other_non_operating_income_expenses": -382000000,
"special_income_charges": 382000000,
"gain_on_sale_of_ppe": 382000000,
"gain_on_sale_of_business": 382000000,
"gain_on_sale_of_security": 382000000,
"other_special_charges": 382000000,
"write_off": 382000000,
"impairment_of_capital_assets": 382000000,
"restructuring_and_merger_acquisition": 382000000,
"securities_amortization": 382000000,
"earnings_from_equity_interest": 382000000,
"earnings_from_equity_interest_net_of_tax": 382000000,
"total_other_finance_cost": 382000000
},
"taxes": {
"tax_provision": 16741000000,
"tax_effect_of_unusual_items": 0,
"tax_rate_for_calculations": 0.147,
"other_taxes": 0
},
"depreciation_and_amortization": {
"depreciation_amortization_depletion": 129188000000,
"amortization_of_intangibles": 129188000000,
"depreciation": 129188000000,
"amortization": 129188000000,
"depletion": 129188000000,
"depreciation_and_amortization_in_income_statement": 129188000000
},
"ebitda": {
"ebitda_value": 129188000000,
"normalized_ebitda_value": 129188000000,
"ebit_value": 117669000000
},
"dividends_and_shares": {
"dividend_per_share": 15812547000,
"diluted_average_shares": 15812547000,
"basic_average_shares": 15744231000,
"preferred_stock_dividends": 15744231000,
"other_under_preferred_stock_dividend": 15744231000
},
"unusual_items": {
"total_unusual_items": 11519000000,
"total_unusual_items_excluding_goodwill": 11519000000
},
"depreciation": {
"reconciled_depreciation": 11519000000
},
"pretax_income": {
"pretax_income_value": 113736000000
},
"special_income_charges": {
"special_income_charges_value": 113736000000
}
}
],
"status": "ok"
}
HTTP route
/income_statement/consolidated
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
Click to expand
|
JSON request example
https://api.twelvedata.com/income_statement/consolidated?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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
Balance Sheet consolidated
Returns consolidated balance sheet of a company showing the summary of assets, liabilities, and shareholders.
HTTP request example
https://api.twelvedata.com/balance_sheet/consolidated?symbol=AAPL&apikey=your_api_key
This request will return JSON with the following structure
{
"balance_sheet": [
{
"fiscal_date": "2023-09-30",
"assets": {
"total_assets": 352583000000,
"current_assets": {
"total_current_assets": 143566000000,
"cash_cash_equivalents_and_short_term_investments": 61555000000,
"cash_and_cash_equivalents": 29965000000,
"cash_equivalents": 1606000000,
"cash_financial": 28359000000,
"other_short_term_investments": 31590000000,
"restricted_cash": 31590000000,
"receivables": {
"total_receivables": 60985000000,
"accounts_receivable": 29508000000,
"gross_accounts_receivable": 29508000000,
"allowance_for_doubtful_accounts_receivable": 29508000000,
"receivables_adjustments_allowances": 29508000000,
"other_receivables": 31477000000,
"due_from_related_parties_current": 31477000000,
"taxes_receivable": 31477000000,
"accrued_interest_receivable": 31477000000,
"notes_receivable": 31477000000,
"loans_receivable": 31477000000
},
"inventory": {
"total_inventory": 6331000000,
"inventories_adjustments_allowances": 6331000000,
"other_inventories": 6331000000,
"finished_goods": 6331000000,
"work_in_process": 6331000000,
"raw_materials": 6331000000
},
"prepaid_assets": 14695000000,
"current_deferred_assets": 14695000000,
"current_deferred_taxes_assets": 14695000000,
"assets_held_for_sale_current": 14695000000,
"hedging_assets_current": 14695000000,
"other_current_assets": 14695000000
},
"non_current_assets": {
"total_non_current_assets": 209017000000,
"financial_assets": 209017000000,
"investments_and_advances": 100544000000,
"other_investments": 100544000000,
"investment_in_financial_assets": 100544000000,
"held_to_maturity_securities": 100544000000,
"available_for_sale_securities": 100544000000,
"financial_assets_designated_as_fair_value_through_profit_or_loss_total": 100544000000,
"trading_securities": 100544000000,
"long_term_equity_investment": 100544000000,
"investments_in_joint_ventures_at_cost": 100544000000,
"investments_in_other_ventures_under_equity_method": 100544000000,
"investments_in_associates_at_cost": 100544000000,
"investments_in_subsidiaries_at_cost": 100544000000,
"investment_properties": 100544000000,
"goodwill_and_other_intangible_assets": {
"goodwill": 100544000000,
"other_intangible_assets": 100544000000,
"total_goodwill_and_intangible_assets": 100544000000
},
"net_ppe": 54376000000,
"gross_ppe": 125260000000,
"accumulated_depreciation": -70884000000,
"leases": 12839000000,
"construction_in_progress": 12839000000,
"other_properties": 10661000000,
"machinery_furniture_equipment": 78314000000,
"buildings_and_improvements": 12839000000,
"land_and_improvements": 23446000000,
"properties": 0,
"non_current_accounts_receivable": 12839000000,
"non_current_note_receivables": 12839000000,
"due_from_related_parties_non_current": 12839000000,
"non_current_prepaid_assets": 12839000000,
"non_current_deferred_assets": 17852000000,
"non_current_deferred_taxes_assets": 17852000000,
"defined_pension_benefit": 12839000000,
"other_non_current_assets": 36245000000
},
"liabilities": {
"total_liabilities_net_minority_interest": 290437000000,
"current_liabilities": {
"total_current_liabilities": 145308000000,
"current_debt_and_capital_lease_obligation": 17382000000,
"current_debt": 15807000000,
"current_capital_lease_obligation": 1575000000,
"other_current_borrowings": 9822000000,
"line_of_credit": 9822000000,
"commercial_paper": 5985000000,
"current_notes_payable": 9822000000,
"current_provisions": 9822000000,
"payables_and_accrued_expenses": {
"total_payables_and_accrued_expenses": 71430000000,
"accounts_payable": 62611000000,
"current_accrued_expenses": 9822000000,
"interest_payable": 9822000000,
"payables": 71430000000,
"other_payable": 9822000000,
"due_to_related_parties_current": 9822000000,
"dividends_payable": 9822000000,
"total_tax_payable": 8819000000,
"income_tax_payable": 8819000000
},
"pension_and_other_post_retirement_benefit_plans_current": 8061000000,
"employee_benefits": 8061000000,
"current_deferred_liabilities": 8061000000,
"current_deferred_revenue": 8061000000,
"current_deferred_taxes_liabilities": 8061000000,
"other_current_liabilities": 48435000000,
"liabilities_held_for_sale_non_current": 48435000000
},
"non_current_liabilities": {
"total_non_current_liabilities_net_minority_interest": 145129000000,
"long_term_debt_and_capital_lease_obligation": {
"total_long_term_debt_and_capital_lease_obligation": 106548000000,
"long_term_debt": 95281000000,
"long_term_capital_lease_obligation": 11267000000
},
"long_term_provisions": 15457000000,
"non_current_pension_and_other_postretirement_benefit_plans": 15457000000,
"non_current_accrued_expenses": 15457000000,
"due_to_related_parties_non_current": 15457000000,
"trade_and_other_payables_non_current": 15457000000,
"trade_and_other_payables_non_current": 15457000000,
"non_current_deferred_liabilities": 15457000000,
"non_current_deferred_revenue": 15457000000,
"non_current_deferred_taxes_liabilities": 15457000000,
"other_non_current_liabilities": 23124000000,
"preferred_securities_outside_stock_equity": 15457000000,
"derivative_product_liabilities": 15457000000,
"capital_lease_obligations": 12842000000,
"restricted_common_stock": 12842000000
},
"equity": {
"total_equity_gross_minority_interest": 62146000000,
"stockholders_equity": 62146000000,
"common_stock_equity": 62146000000,
"preferred_stock_equity": 62146000000,
"other_equity_interest": 62146000000,
"minority_interest": 62146000000,
"total_capitalization": 157427000000,
"net_tangible_assets": 62146000000,
"tangible_book_value": 62146000000,
"invested_capital": 173234000000,
"working_capital": -1742000000,
"capital_stock": {
"common_stock": 73812000000,
"preferred_stock": 73812000000,
"total_partnership_capital": 73812000000,
"general_partnership_capital": 73812000000,
"limited_partnership_capital": 73812000000,
"capital_stock": 73812000000,
"other_capital_stock": 73812000000,
"additional_paid_in_capital": 73812000000,
"retained_earnings": -214000000,
"treasury_stock": 73812000000,
"treasury_shares_number": 0,
"ordinary_shares_number": 15550061000,
"preferred_shares_number": 73812000000,
"share_issued": 15550061000
},
"equity_adjustments": {
"gains_losses_not_affecting_retained_earnings": -11452000000,
"other_equity_adjustments": -11452000000,
"fixed_assets_revaluation_reserve": 11452000000,
"foreign_currency_translation_adjustments": 11452000000,
"minimum_pension_liabilities": 11452000000,
"unrealized_gain_loss": 11452000000
},
"net_debt": 81123000000,
"total_debt": 123930000000
}
}
}
}
],
"status": "ok"
}
HTTP route
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
Click to expand
|
JSON request example
https://api.twelvedata.com/balance_sheet/consolidated?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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
Cash Flow consolidated
Returns consolidated 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/consolidated?symbol=AAPL&apikey=your_api_key
This request will return JSON with the following structure
{
"cash_flow": [
{
"fiscal_date": "2023-09-30",
"cash_flow_from_operating_activities": {
"net_income_from_continuing_operations": 96995000000,
"operating_cash_flow": 110543000000,
"cash_flow_from_continuing_operating_activities": 110543000000,
"cash_from_discontinued_operating_activities": 108488000000,
"cash_flow_from_discontinued_operation": 108488000000,
"free_cash_flow": 99584000000,
"cash_flows_from_used_in_operating_activities_direct": 108488000000,
"taxes_refund_paid": 108488000000,
"taxes_refund_paid_direct": 108488000000,
"interest_received": 108488000000,
"interest_received_direct": 108488000000,
"interest_paid": 108488000000,
"interest_paid_direct": 108488000000,
"dividend_received": 108488000000,
"dividend_received_direct": 108488000000,
"dividend_paid": 108488000000,
"dividend_paid_direct": 108488000000,
"change_in_working_capital": -6577000000,
"change_in_other_working_capital": 108488000000,
"change_in_receivables": -417000000,
"changes_in_account_receivables": -1688000000,
"change_in_payables_and_accrued_expense": -1889000000,
"change_in_accrued_expense": 108488000000,
"change_in_payable": -1889000000,
"change_in_dividend_payable": 108488000000,
"change_in_account_payable": -1889000000,
"change_in_tax_payable": 108488000000,
"change_in_income_tax_payable": 108488000000,
"change_in_interest_payable": 108488000000,
"change_in_other_current_liabilities": 3031000000,
"change_in_other_current_assets": -5684000000,
"change_in_inventory": -1618000000,
"change_in_prepaid_assets": 108488000000,
"other_non_cash_items": -2227000000,
"excess_tax_benefit_from_stock_based_compensation": 108488000000,
"stock_based_compensation": 10833000000,
"unrealized_gain_loss_on_investment_securities": 108488000000,
"provision_and_write_off_of_assets": 108488000000,
"asset_impairment_charge": 108488000000,
"amortization_of_securities": 108488000000,
"deferred_tax": 108488000000,
"deferred_income_tax": 108488000000,
"depreciation_amortization_depletion": 11519000000,
"depletion": 108488000000,
"depreciation_and_amortization": 11519000000,
"amortization_cash_flow": 108488000000,
"amortization_of_intangibles": 108488000000,
"depreciation": 108488000000,
"operating_gains_losses": 108488000000,
"pension_and_employee_benefit_expense": 108488000000,
"earnings_losses_from_equity_investments": 108488000000,
"gain_loss_on_investment_securities": 108488000000,
"net_foreign_currency_exchange_gain_loss": 108488000000,
"gain_loss_on_sale_of_ppe": 108488000000,
"gain_loss_on_sale_of_business": 108488000000
},
"cash_flow_from_investing_activities": {
"investing_cash_flow": 3705000000,
"cash_flow_from_continuing_investing_activities": 3705000000,
"cash_from_discontinued_investing_activities": 108488000000,
"net_other_investing_changes": -1337000000,
"interest_received_cfi": 108488000000,
"dividends_received_cfi": 108488000000,
"net_investment_purchase_and_sale": 16001000000,
"sale_of_investment": 45514000000,
"purchase_of_investment": -29513000000,
"net_investment_properties_purchase_and_sale": 108488000000,
"sale_of_investment_properties": 108488000000,
"purchase_of_investment_properties": 108488000000,
"net_business_purchase_and_sale": 108488000000,
"sale_of_business": 108488000000,
"purchase_of_business": 108488000000,
"net_intangibles_purchase_and_sale": 108488000000,
"sale_of_intangibles": 108488000000,
"purchase_of_intangibles": 108488000000,
"net_ppe_purchase_and_sale": -10959000000,
"sale_of_ppe": 108488000000,
"purchase_of_ppe": -10959000000,
"capital_expenditure_reported": 108488000000,
"capital_expenditure": -10959000000
},
"cash_flow_from_financing_activities": {
"financing_cash_flow": -108488000000,
"cash_flow_from_continuing_financing_activities": -108488000000,
"cash_from_discontinued_financing_activities": 108488000000,
"net_other_financing_charges": -6012000000,
"interest_paid_cff": 108488000000,
"proceeds_from_stock_option_exercised": 108488000000,
"cash_dividends_paid": -15025000000,
"preferred_stock_dividend_paid": 108488000000,
"common_stock_dividend_paid": -15025000000,
"net_preferred_stock_issuance": 108488000000,
"preferred_stock_payments": 108488000000,
"preferred_stock_issuance": 108488000000,
"net_common_stock_issuance": -77550000000,
"common_stock_payments": -77550000000,
"common_stock_issuance": 108488000000,
"repurchase_of_capital_stock": -77550000000,
"net_issuance_payments_of_debt": -9901000000,
"net_short_term_debt_issuance": -3978000000,
"short_term_debt_payments": 108488000000,
"short_term_debt_issuance": 108488000000,
"net_long_term_debt_issuance": -5923000000,
"long_term_debt_payments": -11151000000,
"long_term_debt_issuance": 5228000000,
"issuance_of_debt": 5228000000,
"repayment_of_debt": -11151000000,
"issuance_of_capital_stock": 108488000000
},
"supplemental_data": {
"interest_paid_supplemental_data": 3803000000,
"income_tax_paid_supplemental_data": 18679000000
},
"foreign_and_domestic_sales": {
"foreign_sales": 108488000000,
"domestic_sales": 108488000000,
"adjusted_geography_segment_data": 108488000000
},
"cash_position": {
"beginning_cash_position": 24977000000,
"end_cash_position": 30737000000,
"changes_in_cash": 5760000000,
"other_cash_adjustment_outside_change_in_cash": 108488000000,
"other_cash_adjustment_inside_change_in_cash": 108488000000,
"effect_of_exchange_rate_changes": 108488000000
},
"direct_method_cash_flow": {
"classes_of_cash_receipts_from_operating_activities": 108488000000,
"other_cash_receipts_from_operating_activities": 108488000000,
"receipts_from_government_grants": 108488000000,
"receipts_from_customers": 108488000000,
"classes_of_cash_payments": 108488000000,
"other_cash_payments_from_operating_activities": 108488000000,
"payments_on_behalf_of_employees": 108488000000,
"payments_to_suppliers_for_goods_and_services": 108488000000
}
}
],
"status": "ok"
}
HTTP route
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
Click to expand
|
JSON request example
https://api.twelvedata.com/cash_flow/consolidated?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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
Options Price
Returns a recent price for the options contract.
HTTP request example
https://api.twelvedata.com/options/price?option_id=AAPL240216C00130000&apikey=your_api_key
This request will return JSON with the following structure
{
"last_price": "200.99001"
}
HTTP route
API credits
1 per request
API parameters
| Key | Type | Description |
|---|---|---|
| option_id | string | • Required parameter • Contract name of an option • Format AAPL220121C00505000 |
Response
| Key | Type | Description |
|---|---|---|
| last_price | number | Returns price of the last trade if available |
JSON request example
https://api.twelvedata.com/options/price?option_id=AAPL240216C00130000&apikey=your_api_key
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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
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 |
| figi | string | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
Last changesNew
Returns the latest changes of fundamental data. This endpoint helps consume API credits more efficiently and request new data once it is updated.
HTTP request example
https://api.twelvedata.com/last_change/:endpoint?apikey=demo&start_date=2023-10-14 10:00:00
This request will return JSON with the following structure
[
{
"symbol": "VFIAX",
"mic_code": "XNAS",
"last_change": "2023-10-14 12:22:48"
},
{
"symbol": "AAPL",
"mic_code": "XNAS",
"last_change": "2023-10-14 12:22:48"
}
]
HTTP route
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
|
| endpoint | • Required parameter • Endpoint name. Supported values: price_target, recommendations, statistics, insider_transactions, profile, mutual_funds_world_summary, mutual_funds_world, institutional_holders, analyst_rating, income_statement, cash_flow, balance_sheet, mutual_funds_list, mutual_funds_world_sustainability, mutual_funds_world_summary, mutual_funds_world_risk, mutual_funds_world_purchase_info, mutual_funds_world_composition, mutual_funds_world_performance, mutual_funds_world
|
| start_date | • Parameter is optional • The starting date and time for data selection, in "2006-01-02 15:04:05" format |
| 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 |
| page | • Parameter is optional • Page number; default 1
|
| outputsize | • Parameter is optional • Number of records in response; default 30
|
Response
| Key | Type | Description |
|---|---|---|
| symbol | string | Ticker of the company |
| mic_code | string | Market Identifier Code (MIC) under ISO 10383 standard |
| last_change | string | The date and time of last changes, in "2006-01-02 15:04:05" format. |
JSON request example
https://api.twelvedata.com/last_change/profile?start_date=2023-10-14 10:00:00&apikey=your_api_key
Edgar filings archiveNew
Real-time and historical access to all forms, filings, and exhibits directly from the SEC's EDGAR system.
HTTP request example
https://api.twelvedata.com/edgar_filings/archive?apikey=your_api_key
This request will return JSON with the following structure
{
"meta": {
"symbol": "AAPL",
"exchange": "NASDAQ",
"mic_code": "XNGS",
"type": "Common Stock"
},
"values": [
{
"cik": 1711463,
"filed_at": 1726617600,
"files": [
{
"name": "primary_doc.html",
"type": "144",
"url": "https://www.sec.gov/Archives/edgar/data/1711463/000197185724000581/xsl144X01/primary_doc.xml"
},
{
"name": "primary_doc.xml",
"size": 2980,
"type": "144",
"url": "https://www.sec.gov/Archives/edgar/data/1711463/000197185724000581/primary_doc.xml"
},
{
"name": "0001971857-24-000581.txt",
"size": 4382,
"type": "archive_file",
"url": "https://www.sec.gov/Archives/edgar/data/1711463/000197185724000581/0001971857-24-000581.txt"
}
],
"filing_url": "https://www.sec.gov/Archives/edgar/data/1711463/0001971857-24-000581-index.htm",
"form_type": "144"
}
}
HTTP route
API credits
50 per request
API parameters
| Parameter | Details |
|---|---|
| apikey | • Required parameter • Your personal API key, which you can obtain for free here • Type string
|
| symbol | • Parameter is optional • Filter by symbol |
| figi | Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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 |
| form_type | • Parameter is optional • Filter by form types, example 8-K, EX-1.1
|
| filled_from | • Parameter is optional • Filter by filled time from, example 2024-01-01
|
| filled_to | • Parameter is optional • Filter by filled time to, example 2024-01-01
|
| page | • Parameter is optional • Page number; default 1
|
| page_size | • Parameter is optional • Number of records in response; default 10
|
Response
| Key | Type | Description |
|---|---|---|
| symbol | string | Ticker of the company |
| exchange | string | Exchange name where the company is listed |
| mic_code | string | Market Identifier Code (MIC) under ISO 10383 standard |
| type | string | Issue type of the stock |
| cik | integer | CIK code |
| filled_at | integer | Filing date in UNIX timestamp |
| form_type | string | Filing form type |
| files | array | Filing files |
| files.name | string | File name |
| files.size | integer | File size |
| files.type | string | File type |
| files.url | string | File full url |
| filing_url | string | Full URL of the filing |
| ticker | array | List of tickers |
JSON request example
https://api.twelvedata.com/edgar_filings/archive
Analysis
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
{
"meta": {
"symbol": "AAPL",
"name": "Apple Inc",
"currency": "USD",
"exchange_timezone": "America/New_York",
"exchange": "NASDAQ",
"mic_code": "XNGS",
"type": "Common Stock"
},
"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
API credits
20 per symbol
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
{
"meta": {
"symbol": "AAPL",
"name": "Apple Inc",
"currency": "USD",
"exchange_timezone": "America/New_York",
"exchange": "NASDAQ",
"mic_code": "XNGS",
"type": "Common Stock"
},
"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
API credits
20 per symbol
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
{
"meta": {
"symbol": "AAPL",
"name": "Apple Inc",
"currency": "USD",
"exchange_timezone": "America/New_York",
"exchange": "NASDAQ",
"mic_code": "XNGS",
"type": "Common Stock"
},
"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
API credits
20 per symbol
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
{
"meta": {
"symbol": "AAPL",
"name": "Apple Inc",
"currency": "USD",
"exchange_timezone": "America/New_York",
"exchange": "NASDAQ",
"mic_code": "XNGS",
"type": "Common Stock"
},
"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
API credits
20 per symbol
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
{
"meta": {
"symbol": "AAPL",
"name": "Apple Inc",
"currency": "USD",
"exchange_timezone": "America/New_York",
"exchange": "NASDAQ",
"mic_code": "XNGS",
"type": "Common Stock"
},
"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
API credits
20 per symbol
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
{
"meta": {
"symbol": "AAPL",
"name": "Apple Inc",
"currency": "USD",
"exchange_timezone": "America/New_York",
"exchange": "NASDAQ",
"mic_code": "XNGS",
"type": "Common Stock"
},
"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
API credits
100 per symbol
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
{
"meta": {
"symbol": "AAPL",
"name": "Apple Inc",
"currency": "USD",
"exchange_timezone": "America/New_York",
"exchange": "NASDAQ",
"mic_code": "XNGS",
"type": "Common Stock"
},
"price_target": {
"high": 220,
"median": 185,
"low": 136,
"average": 184.01,
"current": 169.5672
},
"status": "ok"
}
HTTP route
API credits
75 per symbol
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
{
"meta": {
"symbol": "AAPL",
"name": "Apple Inc",
"currency": "USD",
"exchange_timezone": "America/New_York",
"exchange": "NASDAQ",
"mic_code": "XNGS",
"type": "Common Stock"
},
"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
API credits
75 per symbol
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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
{
"meta": {
"symbol": "AAPL",
"name": "Apple Inc",
"currency": "USD",
"exchange_timezone": "America/New_York",
"exchange": "NASDAQ",
"mic_code": "XNGS",
"type": "Common Stock"
},
"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
API credits
200 per symbol
API parameters
| Parameter | Details |
|---|---|
| symbol | • Required parameter • Filter by symbol |
| figi | • Parameter is optional • Filter by financial instrument global identifier (FIGI) |
| 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:
- Server limits to receive up to
100events from the client-side. This constraint does not affect the number of messages sent from the server to the client. - There is no limit on the number of input symbols; however, the size of the input message can not exceed
1 MB.
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
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:
- Manually unsubscribe from symbols. This is done with the same format as the subscription, but with action set to
"action": "unsubscribe". - 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.
- Common parameters are
intervals,outputsize, etc. - General parameters are:
symbols(required),apikey(optional), common parameters, andmethodsarray (required). - Method could be either a string with the name of endpoint (as with a single API call) or an object.
The object takes
name(required) and optional common parameters. Take note that method parameters are given higher priority, over general ones in the case of overlapping.
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 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.
AD
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=