Discovery

Discovery endpoints help you find instruments when you don't already know the exact identifier. The Asset Catalog is the phone book; Discovery is the search engine on top of it.

Symbol search High demand

The symbol search endpoint allows users to find financial instruments by name or symbol. It returns a list of matching symbols, ordered by relevance, with the most relevant instrument first. This is useful for quickly locating specific stocks, ETFs, or other financial instruments when only partial information is available.

Route

/symbol_search

API credits cost

1 per request

Parameters Response

✱ symbol

string

Symbol to search. Supports:

Ticker symbol of instrument.
Look up an instrument by its International Securities Identification Number (ISIN). Available on all plans. Returning ISIN values in responses requires the ISIN Data add-on.
The FIGI (Financial Instrument Global Identifier) parameter is available on the Ultra plan (individual) and Enterprise plan (business) and above.
Composite FIGI parameter is available on the Ultra plan (individual) and Enterprise plan (business) and above.
Share Class FIGI parameter is available on the Ultra plan (individual) and Enterprise plan (business) and above.

Example: AAPL

outputsize

integer

Number of matches in response. Max 120

Default: 30

show_plan

boolean

Adds info on which plan symbol is available.

Default: false

data

array of object

List of symbols matching the search criteria

Attributes

symbol

string

Ticker symbol of instrument

instrument_name

string

Name of exchange

exchange

string

Exchange where instrument is traded

mic_code

string

Market identifier code (MIC) under ISO 10383 standard

exchange_timezone

string

Time zone where exchange is located

instrument_type

string

Type of instrument

country

string

Country to which stock exchange belongs to

currency

string

Currency in which the instrument is traded

access

object

Info on which plan symbol is available (displayed then show_plan is true)

Attributes

global

string

Level of access to the symbol

plan

string

The individual plan name for the symbol

plan_business

string

The business plan name for the symbol

status

string

Status of the response

Copy for LLM

View as Markdown

Request example

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

Response

{
    "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",
                "plan_business": "Basic"
            }
        }
    ],
    "status": "ok"
}

Cross listings

The cross_listings endpoint provides a daily updated list of cross-listed symbols for a specified financial instrument. Cross-listed symbols represent the same security available on multiple exchanges. This endpoint is useful for identifying all the exchanges where a particular security is traded, allowing users to access comprehensive trading information across different markets.

Route

/cross_listings

API credits cost

40 per request

This API endpoint is available on the Grow plan (individual) and the Venture plan (business) and above.

Parameters Response

✱ symbol

string

The ticker symbol of an instrument for which data is requested

Example: AAPL

exchange

string

Exchange where instrument is traded

Example: NASDAQ

mic_code

string

Market identifier code (MIC) under ISO 10383 standard

Example: XNGS

country

string

Country to which stock exchange belongs to

Example: United States

Copy for LLM

View as Markdown

Request example

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

Response

{
    "result": {
        "count": 4,
        "list": [
            {
                "exchange": "NASDAQ",
                "mic_code": "XNGS",
                "name": "NVIDIA Corporation",
                "symbol": "NVDA"
            },
            {
                "exchange": "VSE",
                "mic_code": "XWBO",
                "name": "NVIDIA Corporation",
                "symbol": "NVDA"
            },
            {
                "exchange": "BVS",
                "mic_code": "XSGO",
                "name": "NVIDIA Corporation",
                "symbol": "NVDACL"
            },
            {
                "exchange": "BVS",
                "mic_code": "XSGO",
                "name": "NVIDIA Corporation",
                "symbol": "NVDA"
            }
        ]
    }
}

Earliest timestamp

The earliest_timestamp endpoint provides the earliest available date and time for a specified financial instrument at a given data interval. This endpoint is useful for determining the starting point of historical data availability for various assets, such as stocks or currencies, allowing users to understand the time range covered by the data.

Route

/earliest_timestamp

API credits cost

1 per request

Parameters Response

✱ One of these parameters is required

symbol

string

Symbol ticker of the instrument.

Example: AAPL

figi

string

Filter by financial instrument global identifier (FIGI). This parameter is available on the Ultra plan (individual) and the Enterprise plan (business) and above.

Example: BBG000B9XRY4

isin

string

Look up an instrument by its International Securities Identification Number (ISIN). Available on all plans. Returning ISIN values in responses requires the ISIN Data add-on.

Example: US0378331005

cusip

string

Look up an instrument by its Committee on Uniform Securities Identification Procedures (CUSIP) number. Available on all plans. Returning CUSIP values in responses requires the CUSIP Data add-on.

Example: 594918104

✱ interval

string

Interval between two consecutive points in time series.

Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 8h, 1day, 1week, 1month

Example: 1day

exchange

string

Exchange where instrument is traded.

Example: Nasdaq

mic_code

string

Market Identifier Code (MIC) under ISO 10383 standard.

Example: XNAS

timezone

string

Timezone at which output datetime will be displayed. Supports:

1. Exchange for local exchange time
2. UTC for datetime at universal UTC standard
3. Timezone name according to the IANA Time Zone Database. E.g. America/New_York, Asia/Singapore. Full list of timezones can be found here.

Interval Limitation: The timezone parameter is only applicable for intraday intervals (less than 1 day). For intervals of 1day, 1week, or 1month, the timezone parameter is ignored, and data is strictly returned in the Exchange local time.

Take note that the IANA Timezone name is case-sensitive

Default: Exchange

Copy for LLM

View as Markdown

Request example

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

Response

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