Twelwdata

Type: twelwdata • Category: flow

Description

Twelve Data provides access to over 100,000 financial symbols from various markets, including stocks, forex, cryptocurrencies, ETFs, and commodities. This allows you to obtain data from more than 250 exchanges worldwide.

Parameters

Name	Type	Description	Required	Default
symbol	string	Example NVDA	no
date_from	date	Example date	no	"2025-01-01"
date_to	date	Example date	no	"2099-01-01"
interval	string	Interval	no	"1h"
type	string	Type of the data to fetch	no	"price"
exchange	string	Exchange, Example NASDAQ	no
country	string	Country, Example USA	no
period	string	Period for financial data	no	"annual"
outputsize	number	Output size	no	100
expiration_date	date	Expiration date for options	no
option_id	string	Option ID	no
side	string	Option side	no

Help

Overview

Twelve Data offers programmatic access to more than 100,000 financial symbols across a wide range of asset classes—stocks, forex, cryptocurrencies, ETFs, and commodities. The service aggregates data from over 250 exchanges worldwide, enabling you to retrieve price histories, corporate fundamentals, earnings information, and option‑related metrics through a single, consistent API.

The worker described below acts as a thin wrapper around the official twelvedata Python client. By supplying a small set of parameters you can request any of the supported data types (price series, company profile, dividends, splits, earnings, etc.) and receive the result as JSON ready for downstream analysis.

---

Input Parameters

• symbol string – The ticker or identifier of the instrument (e.g., NVDA).
• date_from date – Start date for time‑restricted queries. Default: 2025‑01‑01.
• date_to date – End date for time‑restricted queries. Default: 2099‑01‑01.
• interval string – Granularity of time‑series data (e.g., 1h, 1d). Default: 1h.
• type string – Category of data to fetch. Options include price, profile, dividends, splits, earnings, earnings_calendar, ipo_calendar, statistics, insider_transactions, income_statement, balance_sheet, cash_flow, options_expiration. Default: price.
• exchange string – Exchange on which the symbol trades (e.g., NASDAQ).
• country string – Country of the exchange or issuer (e.g., USA).
• period string – Reporting period for financial statements (annual, quarterly). Default: annual.
• outputsize number – Maximum number of records to return. Default: 100.
• expiration_date date – Specific expiration date when requesting option chains.
• option_id string – Identifier of a particular option contract.
• side string – Option side (call or put).

All parameters are optional unless otherwise noted; the worker supplies sensible defaults so that a basic price request can be made with only the symbol field.

---

Minimal Example Usage

# Initialise the Twelve Data client (replace with your own API key)
from twelvedata import TDClient
td = TDClient(apikey="YOUR_API_KEY")

# Parameters supplied to the worker
params = {
    "symbol": "NVDA",
    "type": "price",
    "interval": "1h",
    "date_from": "2024-01-01",
    "date_to": "2024-01-31"
}

# Build the request dictionary dynamically
ts_params = {
    "symbol": params["symbol"],
    "interval": params["interval"],
    "outputsize": 1000,
    "timezone": "America/New_York"
}
if params.get("date_from"):
    ts_params["start_date"] = params["date_from"]
if params.get("date_to"):
    ts_params["end_date"] = params["date_to"]

# Dispatch the appropriate API call based on the requested type
if params["type"] == "price":
    ts = td.time_series(**ts_params)
    result = ts.as_json()
elif params["type"] == "profile":
    result = td.get_profile(symbol=params["symbol"],
                            exchange=params.get("exchange"),
                            country=params.get("country"))
elif params["type"] == "dividends":
    result = td.get_dividends(symbol=params["symbol"],
                              exchange=params.get("exchange"),
                              country=params.get("country"))
elif params["type"] == "splits":
    result = td.get_splits(symbol=params["symbol"],
                           exchange=params.get("exchange"),
                           country=params.get("country"))
elif params["type"] == "earnings":
    result = td.get_earnings(symbol=params["symbol"],
                             exchange=params.get("exchange"),
                             country=params.get("country"),
                             period=params.get("period", "annual"),
                             outputsize=params.get("outputsize", 100),
                             start_date=params.get("date_from"),
                             end_date=params.get("date_to"))
# …additional branches for the remaining types…

# `result` now contains the JSON payload returned by Twelve Data.

In this short script the worker:

1. Instantiates the Twelve Data client with a valid API key.
2. Constructs a parameter dictionary, adding start/end dates only when they are supplied.
3. Selects the appropriate endpoint based on the type field.
4. Returns the raw JSON response, which can be parsed or stored as needed.

---

Additional Notes

• Authentication – An active Twelve Data API key is mandatory. The key must be passed to TDClient(apikey=…).
• Timezone handling – The example forces the America/New_York timezone; adjust as required for your market.
• Output size – For time‑series data the worker defaults to outputsize=1000 to ensure a complete dataset for the requested period.
• Optional fields – Parameters such as exchange, country, expiration_date, option_id, and side are only used for the specific endpoints that need them (e.g., options‑related calls).
• Error handling – The underlying client raises exceptions for invalid symbols, missing permissions, or network issues. Wrap the call in a try/except block if you need graceful degradation.

By following the structure above you can retrieve virtually any publicly available market data that Twelve Data supports, using a concise and uniform interface.