twelvedata

package module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 16, 2026 License: MIT Imports: 25 Imported by: 1

README

Twelve data go api client

Go Report Card Tests and linters

Install

go get github.com/soulgarden/twelvedata@latest

If you're upgrading from v0.1.x, see MIGRATION.md.

Covered:

Market data

  • Time series ✅ High demand
  • Time series cross ✅
  • Quote ✅ High demand
  • Latest price ✅ High demand
  • End of day price ✅
  • Market movers ✅ High demand

Reference Data

Asset Catalogs
  • Stocks ✅
  • Forex pairs ✅
  • Cryptocurrency pairs ✅
  • ETFs ✅
  • Funds ✅
  • Commodities ✅
  • Fixed income ✅
Discovery
  • Symbol search ✅ High demand
  • Cross listings ✅
  • Earliest timestamp ✅
Markets
  • Exchanges ✅ High demand
  • Exchanges schedule ✅
  • Cryptocurrency exchanges ✅
  • Market state ✅
Supporting Metadata
  • Countries ✅
  • Instrument type ✅
  • Technical indicators ✅

Fundamentals

  • Logo ✅
  • Profile ✅ Useful
  • Dividends ✅
  • Dividends calendar ✅
  • Splits ✅
  • Splits calendar ✅
  • Earnings ✅
  • Earnings calendar ✅
  • IPO calendar ✅
  • Statistics ✅
  • Press releases ✅ New
  • Income statement ✅
  • Income statement consolidated ✅ New
  • Balance sheet ✅
  • Balance sheet consolidated ✅ New
  • Cash flow ✅
  • Cash flow consolidated ✅ New
  • Key executives ✅ Useful
  • Market capitalization ✅ New
  • Last changes ✅ New

Currencies

  • Exchange rate ✅
  • Currency conversion ✅ Useful

ETFs

  • ETFs directory ✅ Useful
  • ETF full data ✅ High demand
  • Summary ✅
  • Performance ✅ High demand
  • Risk ✅
  • Composition ✅ High demand
  • ETFs families ✅
  • ETFs types ✅

Mutual Funds

  • MFs directory ✅ Useful
  • MF full data ✅ High demand
  • Summary ✅
  • Performance ✅ High demand
  • Risk ✅
  • Ratings ✅
  • Composition ✅ High demand
  • Purchase info ✅
  • Sustainability ✅
  • MFs families ✅
  • MFs types ✅

Technical Indicators

Overlap Studies
  • Bollinger Bands ✅ High demand
  • Double Exponential Moving Average (DEMA) ✅
  • Exponential Moving Average (EMA) ✅ High demand
  • Hilbert Transform Instantaneous Trendline ❌
  • Ichimoku Cloud ❌
  • Kaufman Adaptive Moving Average (KAMA) ✅
  • Keltner Channel ❌
  • Moving Average ✅
  • MESA Adaptive Moving Average (MAMA) ❌
  • McGinley Dynamic Indicator ❌
  • Midpoint ❌
  • Midprice ❌
  • Pivot Points High Low ❌
  • Parabolic Stop and Reverse (SAR) ✅
  • Parabolic Stop and Reverse Extended (SAREXT) ❌
  • Simple Moving Average (SMA) ✅ High demand
  • Triple Exponential Moving Average (T3MA) ❌
  • Triple Exponential Moving Average (TEMA) ✅
  • Triangular Moving Average ✅
  • Volume Weighted Average Price ✅
  • Weighted Moving Average ✅
Momentum Indicators
  • Average Directional Index (ADX) ✅ High demand
  • Average Directional Movement Index Rating ❌
  • Absolute Price Oscillator ❌
  • Aroon Indicator ❌
  • Aroon Oscillator ❌
  • Balance of Power ❌
  • Commodity Channel Index ✅
  • Chande Momentum Oscillator ❌
  • Coppock Curve ❌
  • Connors Relative Strength Index ❌
  • Detrended Price Oscillator ❌
  • Directional Movement Index ❌
  • Know Sure Thing ❌
  • Moving Average Convergence Divergence (MACD) ✅ High demand
  • MACD Slope ❌
  • MACD Extension ❌
  • Money Flow Index ❌
  • Minus Directional Indicator ❌
  • Minus Directional Movement ❌
  • Momentum ✅
  • Percent B ✅ High demand
  • Plus Directional Indicator ❌
  • Plus Directional Movement ❌
  • Percentage Price Oscillator ❌
  • Rate of Change ✅
  • Rate of Change Percentage ❌
  • Rate of Change Ratio ❌
  • Rate of Change Ratio 100 ❌
  • Relative Strength Index (RSI) ✅ High demand
  • Stochastic Oscillator ✅ High demand
  • Stochastic Fast ❌
  • Stochastic Relative Strength Index ❌
  • Ultimate Oscillator ❌
  • Williams %R ✅
Volume Indicators
  • Accumulation/Distribution ✅
  • Accumulation/Distribution Oscillator ❌
  • On Balance Volume ✅
  • Relative Volume ❌
Volatility Indicators
  • Average True Range (ATR) ✅
  • Normalized Average True Range (NATR) ✅
  • Supertrend ❌
  • Supertrend Heikin Ashi candles ❌
  • True Range ✅
Price Transform
  • Addition ❌
  • Average ❌
  • Average Price ❌
  • Ceiling ❌
  • Division ❌
  • Exponential ❌
  • Floor ❌
  • Heikinashi Candles ❌
  • High, Low, Close Average ❌
  • Natural Logarithm ❌
  • Base-10 Logarithm ❌
  • Median Price ❌
  • Multiplication ❌
  • Square Root ❌
  • Subtraction ❌
  • Summation ❌
  • Typical Price ❌
  • Weighted Close Price ❌
Cycle Indicators
  • Hilbert Transform Dominant Cycle Period ❌
  • Hilbert Transform Dominant Cycle Phase ❌
  • Hilbert Transform Phasor Components ❌
  • Hilbert Transform Sine Wave ❌
  • Hilbert Transform Trend vs Cycle Mode ❌
Statistic Functions
  • Beta Indicator ❌
  • Correlation ❌
  • Linear Regression ❌
  • Linear Regression Angle ❌
  • Linear Regression Intercept ❌
  • Linear Regression Slope ❌
  • Maximum ❌
  • Maximum Index ❌
  • Minimum ❌
  • Minimum Index ❌
  • Minimum and Maximum ❌
  • Minimum and Maximum Index ❌
  • Standard Deviation ❌
  • Time Series Forecast ❌
  • Variance ❌

Analysis

  • Earnings estimate ✅ Useful
  • Revenue estimate ✅
  • EPS trend ✅
  • EPS revisions ✅
  • Growth estimates ✅
  • Recommendations ✅ High demand
  • Price target ✅ High demand
  • Analyst ratings snapshot ✅
  • Analyst ratings US equities ✅

Regulatory

  • EDGAR filings ✅
  • Insider transaction ✅
  • Institutional holders ✅
  • Fund holders ✅
  • Direct holders ✅
  • Tax information ✅
  • Sanctioned entities ✅

Advanced

  • Batches ✅ Useful
  • API usage ✅

WebSocket

  • Real-time price ✅ Useful

Usage

http example

ws example

error handling example

Documentation

Overview

Package twelvedata provides a Go client for the Twelve Data API, offering comprehensive access to market data, reference data, fundamentals, and more.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsAPIKeyError added in v1.0.0 

func IsAPIKeyError(err error) bool

IsAPIKeyError checks if an error is an APIKeyError type.

func IsBadRequestError added in v1.0.0 

func IsBadRequestError(err error) bool

IsBadRequestError checks if an error is a BadRequestError type.

func IsDomainError added in v1.0.0 

func IsDomainError(err error) bool

IsDomainError checks if an error is any of the Twelve Data domain-specific errors.

func IsHTTPError added in v1.0.0 

func IsHTTPError(err error) bool

IsHTTPError checks if an error is an HTTPError or any of its subtypes.

func IsInsufficientCreditsError added in v1.0.0 

func IsInsufficientCreditsError(err error) bool

IsInsufficientCreditsError checks if an error is an InsufficientCreditsError type.

func IsNetworkError added in v1.0.0 

func IsNetworkError(err error) bool

IsNetworkError checks if an error is a NetworkError type.

func IsNotFoundError added in v1.0.0 

func IsNotFoundError(err error) bool

IsNotFoundError checks if an error is a NotFoundError type.

func IsPlanLimitationError added in v1.0.0 

func IsPlanLimitationError(err error) bool

IsPlanLimitationError checks if an error is a PlanLimitationError type.

func IsRateLimitError added in v1.0.0 

func IsRateLimitError(err error) bool

IsRateLimitError checks if an error is a TooManyRequestsError type.

func IsSymbolNotFoundError added in v1.0.0 

func IsSymbolNotFoundError(err error) bool

IsSymbolNotFoundError checks if an error is a SymbolNotFoundError type.

func IsTimeoutError added in v1.0.0 

func IsTimeoutError(err error) bool

IsTimeoutError checks if an error is a TimeoutError type.

func IsUnauthorizedError added in v1.0.0 

func IsUnauthorizedError(err error) bool

IsUnauthorizedError checks if an error is an UnauthorizedError type.

func IsWSConnectionError added in v1.0.0 

func IsWSConnectionError(err error) bool

IsWSConnectionError checks if an error is a WSConnectionError type.

func IsWSError added in v1.0.0 

func IsWSError(err error) bool

IsWSError checks if an error is any WebSocket-related error type.

func IsWSMessageError added in v1.0.0 

func IsWSMessageError(err error) bool

IsWSMessageError checks if an error is a WSMessageError type.

func IsWSSubscriptionError added in v1.0.0 

func IsWSSubscriptionError(err error) bool

IsWSSubscriptionError checks if an error is a WSSubscriptionError type.

func NewHTTPError added in v1.0.0 

func NewHTTPError(statusCode int, body []byte, url string, apiError *response.Error, cause error) error

NewHTTPError creates appropriate typed error based on HTTP status code.

func ParseDomainError added in v1.0.0 

func ParseDomainError(apiError *response.Error, _ int, _ string) error

ParseDomainError analyzes an API error response and converts it to a domain-specific error.

func WrapWithDomainError added in v1.0.0 

func WrapWithDomainError(err error, apiError *response.Error, statusCode int, url string) error

WrapWithDomainError wraps an existing error with domain-specific error if applicable.

Types

type APIKeyError added in v1.0.0 

type APIKeyError struct {
	Type    string // "invalid", "required", "expired"
	Message string
	Cause   error
}

APIKeyError represents API key related errors.

func (APIKeyError) Error added in v1.0.0 

func (e APIKeyError) Error() string

func (APIKeyError) Unwrap added in v1.0.0 

func (e APIKeyError) Unwrap() error

type Advanced 

type Advanced struct {
	UsageURL   string `default:"/api_usage" json:"usage_url"`
	BatchesURL string `default:"/batch"     json:"batches_url"`
}

Advanced contains URL configurations for advanced API endpoints such as usage tracking and batch operations.

type Analysis added in v1.0.0 

type Analysis struct {
	EarningsEstimateURL         string `default:"/earnings_estimate"            json:"earnings_estimate_url"`
	RevenueEstimateURL          string `default:"/revenue_estimate"             json:"revenue_estimate_url"`
	EPSTrendURL                 string `default:"/eps_trend"                    json:"eps_trend_url"`
	EPSRevisionsURL             string `default:"/eps_revisions"                json:"eps_revisions_url"`
	GrowthEstimatesURL          string `default:"/growth_estimates"             json:"growth_estimates_url"`
	RecommendationsURL          string `default:"/recommendations"              json:"recommendations_url"`
	PriceTargetURL              string `default:"/price_target"                 json:"price_target_url"`
	AnalystRatingsSnapshotURL   string `default:"/analyst_ratings/light"        json:"analyst_ratings_snapshot_url"`
	AnalystRatingsUSEquitiesURL string `default:"/analyst_ratings/us_equities"  json:"analyst_ratings_us_equities_url"`
}

Analysis contains URL configurations for analysis endpoints including earnings estimates, recommendations, and price targets. nolint: lll

type BadRequestError added in v1.0.0 

type BadRequestError struct {
	HTTPError
	APIError *response.Error
}

BadRequestError represents 400 Bad Request errors.

func (BadRequestError) Error added in v1.0.0 

func (e BadRequestError) Error() string

type Client added in v1.0.0 

type Client interface {
	// Market Data
	GetTimeSeries(request.GetTimeSeries) (response.TimeSeries, response.Credits, error)
	GetTimeSeriesCross(request.GetTimeSeriesCross) (response.TimeSeriesCross, response.Credits, error)
	GetQuote(request.GetQuote) (response.Quote, response.Credits, error)
	GetPrice(request.GetPrice) (response.Price, response.Credits, error)
	GetEOD(request.GetEOD) (response.EOD, response.Credits, error)
	GetMarketMovers(request.GetMarketMovers) (response.MarketMovers, response.Credits, error)

	// Reference Data - Asset Catalogs
	GetStocks(request.GetStock) (response.Stocks, response.Credits, error)
	GetForexPairs(request.GetForexPairs) (response.ForexPairs, response.Credits, error)
	GetCryptocurrencies(request.GetCryptocurrencies) (response.Cryptocurrencies, response.Credits, error)
	GetETFs(request.GetETFs) (response.ETFs, response.Credits, error)
	GetFunds(request.GetFunds) (response.Funds, response.Credits, error)
	GetCommodities(request.GetCommodities) (response.Commodities, response.Credits, error)
	GetBonds(request.GetBonds) (response.Bonds, response.Credits, error)

	// Reference Data - Discovery
	GetSymbolSearch(request.GetSymbolSearch) (response.SymbolSearch, response.Credits, error)
	GetCrossListings(request.GetCrossListings) (response.CrossListings, response.Credits, error)
	GetEarliestTimestamp(request.GetEarliestTimestamp) (response.EarliestTimestamp, response.Credits, error)

	// Reference Data - Markets
	GetExchanges(request.GetExchanges) (response.Exchanges, response.Credits, error)
	GetExchangeSchedule(request.GetExchangeSchedule) (response.ExchangeSchedule, response.Credits, error)
	GetCryptocurrencyExchanges(request.GetCryptocurrencyExchanges) (response.CryptocurrencyExchanges, response.Credits, error)
	GetMarketState(request.GetMarketState) ([]response.MarketState, response.Credits, error)

	// Reference Data - Supporting Metadata
	GetCountries(request.GetCountries) (response.Countries, response.Credits, error)
	GetInstrumentType(request.GetInstrumentType) (response.InstrumentType, response.Credits, error)
	GetTechnicalIndicators(request.GetTechnicalIndicators) (response.TechnicalIndicators, response.Credits, error)

	// Fundamentals
	GetProfile(request.GetProfile) (response.Profile, response.Credits, error)
	GetDividends(request.GetDividends) (response.Dividends, response.Credits, error)
	GetDividendsCalendar(request.GetDividendsCalendar) (response.DividendsCalendar, response.Credits, error)
	GetEarnings(request.GetEarnings) (response.Earnings, response.Credits, error)
	GetEarningsCalendar(request.GetEarningsCalendar) (response.EarningsCalendar, response.Credits, error)
	GetIPOCalendar(request.GetIPOCalendar) (response.IPOCalendar, response.Credits, error)
	GetSplits(request.GetSplits) (response.Splits, response.Credits, error)
	GetSplitsCalendar(request.GetSplitsCalendar) (response.SplitsCalendar, response.Credits, error)
	GetStatistics(statistics request.GetStatistics) (response.Statistics, response.Credits, error)
	GetPressReleases(request.GetPressReleases) (response.PressReleases, response.Credits, error)
	GetIncomeStatement(request.GetIncomeStatement) (response.IncomeStatements, response.Credits, error)
	GetIncomeStatementConsolidated(request.GetIncomeStatement) (response.IncomeStatements, response.Credits, error)
	GetBalanceSheet(request.GetBalanceSheet) (response.BalanceSheets, response.Credits, error)
	GetBalanceSheetConsolidated(request.GetBalanceSheet) (response.BalanceSheets, response.Credits, error)
	GetCashFlow(request.GetCashFlow) (response.CashFlows, response.Credits, error)
	GetCashFlowConsolidated(request.GetCashFlow) (response.CashFlows, response.Credits, error)
	GetKeyExecutives(request.GetKeyExecutives) (response.KeyExecutives, response.Credits, error)
	GetMarketCap(request.GetMarketCap) (response.MarketCap, response.Credits, error)
	GetLastChange(request.GetLastChange) (response.LastChange, response.Credits, error)

	// Currencies
	GetExchangeRate(request.GetExchangeRate) (response.ExchangeRate, response.Credits, error)
	GetCurrencyConversion(request.GetCurrencyConversion) (response.CurrencyConversion, response.Credits, error)

	// ETFs
	GetETFsDirectory(request.GetETFsDirectory) (response.ETFsDirectory, response.Credits, error)
	GetETFFullData(request.GetETFFullData) (response.ETFFullData, response.Credits, error)
	GetETFSummary(request.GetETFSummary) (response.ETFWorldSummary, response.Credits, error)
	GetETFPerformance(request.GetETFPerformance) (response.ETFPerformance, response.Credits, error)
	GetETFRisk(request.GetETFRisk) (response.ETFRisk, response.Credits, error)
	GetETFComposition(request.GetETFComposition) (response.ETFComposition, response.Credits, error)
	GetETFFamilies(request.GetETFFamilies) (response.ETFFamilies, response.Credits, error)
	GetETFTypes(request.GetETFTypes) (response.ETFTypes, response.Credits, error)

	// Mutual Funds
	GetMutualFundsDirectory(request.GetMutualFundsDirectory) (response.MutualFundsDirectory, response.Credits, error)
	GetMutualFundFullData(request.GetMutualFundFullData) (response.MutualFundFullData, response.Credits, error)
	GetMutualFundSummary(request.GetMutualFundSummary) (response.MutualFundSummary, response.Credits, error)
	GetMutualFundPerformance(request.GetMutualFundPerformance) (response.MutualFundPerformance, response.Credits, error)
	GetMutualFundRisk(request.GetMutualFundRisk) (response.MutualFundRisk, response.Credits, error)
	GetMutualFundRatings(request.GetMutualFundRatings) (response.MutualFundRatings, response.Credits, error)
	GetMutualFundComposition(request.GetMutualFundComposition) (response.MutualFundComposition, response.Credits, error)
	GetMutualFundPurchaseInfo(request.GetMutualFundPurchaseInfo) (response.MutualFundPurchaseInfo, response.Credits, error)
	GetMutualFundSustainability(request.GetMutualFundSustainability) (response.MutualFundSustainability, response.Credits, error)
	GetMutualFundFamilies(request.GetMutualFundFamilies) (response.MutualFundFamilies, response.Credits, error)
	GetMutualFundTypes(request.GetMutualFundTypes) (response.MutualFundTypes, response.Credits, error)

	// Technical Indicators
	GetBBands(request.GetBBands) (response.BBands, response.Credits, error)
	GetSMA(request.GetSMA) (response.SMA, response.Credits, error)
	GetEMA(request.GetEMA) (response.EMA, response.Credits, error)
	GetADX(request.GetADX) (response.ADX, response.Credits, error)
	GetMACD(request.GetMACD) (response.MACD, response.Credits, error)
	GetRSI(request.GetRSI) (response.RSI, response.Credits, error)
	GetStoch(request.GetStoch) (response.Stoch, response.Credits, error)
	GetPercentB(request.GetPercentB) (response.PercentB, response.Credits, error)
	GetATR(request.GetATR) (response.ATR, response.Credits, error)
	GetVWAP(request.GetVWAP) (response.VWAP, response.Credits, error)
	GetMA(request.GetMA) (response.MA, response.Credits, error)
	GetWMA(request.GetWMA) (response.WMA, response.Credits, error)
	GetDEMA(request.GetDEMA) (response.DEMA, response.Credits, error)
	GetTEMA(request.GetTEMA) (response.TEMA, response.Credits, error)
	GetTRMA(request.GetTRMA) (response.TRMA, response.Credits, error)
	GetKAMA(request.GetKAMA) (response.KAMA, response.Credits, error)
	GetSAR(request.GetSAR) (response.SAR, response.Credits, error)
	GetCCI(request.GetCCI) (response.CCI, response.Credits, error)
	GetWillR(request.GetWillR) (response.WillR, response.Credits, error)
	GetROC(request.GetROC) (response.ROC, response.Credits, error)
	GetMOM(request.GetMOM) (response.MOM, response.Credits, error)
	GetOBV(request.GetOBV) (response.OBV, response.Credits, error)
	GetAD(request.GetAD) (response.AD, response.Credits, error)
	GetNATR(request.GetNATR) (response.NATR, response.Credits, error)
	GetTR(request.GetTR) (response.TR, response.Credits, error)

	// Analysis
	GetRecommendations(request.GetRecommendations) (response.Recommendations, response.Credits, error)
	GetPriceTarget(request.GetPriceTarget) (response.PriceTarget, response.Credits, error)
	GetEarningsEstimate(request.GetEarningsEstimate) (response.EarningsEstimate, response.Credits, error)
	GetRevenueEstimate(request.GetRevenueEstimate) (response.RevenueEstimate, response.Credits, error)
	GetEPSTrend(request.GetEPSTrend) (response.EPSTrend, response.Credits, error)
	GetEPSRevisions(request.GetEPSRevisions) (response.EPSRevisions, response.Credits, error)
	GetGrowthEstimates(request.GetGrowthEstimates) (response.GrowthEstimates, response.Credits, error)
	GetAnalystRatingsSnapshot(request.GetAnalystRatingsSnapshot) (response.AnalystRatingsSnapshot, response.Credits, error)
	GetAnalystRatingsUSEquities(request.GetAnalystRatingsUSEquities) (response.AnalystRatingsUSEquities, response.Credits, error)

	// Regulatory
	GetInsiderTransactions(request.GetInsiderTransactions) (response.InsiderTransactions, response.Credits, error)
	GetEDGARFilings(request.GetEDGARFilings) (response.EDGARFilings, response.Credits, error)
	GetInstitutionalHolders(request.GetInstitutionalHolders) (response.InstitutionalHolders, response.Credits, error)
	GetFundHolders(request.GetFundHolders) (response.FundHolders, response.Credits, error)
	GetDirectHolders(request.GetDirectHolders) (response.DirectHolders, response.Credits, error)
	GetTaxInformation(request.GetTaxInformation) (response.TaxInformation, response.Credits, error)
	GetSanctionedEntities(request.GetSanctionedEntities) (response.SanctionedEntities, response.Credits, error)

	// Advanced
	GetUsage(request.GetUsage) (response.Usage, response.Credits, error)
	GetBatches(request.GetBatches) (response.Batches, response.Credits, error)
}

Client defines the interface for interacting with the Twelve Data API. It provides methods for accessing various financial data endpoints including market data, reference data, fundamentals, and currencies.

func NewClient added in v1.0.0 

func NewClient(httpCli *HTTPCli, cfg *Conf) Client

NewClient creates a new Twelve Data API client instance with the provided HTTP client and configuration. The httpCli parameter should be configured with appropriate timeout and other HTTP settings, while cfg contains the API endpoints, authentication, and other client configuration.

type Conf 

type Conf struct {
	BaseURL   string `default:"https://api.twelvedata.com" json:"base_url"`
	BaseWSURL string `default:"ws.twelvedata.com"          json:"base_ws_url"`

	CoreData            CoreData            `json:"core_data"`
	ReferenceData       ReferenceData       `json:"reference_data"`
	Fundamentals        Fundamentals        `json:"fundamentals"`
	Currencies          Currencies          `json:"currencies"`
	ETFs                ETFs                `json:"etfs"`
	MutualFunds         MutualFunds         `json:"mutual_funds"`
	TechnicalIndicators TechnicalIndicators `json:"technical_indicators"`
	Analysis            Analysis            `json:"analysis"`
	Regulatory          Regulatory          `json:"regulatory"`
	Advanced            Advanced            `json:"advanced"`
	WebSocket           WebSocket           `json:"web_socket"`

	APIKey  string `default:"demo" json:"api_key"`
	Timeout int    `default:"15"   json:"timeout"`
}

Conf holds the configuration settings for the Twelve Data API client, including base URLs, API endpoints, authentication, and timeout settings.

type CoreData 

type CoreData struct {
	TimeSeriesURL      string `default:"/time_series"       json:"time_series_url"`
	TimeSeriesCrossURL string `default:"/time_series/cross" json:"time_series_cross_url"`
	QuotesURL          string `default:"/quote"             json:"quotes_url"`
	PriceURL           string `default:"/price"             json:"price_url"`
	EODURL             string `default:"/eod"               json:"eod_url"`

	MarketMoversURL string `default:"/market_movers/{market}" json:"market_movers_url"`
}

CoreData contains URL configurations for market data endpoints including time series data, quotes, prices, and end-of-day data. nolint: lll

type Currencies added in v1.0.0 

type Currencies struct {
	ExchangeRateURL       string `default:"/exchange_rate"        json:"exchange_rate_url"`
	CurrencyConversionURL string `default:"/currency_conversion"  json:"currency_conversion_url"`
}

Currencies contains URL configurations for currency-related endpoints including exchange rates and conversions.

type ETFs added in v1.0.0 

type ETFs struct {
	ETFsDirectoryURL   string `default:"/etfs/list"              json:"etfs_directory_url"`
	ETFsFullDataURL    string `default:"/etfs/world"             json:"etfs_full_data_url"`
	ETFsSummaryURL     string `default:"/etfs/world/summary"     json:"etfs_summary_url"`
	ETFsPerformanceURL string `default:"/etfs/world/performance" json:"etfs_performance_url"`
	ETFsRiskURL        string `default:"/etfs/world/risk"        json:"etfs_risk_url"`
	ETFsCompositionURL string `default:"/etfs/world/composition" json:"etfs_composition_url"`
	ETFsFamiliesURL    string `default:"/etfs/family"            json:"etfs_families_url"`
	ETFsTypesURL       string `default:"/etfs/type"              json:"etfs_types_url"`
}

ETFs contains URL configurations for ETF-related endpoints including directory, full data, and performance metrics. nolint: lll

type Endpoint added in v1.0.0 

type Endpoint[Request any, Response any, Credits response.Credits, Error error] struct {
	URL string
	// contains filtered or unexported fields
}

Endpoint represents a generic HTTP endpoint with type-safe request/response handling.

func NewEndpoint added in v1.0.0 

func NewEndpoint[Request any, Response any, Credits response.Credits, Error error](httpCli *HTTPCli, uri string) *Endpoint[Request, Response, Credits, Error]

NewEndpoint creates a new endpoint instance with the specified HTTP client and URI.

func (Endpoint[Request, Response, Credits, ErrorResponse]) Call added in v1.0.0 

func (endpoint Endpoint[Request, Response, Credits, ErrorResponse]) Call(req Request) (resp Response, creds response.Credits, err Error)

Call executes the endpoint request and returns the response, credits, and any errors.

type ErrImplError added in v1.0.0 

type ErrImplError[Err error] struct {
	// contains filtered or unexported fields
}

ErrImplError represents a generic error implementation with type safety.

func NewError added in v1.0.0 

func NewError[T error](err error, t T) ErrImplError[T]

NewError creates a new generic error wrapper.

func (ErrImplError[Err]) Error added in v1.0.0 

func (e ErrImplError[Err]) Error() string

func (ErrImplError[Err]) Unwrap added in v1.0.0 

func (e ErrImplError[Err]) Unwrap() error

type Error added in v1.0.0 

type Error interface {
	Error() string
}

Error represents a generic error interface.

type EventChannel added in v1.0.0 

type EventChannel[T any] struct {
	// contains filtered or unexported fields
}

EventChannel provides a generic, thread-safe event channel with graceful closing. It follows Go best practices: the creator (owner) is responsible for closing the channel.

func NewEventChannel added in v1.0.0 

func NewEventChannel[T any](size int) *EventChannel[T]

NewEventChannel creates a new generic event channel with the specified buffer size.

func (*EventChannel[T]) Channel added in v1.0.0 

func (ec *EventChannel[T]) Channel() <-chan T

Channel returns a read-only channel for consuming events. Consumers can range over this channel safely, as it will be closed when the EventChannel is closed.

func (*EventChannel[T]) Close added in v1.0.0 

func (ec *EventChannel[T]) Close()

Close closes the event channel safely. Can be called multiple times. This method should only be called by the channel owner.

func (*EventChannel[T]) IsClosed added in v1.0.0 

func (ec *EventChannel[T]) IsClosed() bool

IsClosed returns true if the channel has been closed.

func (*EventChannel[T]) Send added in v1.0.0 

func (ec *EventChannel[T]) Send(ctx context.Context, event T) bool

Send attempts to send an event to the channel in a non-blocking way. Returns true if the event was sent successfully, false otherwise. This method respects context cancellation and channel closure.

type Fundamentals 

type Fundamentals struct {
	LogoURL                        string `default:"/logo"                    json:"logo_url"`
	ProfileURL                     string `default:"/profile"                 json:"profile_url"`
	DividendsURL                   string `default:"/dividends"               json:"dividends_url"`
	DividendsCalendarURL           string `default:"/dividends_calendar"      json:"dividends_calendar_url"`
	EarningsURL                    string `default:"/earnings"                json:"earnings_url"`
	EarningsCalendarURL            string `default:"/earnings_calendar"       json:"earnings_calendar_url"`
	IPOCalendarURL                 string `default:"/ipo_calendar"            json:"ipo_calendar_url"`
	SplitsURL                      string `default:"/splits"                  json:"splits_url"`
	SplitsCalendarURL              string `default:"/splits_calendar"         json:"splits_calendar_url"`
	StatisticsURL                  string `default:"/statistics"              json:"statistics_url"`
	PressReleasesURL               string `default:"/press_releases"          json:"press_releases_url"`
	IncomeStatementURL             string `default:"/income_statement"        json:"income_statement_url"`
	IncomeStatementConsolidatedURL string `default:"/income_statement/consolidated" json:"income_statement_consolidated_url"`
	BalanceSheetURL                string `default:"/balance_sheet"           json:"balance_sheet_url"`
	BalanceSheetConsolidatedURL    string `default:"/balance_sheet/consolidated" json:"balance_sheet_consolidated_url"`
	CashFlowURL                    string `default:"/cash_flow"               json:"cash_flow_url"`
	CashFlowConsolidatedURL        string `default:"/cash_flow/consolidated" json:"cash_flow_consolidated_url"`
	KeyExecutivesURL               string `default:"/key_executives"          json:"key_executives_url"`
	MarketCapURL                   string `default:"/market_cap"              json:"market_cap_url"`
	LastChangeURL                  string `default:"/last_change/{endpoint}"  json:"last_change_url"`
}

Fundamentals contains URL configurations for fundamental data endpoints including company profiles, press releases, financial statements, dividends, splits, and other corporate data. nolint: lll

type HTTPCli 

type HTTPCli struct {
	// contains filtered or unexported fields
}

HTTPCli represents an HTTP client wrapper for API requests.

func NewHTTPCli 

func NewHTTPCli(transport *fasthttp.Client, cfg *Conf, logger *zerolog.Logger) *HTTPCli

NewHTTPCli creates a new HTTP client with the specified transport, configuration, and logger.

type HTTPError added in v1.0.0 

type HTTPError struct {
	StatusCode int
	Message    string
	Body       []byte
	URL        string // request URL that failed
	Cause      error  // underlying error that caused this HTTP error
}

HTTPError represents HTTP-related errors with status codes.

func (HTTPError) Error added in v1.0.0 

func (e HTTPError) Error() string

func (HTTPError) Unwrap added in v1.0.0 

func (e HTTPError) Unwrap() error

Unwrap returns the underlying cause if this HTTPError wraps another error.

type InsufficientCreditsError added in v1.0.0 

type InsufficientCreditsError struct {
	Required  int64
	Available int64
	Message   string
	Cause     error
}

InsufficientCreditsError represents errors when user has insufficient API credits.

func (InsufficientCreditsError) Error added in v1.0.0 

func (e InsufficientCreditsError) Error() string

func (InsufficientCreditsError) Unwrap added in v1.0.0 

func (e InsufficientCreditsError) Unwrap() error

type InternalServerError added in v1.0.0 

type InternalServerError struct {
	HTTPError
	APIError *response.Error
}

InternalServerError represents 500 Internal Server errors.

func (InternalServerError) Error added in v1.0.0 

func (e InternalServerError) Error() string

type MutualFunds added in v1.0.0 

type MutualFunds struct {
	MutualFundsDirectoryURL      string `default:"/mutual_funds/list"               json:"mutual_funds_directory_url"`
	MutualFundsFullDataURL       string `default:"/mutual_funds/world"              json:"mutual_funds_full_data_url"`
	MutualFundsSummaryURL        string `default:"/mutual_funds/world/summary"      json:"mutual_funds_summary_url"`
	MutualFundsPerformanceURL    string `default:"/mutual_funds/world/performance"  json:"mutual_funds_performance_url"`
	MutualFundsRiskURL           string `default:"/mutual_funds/world/risk"         json:"mutual_funds_risk_url"`
	MutualFundsRatingsURL        string `default:"/mutual_funds/world/ratings"      json:"mutual_funds_ratings_url"`
	MutualFundsCompositionURL    string `default:"/mutual_funds/world/composition"  json:"mutual_funds_composition_url"`
	MutualFundsPurchaseInfoURL   string `default:"/mutual_funds/world/purchase_info" json:"mutual_funds_purchase_info_url"`
	MutualFundsSustainabilityURL string `default:"/mutual_funds/world/sustainability" json:"mutual_funds_sustainability_url"`
	MutualFundsFamiliesURL       string `default:"/mutual_funds/family"             json:"mutual_funds_families_url"`
	MutualFundsTypesURL          string `default:"/mutual_funds/type"               json:"mutual_funds_types_url"`
}

MutualFunds contains URL configurations for mutual fund-related endpoints including directory, performance, and ratings. nolint: lll

type NetworkError added in v1.0.0 

type NetworkError struct {
	Message string
	Cause   error
}

NetworkError represents network connectivity errors.

func (NetworkError) Error added in v1.0.0 

func (e NetworkError) Error() string

func (NetworkError) Unwrap added in v1.0.0 

func (e NetworkError) Unwrap() error

type NotFoundError added in v1.0.0 

type NotFoundError struct {
	HTTPError
	APIError *response.Error
}

NotFoundError represents 404 Not Found errors.

func (NotFoundError) Error added in v1.0.0 

func (e NotFoundError) Error() string

type PlanLimitationError added in v1.0.0 

type PlanLimitationError struct {
	Feature string
	Plan    string
	Message string
	Cause   error
}

PlanLimitationError represents errors when a feature is not available with the current plan.

func (PlanLimitationError) Error added in v1.0.0 

func (e PlanLimitationError) Error() string

func (PlanLimitationError) Unwrap added in v1.0.0 

func (e PlanLimitationError) Unwrap() error

type ReferenceData 

type ReferenceData struct {
	// Asset Catalogs
	StocksURL           string `default:"/stocks"           json:"stocks_url"`
	ForexPairsURL       string `default:"/forex_pairs"      json:"forex_pairs_url"`
	CryptocurrenciesURL string `default:"/cryptocurrencies" json:"cryptocurrencies_url"`
	ETFsURL             string `default:"/etfs"             json:"etfs_url"`
	FundsURL            string `default:"/funds"            json:"funds_url"`
	CommoditiesURL      string `default:"/commodities"      json:"commodities_url"`
	BondsURL            string `default:"/bonds"            json:"bonds_url"`

	// Discovery
	SymbolSearchURL      string `default:"/symbol_search"      json:"symbol_search_url"`
	CrossListingsURL     string `default:"/cross_listings"     json:"cross_listings_url"`
	EarliestTimestampURL string `default:"/earliest_timestamp" json:"earliest_timestamp_url"`

	// Markets
	ExchangesURL               string `default:"/exchanges"                json:"exchange_url"`
	ExchangeScheduleURL        string `default:"/exchange_schedule"        json:"exchange_schedule_url"`
	CryptocurrencyExchangesURL string `default:"/cryptocurrency_exchanges" json:"cryptocurrency_exchanges_url"`
	MarketStateURL             string `default:"/market_state"             json:"market_state_url"`

	// Supporting Metadata
	CountriesURL           string `default:"/countries"            json:"countries_url"`
	InstrumentTypeURL      string `default:"/instrument_type"      json:"instrument_type_url"`
	TechnicalIndicatorsURL string `default:"/technical_indicators" json:"technical_indicators_url"`
}

ReferenceData contains URL configurations for reference data endpoints including asset catalogs, discovery tools, market information, and supporting metadata. nolint: lll

type Regulatory added in v1.0.0 

type Regulatory struct {
	EDGARFilingsURL         string `default:"/edgar_filings/archive"        json:"edgar_filings_url"`
	InsiderTransactionsURL  string `default:"/insider_transactions"  json:"insider_transactions_url"`
	InstitutionalHoldersURL string `default:"/institutional_holders" json:"institutional_holders_url"`
	FundHoldersURL          string `default:"/fund_holders"          json:"fund_holders_url"`
	DirectHoldersURL        string `default:"/direct_holders"        json:"direct_holders_url"`
	TaxInformationURL       string `default:"/tax_info"            json:"tax_information_url"`
	SanctionedEntitiesURL   string `default:"/sanctions/{source}"  json:"sanctioned_entities_url"`
}

Regulatory contains URL configurations for regulatory and compliance endpoints including filings and ownership data. nolint: lll

type RequestBodyer added in v1.0.0 

type RequestBodyer interface {
	Body() (any, string, error)
}

RequestBodyer allows a request to provide a JSON body and content type.

type RequestHeaderer added in v1.0.0 

type RequestHeaderer interface {
	Headers() map[string]string
}

RequestHeaderer allows a request to define custom headers.

type RequestMethoder added in v1.0.0 

type RequestMethoder interface {
	Method() string
}

RequestMethoder allows a request to override the HTTP method.

type RequestPather added in v1.0.0 

type RequestPather interface {
	PathParams() map[string]string
}

RequestPather allows a request to provide URL path parameters.

type RequestQueryer added in v1.0.0 

type RequestQueryer interface {
	Query() (url.Values, error)
}

RequestQueryer allows a request to build custom query parameters.

type RequestRawBodyer added in v1.0.0 

type RequestRawBodyer interface {
	RawBody() ([]byte, string, error)
}

RequestRawBodyer allows a request to provide raw body bytes and content type.

type SymbolNotFoundError added in v1.0.0 

type SymbolNotFoundError struct {
	Symbol  string
	Message string
	Cause   error
}

SymbolNotFoundError represents errors when a requested symbol is not found.

func (SymbolNotFoundError) Error added in v1.0.0 

func (e SymbolNotFoundError) Error() string

func (SymbolNotFoundError) Unwrap added in v1.0.0 

func (e SymbolNotFoundError) Unwrap() error

type TechnicalIndicatorTestArgs added in v1.0.0 

type TechnicalIndicatorTestArgs[T any] struct {
	// contains filtered or unexported fields
}

TechnicalIndicatorTestArgs represents common test arguments for technical indicators.

type TechnicalIndicatorTestCase added in v1.0.0 

type TechnicalIndicatorTestCase[T any, R any] struct {
	// contains filtered or unexported fields
}

TechnicalIndicatorTestCase represents a common test case structure for technical indicators.

type TechnicalIndicators added in v1.0.0 

type TechnicalIndicators struct {
	// Overlap Studies
	BbandsURL string `default:"/bbands" json:"bbands_url"`
	SMAURL    string `default:"/sma" json:"sma_url"`
	EMAURL    string `default:"/ema" json:"ema_url"`
	MAURL     string `default:"/ma" json:"ma_url"`
	WMAURL    string `default:"/wma" json:"wma_url"`
	VWAPURL   string `default:"/vwap" json:"vwap_url"`
	DEMAURL   string `default:"/dema" json:"dema_url"`
	TEMAURL   string `default:"/tema" json:"tema_url"`
	TRMAURL   string `default:"/trima" json:"trima_url"`
	KAMAURL   string `default:"/kama" json:"kama_url"`
	SARURL    string `default:"/sar" json:"sar_url"`

	// Momentum Indicators
	ADXURL       string `default:"/adx" json:"adx_url"`
	MACDURL      string `default:"/macd" json:"macd_url"`
	RSIURL       string `default:"/rsi" json:"rsi_url"`
	StochURL     string `default:"/stoch" json:"stoch_url"`
	PercentBURL  string `default:"/percent_b" json:"percent_b_url"`
	CCIURL       string `default:"/cci" json:"cci_url"`
	WilliamsRURL string `default:"/willr" json:"williams_r_url"`
	ROCURL       string `default:"/roc" json:"roc_url"`
	MomURL       string `default:"/mom" json:"mom_url"`

	// Volume Indicators
	OBVURL string `default:"/obv" json:"obv_url"`
	ADURL  string `default:"/ad" json:"ad_url"`

	// Volatility Indicators
	ATRURL  string `default:"/atr" json:"atr_url"`
	NATRURL string `default:"/natr" json:"natr_url"`
	TRURL   string `default:"/trange" json:"trange_url"`
}

TechnicalIndicators contains URL configurations for technical indicator endpoints including overlapping studies, momentum indicators, volume indicators, and volatility indicators. nolint: lll

type TimeoutError added in v1.0.0 

type TimeoutError struct {
	Message string
}

TimeoutError represents request timeout errors.

func (TimeoutError) Error added in v1.0.0 

func (e TimeoutError) Error() string

type TooManyRequestsError added in v1.0.0 

type TooManyRequestsError struct {
	HTTPError
	APIError *response.Error
}

TooManyRequestsError represents 429 Rate Limit errors.

func (TooManyRequestsError) Error added in v1.0.0 

func (e TooManyRequestsError) Error() string

type UnauthorizedError added in v1.0.0 

type UnauthorizedError struct {
	HTTPError
	APIError *response.Error
}

UnauthorizedError represents 401 Unauthorized errors.

func (UnauthorizedError) Error added in v1.0.0 

func (e UnauthorizedError) Error() string

type WS 

type WS struct {
	// contains filtered or unexported fields
}

WS represents a WebSocket client for real-time price data streaming from the Twelve Data API. It supports comprehensive WebSocket functionality including subscription management, heartbeat handling, and multiple event types with graceful shutdown.

func NewWS 

func NewWS(cfg *Conf, logger *zerolog.Logger, dialer *websocket.Dialer) *WS

NewWS creates a new WebSocket client instance configured for the Twelve Data API. If dialer is nil, the default WebSocket dialer will be used. The client uses generic event channels for type-safe event handling.

func (*WS) Close added in v1.0.0 

func (ws *WS) Close() error

Close gracefully closes the WebSocket connection and stops all goroutines. It follows Go best practices for clean shutdown with timeout and proper resource cleanup.

func (*WS) Connect added in v1.0.0 

func (ws *WS) Connect(ctx context.Context) error

Connect establishes a WebSocket connection and starts message handling. It uses errgroup for proper goroutine lifecycle management and graceful shutdown.

func (*WS) Consume 

func (ws *WS) Consume() <-chan response.WSPriceEvent

Consume returns a read-only channel for receiving price events (legacy method for backward compatibility). The channel will be closed when the WebSocket connection is terminated.

func (*WS) ConsumeErrorEvents added in v1.0.0 

func (ws *WS) ConsumeErrorEvents() <-chan response.WSErrorEvent

ConsumeErrorEvents returns a read-only channel for receiving error events. The channel will be closed when the WebSocket connection is terminated.

func (*WS) ConsumePriceEvents added in v1.0.0 

func (ws *WS) ConsumePriceEvents() <-chan response.WSPriceEvent

ConsumePriceEvents returns a read-only channel for receiving price events. The channel will be closed when the WebSocket connection is terminated.

func (*WS) ConsumeStatusEvents added in v1.0.0 

func (ws *WS) ConsumeStatusEvents() <-chan response.WSSubscribeStatusEvent

ConsumeStatusEvents returns a read-only channel for receiving subscription status events. The channel will be closed when the WebSocket connection is terminated.

func (*WS) IsClosed added in v1.0.0 

func (ws *WS) IsClosed() bool

IsClosed returns true if the WebSocket has been closed.

func (*WS) IsConnected added in v1.0.0 

func (ws *WS) IsConnected() bool

IsConnected returns true if the WebSocket is connected.

func (*WS) Reset added in v1.0.0 

func (ws *WS) Reset() error

Reset clears all current subscriptions.

func (*WS) SendHeartbeat added in v1.0.0 

func (ws *WS) SendHeartbeat() error

SendHeartbeat sends a heartbeat message to maintain connection stability.

func (*WS) Subscribe 

func (ws *WS) Subscribe(symbols []string) error

Subscribe subscribes to price events for the specified symbols. Supports both simple string format and extended format with exchange parameters.

func (*WS) SubscribeExtended added in v1.0.0 

func (ws *WS) SubscribeExtended(symbols []request.WSSymbolExtended) error

SubscribeExtended subscribes to price events using extended symbol format.

func (*WS) Unsubscribe added in v1.0.0 

func (ws *WS) Unsubscribe(symbols []string) error

Unsubscribe removes subscriptions for the specified symbols.

func (*WS) UnsubscribeExtended added in v1.0.0 

func (ws *WS) UnsubscribeExtended(symbols []request.WSSymbolExtended) error

UnsubscribeExtended removes subscriptions using extended symbol format.

type WSConnectionError added in v1.0.0 

type WSConnectionError struct {
	URL     string
	Message string
	Cause   error
}

WSConnectionError represents WebSocket connection errors.

func (WSConnectionError) Error added in v1.0.0 

func (e WSConnectionError) Error() string

func (WSConnectionError) Unwrap added in v1.0.0 

func (e WSConnectionError) Unwrap() error

type WSMessageError added in v1.0.0 

type WSMessageError struct {
	Message string
	Data    []byte
	Cause   error
}

WSMessageError represents WebSocket message handling errors.

func (WSMessageError) Error added in v1.0.0 

func (e WSMessageError) Error() string

func (WSMessageError) Unwrap added in v1.0.0 

func (e WSMessageError) Unwrap() error

type WSSubscriptionError added in v1.0.0 

type WSSubscriptionError struct {
	Symbols []string
	Message string
	Cause   error
}

WSSubscriptionError represents WebSocket subscription errors.

func (WSSubscriptionError) Error added in v1.0.0 

func (e WSSubscriptionError) Error() string

func (WSSubscriptionError) Unwrap added in v1.0.0 

func (e WSSubscriptionError) Unwrap() error

type WebSocket 

type WebSocket struct {
	PriceURL string `default:"/v1/quotes/price" json:"ws_price_url"`
}

WebSocket contains URL configurations for WebSocket endpoints used for real-time data streaming.

Source Files

View all Source files

Directories

Path Synopsis
Package dictionary contains constant definitions used throughout the Twelve Data API client, including API credit costs for various endpoints and other shared constants.
 Package dictionary contains constant definitions used throughout the Twelve Data API client, including API credit costs for various endpoints and other shared constants.
examples module
error_handling command
Package main demonstrates comprehensive error handling patterns for the Twelve Data API client.
 Package main demonstrates comprehensive error handling patterns for the Twelve Data API client.
etf_example command
Package main demonstrates how to retrieve ETF data using the Twelve Data API.
 Package main demonstrates how to retrieve ETF data using the Twelve Data API.
ws_example command
Package main demonstrates WebSocket usage for real-time market data streaming.
 Package main demonstrates WebSocket usage for real-time market data streaming.
Package request contains structures for API request parameters
 Package request contains structures for API request parameters
Package response contains all response structures for Twelve Data API endpoints.
 Package response contains all response structures for Twelve Data API endpoints.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.