utils
Package utils provides utility functions for go-yfinance.
Overview
The utils package contains helper functions for common operations such as timezone handling, MIC code mapping, and exchange-specific utilities.
MIC Code Mapping \(v1.1.0\)
ISO 10383 Market Identifier Code (MIC) to Yahoo Finance suffix mapping:
suffix := utils.GetYahooSuffix("XLON") // Returns "L"
mic := utils.GetMIC("T") // Returns "XTKS"
ticker := utils.FormatYahooTicker("7203", "XTKS") // Returns "7203.T"
base, suffix := utils.ParseYahooTicker("AAPL.L") // Returns "AAPL", "L"
Check if an exchange is US-based:
List all supported exchanges:
mics := utils.AllMICs() // []string{"XNYS", "XNAS", "XLON", ...}
suffixes := utils.AllYahooSuffixes() // []string{"", "L", "T", ...}
Timezone Functions
Exchange timezone lookup:
tz := utils.GetTimezone("NYQ") // Returns "America/New_York"
tz := utils.GetTimezone("TYO") // Returns "Asia/Tokyo"
Timezone validation and conversion:
if utils.IsValidTimezone("America/New_York") {
loc := utils.LoadLocation("America/New_York")
t := utils.ConvertToTimezone(time.Now(), "America/New_York")
}
Exchange Mappings
The package includes timezone mappings for major exchanges:
- US: NYSE (NYQ), NASDAQ (NMS, NGM, NCM), BATS, OTC
- Europe: London (LSE), Frankfurt (FRA), Paris (PAR), etc.
- Asia: Tokyo (TYO), Hong Kong (HKG), Shanghai (SHH), etc.
- Others: TSX (Toronto), ASX (Sydney), etc.
Market Hours
Basic market hours check (simplified, no holiday support):
Thread Safety
All utility functions are thread-safe.
Index
- Variables
- func AllMICs() []string
- func AllYahooSuffixes() []string
- func CacheTimezone(exchange, timezone string)
- func ConvertToTimezone(t time.Time, timezone string) time.Time
- func FormatYahooTicker(baseTicker, mic string) string
- func GetMIC(suffix string) string
- func GetTimezone(exchange string) string
- func GetYahooSuffix(mic string) string
- func IsUSExchange(mic string) bool
- func IsValidTimezone(name string) bool
- func LoadLocation(name string) *time.Location
- func MarketIsOpen(exchange string) bool
- func ParseTimestamp(timestamp int64, timezone string) time.Time
- func ParseYahooTicker(ticker string) (baseTicker, suffix string)
Variables
MICToYahooSuffix maps ISO 10383 Market Identifier Codes (MIC) to Yahoo Finance ticker suffixes. This allows converting standard exchange codes to the format used by Yahoo Finance.
Reference:
- Yahoo Finance suffixes: https://help.yahoo.com/kb/finance-for-web/SLN2310.html
- ISO 10383 MIC codes: https://www.iso20022.org/market-identifier-codes
Example: "XLON" (London Stock Exchange) maps to "L", so AAPL traded on LSE would be "AAPL.L"
var MICToYahooSuffix = map[string]string{
"XCBT": "CBT",
"XCME": "CME",
"IFUS": "NYB",
"CECS": "CMX",
"XNYM": "NYM",
"XNYS": "",
"XNAS": "",
"XBUE": "BA",
"XVIE": "VI",
"XASX": "AX",
"XAUS": "XA",
"XBRU": "BR",
"BVMF": "SA",
"CNSX": "CN",
"NEOE": "NE",
"XTSE": "TO",
"XTSX": "V",
"XSGO": "SN",
"XSHG": "SS",
"XSHE": "SZ",
"XBOG": "CL",
"XPRA": "PR",
"XCSE": "CO",
"XCAI": "CA",
"XTAL": "TL",
"CEUX": "XD",
"XEUR": "NX",
"XHEL": "HE",
"XPAR": "PA",
"XBER": "BE",
"XBMS": "BM",
"XDUS": "DU",
"XFRA": "F",
"XHAM": "HM",
"XHAN": "HA",
"XMUN": "MU",
"XSTU": "SG",
"XETR": "DE",
"XATH": "AT",
"XHKG": "HK",
"XBUD": "BD",
"XICE": "IC",
"XBOM": "BO",
"XNSE": "NS",
"XIDX": "JK",
"XDUB": "IR",
"XTAE": "TA",
"MTAA": "MI",
"EUTL": "TI",
"XTKS": "T",
"XKFE": "KW",
"XRIS": "RG",
"XVIL": "VS",
"XKLS": "KL",
"XMEX": "MX",
"XAMS": "AS",
"XNZE": "NZ",
"XOSL": "OL",
"XPHS": "PS",
"XWAR": "WA",
"XLIS": "LS",
"XQAT": "QA",
"XBSE": "RO",
"XSES": "SI",
"XJSE": "JO",
"XKRX": "KS",
"KQKS": "KQ",
"BMEX": "MC",
"XSAU": "SR",
"XSTO": "ST",
"XSWX": "SW",
"ROCO": "TWO",
"XTAI": "TW",
"XBKK": "BK",
"XIST": "IS",
"XDFM": "AE",
"AQXE": "AQ",
"XCHI": "XC",
"XLON": "L",
"ILSE": "IL",
"XCAR": "CR",
"XSTC": "VN",
}
YahooSuffixToMIC is the reverse mapping from Yahoo Finance suffix to MIC code. Note: Some Yahoo suffixes may map to multiple MIC codes. In such cases, the primary/most common exchange is used.
func AllMICs
AllMICs returns all supported MIC codes.
func AllYahooSuffixes
AllYahooSuffixes returns all supported Yahoo Finance suffixes (excluding empty for US).
func CacheTimezone
CacheTimezone stores a timezone for an exchange in the cache.
func ConvertToTimezone
ConvertToTimezone converts a UTC time to the specified timezone.
func FormatYahooTicker
FormatYahooTicker formats a base ticker symbol with the appropriate Yahoo Finance suffix for the given MIC code.
Example:
FormatYahooTicker("AAPL", "XLON") returns "AAPL.L"
FormatYahooTicker("AAPL", "XNYS") returns "AAPL" (no suffix for US)
func GetMIC
GetMIC returns the MIC code for a given Yahoo Finance ticker suffix. Returns an empty string if the suffix is not found.
func GetTimezone
GetTimezone returns the timezone for a given exchange code. It first checks the cache, then falls back to the known exchange timezones. Returns "America/New_York" as default if exchange is unknown.
func GetYahooSuffix
GetYahooSuffix returns the Yahoo Finance ticker suffix for a given MIC code. Returns an empty string if the MIC code is not found or maps to a US exchange.
func IsUSExchange
IsUSExchange returns true if the MIC code represents a US exchange.
func IsValidTimezone
IsValidTimezone checks if a timezone name is valid.
func LoadLocation
LoadLocation loads a timezone location by name. Returns nil if the timezone is invalid.
func MarketIsOpen
MarketIsOpen checks if a market is currently open based on typical trading hours. This is a simplified check and doesn't account for holidays.
func ParseTimestamp
ParseTimestamp parses a Unix timestamp and converts to the specified timezone.
func ParseYahooTicker
ParseYahooTicker parses a Yahoo Finance ticker into base ticker and suffix.
Example: