-
Notifications
You must be signed in to change notification settings - Fork 1
Symbol and Market Metadata
- Introduction
- Core Symbol Metadata Structure
- Symbol Resolution and Search
- Market Structure Configuration
- Instrument Type Configuration
- Advanced Symbol Properties
- Integration with Third-Party Metadata APIs
- Common Configuration Issues
- Conclusion
This document provides comprehensive guidance on managing symbol metadata and market structure within custom datafeeds for TradingView integration. It details the implementation of the TVLibrarySymbolInfo class and related components that define instrument properties such as ticker, type, exchange, currency, and supported resolutions. The documentation covers the search_symbols method implementation for symbol lookup functionality, advanced fields for accurate chart rendering, and configuration examples for various instrument types including forex, crypto, and stocks. It also addresses integration with external metadata sources and common configuration issues that can affect widget display.
The TVLibrarySymbolInfo class serves as the central structure for defining comprehensive symbol metadata in the TradingView datafeed system. This class contains all required and optional fields necessary to properly configure a trading instrument within the TradingView interface.
classDiagram
class TVLibrarySymbolInfo {
+string name
+string description
+string type
+string session
+string exchange
+string listed_exchange
+Timezone timezone
+SeriesFormat format
+int pricescale
+int minmov
+string ticker
+bool fractional
+bool has_intraday
+ResolutionString[] supported_resolutions
+string currency_code
+string sector
+string industry
+resolve() : TVLibrarySymbolInfo
}
class TVSearchSymbolResultItem {
+string symbol
+string description
+string exchange
+string type
+string ticker
+string[] logo_urls
+string exchange_logo
}
TVLibrarySymbolInfo --> TVSearchSymbolResultItem : "converts to"
The symbol search and resolution process is implemented through the searchSymbols and resolveSymbol methods defined in the TVIDatafeedChartApi interface. These methods enable users to search for symbols within the TradingView interface and resolve symbol names to their complete metadata definitions.
sequenceDiagram
participant User as "TradingView User"
participant Interface as "TVIDatafeedChartApi"
participant Datafeed as "TVDatafeed"
participant Result as "TVSearchSymbolResultItem"
User->>Interface : searchSymbols(userInput, exchange, symbolType)
Interface->>Datafeed : searchSymbols(userInput, exchange, symbolType, onResult)
Datafeed->>Datafeed : Process search query
alt Symbols Found
Datafeed->>Datafeed : Create TVSearchSymbolResultItem objects
Datafeed->>Interface : onResult(results)
Interface->>User : Display search results
else No Symbols Found
Datafeed->>Interface : onResult([])
Interface->>User : Display no results
end
User->>Interface : resolveSymbol(symbolName)
Interface->>Datafeed : resolveSymbol(symbolName, onResolve, onError)
Datafeed->>Datafeed : Retrieve symbol metadata
alt Symbol Resolved
Datafeed->>Datafeed : Create TVLibrarySymbolInfo object
Datafeed->>Interface : onResolve(symbolInfo)
Interface->>User : Display chart with resolved symbol
else Symbol Not Found
Datafeed->>Interface : onError("Symbol not found")
Interface->>User : Display error message
end
Proper market structure configuration is essential for accurate chart rendering and trading session representation. The TVLibrarySymbolInfo class provides comprehensive fields for defining trading sessions, timezones, and resolution support.
flowchart TD
Start([Configure Market Structure]) --> SessionConfig["Define Trading Session"]
SessionConfig --> SessionFormat{"Session Format"}
SessionFormat --> |Regular| RegularSession["Format: HHMM-HHMM"]
SessionFormat --> |Extended| ExtendedSession["Format: HHMM-HHMM;HHMM-HHMM"]
SessionFormat --> |Complex| ComplexSession["Format: HHMM-HHMM+D"]
SessionConfig --> TimezoneConfig["Set Timezone"]
TimezoneConfig --> OlsonDB["Use OlsonDB Format"]
OlsonDB --> Example["Example: America/New_York"]
SessionConfig --> ResolutionConfig["Configure Resolutions"]
ResolutionConfig --> Intraday["has_intraday = True"]
ResolutionConfig --> Daily["has_daily = True"]
ResolutionConfig --> WeeklyMonthly["has_weekly_and_monthly = True"]
ResolutionConfig --> Supported["supported_resolutions"]
ResolutionConfig --> Multipliers["Set Multipliers"]
Multipliers --> IntradayMult["intraday_multipliers"]
Multipliers --> DailyMult["daily_multipliers"]
Multipliers --> WeeklyMult["weekly_multipliers"]
Multipliers --> MonthlyMult["monthly_multipliers"]
Start --> Result["Complete Market Configuration"]
Different instrument types require specific configuration parameters to ensure proper display and functionality within the TradingView interface. This section details the configuration requirements for forex, cryptocurrency, and stock instruments.
classDiagram
class ForexSymbol {
+string name : "EURUSD"
+string type : "forex"
+int pricescale : 5
+int minmov : 1
+bool fractional : false
+string format : "price"
+string currency_code : "USD"
+string[] logo_urls : ["eur.svg", "usd.svg"]
}
class CryptoSymbol {
+string name : "BTCUSDT"
+string type : "crypto"
+int pricescale : 2
+int minmov : 1
+bool fractional : false
+string format : "price"
+string currency_code : "USDT"
+string exchange : "BINANCE"
+bool has_seconds : true
+string[] seconds_multipliers : ["1", "5", "15"]
}
class StockSymbol {
+string name : "AAPL"
+string type : "stock"
+int pricescale : 2
+int minmov : 1
+bool fractional : true
+string format : "price"
+string currency_code : "USD"
+string exchange : "NASDAQ"
+string sector : "Technology"
+string industry : "Consumer Electronics"
+string session : "0930-1600"
+string timezone : "America/New_York"
}
class IndexSymbol {
+string name : "SPX"
+string type : "index"
+int pricescale : 2
+int minmov : 1
+bool fractional : false
+string format : "price"
+string currency_code : "USD"
+string exchange : "CBOE"
+string[] daily_multipliers : ["1", "5"]
+string[] weekly_multipliers : ["1"]
}
ForexSymbol --> TVLibrarySymbolInfo : "inherits"
CryptoSymbol --> TVLibrarySymbolInfo : "inherits"
StockSymbol --> TVLibrarySymbolInfo : "inherits"
IndexSymbol --> TVLibrarySymbolInfo : "inherits"
The TVLibrarySymbolInfo class supports numerous advanced properties that enable precise control over symbol display, price formatting, and data presentation in the TradingView widget.
erDiagram
TVLIBRARYSYMBOLINFO ||--o{ PRICE_FORMATTING : contains
TVLIBRARYSYMBOLINFO ||--o{ SESSION_CONFIGURATION : contains
TVLIBRARYSYMBOLINFO ||--o{ DISPLAY_CONFIGURATION : contains
TVLIBRARYSYMBOLINFO ||--o{ DATA_STATUS : contains
TVLIBRARYSYMBOLINFO ||--o{ CLASSIFICATION : contains
TVLIBRARYSYMBOLINFO ||--o{ CURRENCY_CONVERSION : contains
PRICE_FORMATTING {
bool fractional
int minmove2
dict variable_tick_size
int volume_precision
}
SESSION_CONFIGURATION {
string session_display
string session_holidays
string corrections
string subsession_id
list subsessions
}
DISPLAY_CONFIGURATION {
bool has_empty_bars
string visible_plots_set
}
DATA_STATUS {
string data_status
int delay
bool expired
date expiration_date
}
CLASSIFICATION {
string sector
string industry
}
CURRENCY_CONVERSION {
string currency_code
string original_currency_code
string unit_id
string original_unit_id
list unit_conversion_types
}
Integrating with third-party metadata APIs allows for dynamic population of symbol information and ensures that the datafeed maintains up-to-date instrument metadata.
sequenceDiagram
participant Datafeed as "TVDatafeed"
participant MetadataAPI as "Third-Party API"
participant Cache as "Local Cache"
participant TradingView as "TradingView Widget"
TradingView->>Datafeed : searchSymbols("AAPL", "NASDAQ", "stock")
Datafeed->>Cache : Check cached symbols
alt Symbol in Cache
Cache->>Datafeed : Return cached results
Datafeed->>TradingView : Return search results
else Symbol not in Cache
Datafeed->>MetadataAPI : Request symbol metadata
MetadataAPI->>MetadataAPI : Validate and process request
alt API Success
MetadataAPI->>Datafeed : Return symbol data
Datafeed->>Cache : Store in cache
Datafeed->>TradingView : Return search results
else API Error
MetadataAPI->>Datafeed : Return error
Datafeed->>Datafeed : Use fallback data
Datafeed->>TradingView : Return results with warning
end
end
TradingView->>Datafeed : resolveSymbol("AAPL")
Datafeed->>Cache : Retrieve symbol info
Datafeed->>Datafeed : Enhance with local configuration
Datafeed->>TradingView : Return TVLibrarySymbolInfo
Several common configuration issues can lead to display errors or incorrect behavior in the TradingView widget. This section identifies these issues and provides guidance for resolution.
flowchart TD
Start([Common Issues]) --> ResolutionIssue["Incorrect Resolution Mapping"]
ResolutionIssue --> CheckSupported["Verify supported_resolutions"]
CheckSupported --> DefineMultipliers["Set proper multipliers"]
DefineMultipliers --> TestResolutions["Test all resolution levels"]
Start --> SessionIssue["Invalid Session Configuration"]
SessionIssue --> ValidateFormat["Validate session string format"]
ValidateFormat --> CheckTimezone["Verify timezone setting"]
CheckTimezone --> TestHours["Test trading hours display"]
Start --> CurrencyIssue["Currency Mismatch"]
CurrencyIssue --> VerifyCode["Check currency_code"]
VerifyCode --> MatchFormat["Ensure format matches currency"]
MatchFormat --> TestDisplay["Test price display"]
Start --> PrecisionIssue["Price Precision Errors"]
PrecisionIssue --> CheckPricescale["Verify pricescale value"]
PrecisionIssue --> CheckMinmov["Verify minmov setting"]
PrecisionIssue --> CheckFractional["Validate fractional flag"]
PrecisionIssue --> TestRounding["Test price rounding"]
Start --> DataStatusIssue["Incorrect Data Status"]
DataStatusIssue --> VerifyStatus["Check data_status field"]
DataStatusIssue --> SetDelay["Properly configure delay"]
DataStatusIssue --> TestStreaming["Test data streaming behavior"]
Start --> Result["Resolved Configuration"]
Proper management of symbol metadata and market structure is critical for creating a functional and accurate TradingView datafeed implementation. The TVLibrarySymbolInfo class provides a comprehensive framework for defining instrument properties, while the searchSymbols and resolveSymbol methods enable effective symbol discovery and resolution. By correctly configuring market structure parameters such as trading sessions, timezones, resolutions, and price formatting, developers can ensure accurate chart rendering and optimal user experience. Integration with third-party metadata APIs allows for dynamic updates and maintenance of current instrument information. Attention to common configuration issues such as resolution mapping, session configuration, and currency settings helps prevent display errors and ensures reliable widget performance.