fundamental

package
v0.24.2 Latest Latest
Warning

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

Go to latest
Published: Jun 2, 2026 License: Apache-2.0, MIT Imports: 13 Imported by: 0

Documentation

Overview

Package fundamental provides a client for the Longbridge Fundamental OpenAPI. It covers financial reports, analyst ratings, dividends, EPS forecasts, consensus estimates, valuation metrics, company overview, executives, shareholders, fund holders, corporate actions, investor relations, operating reports, buyback data, and stock ratings.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BusinessSegmentHistoryItem

type BusinessSegmentHistoryItem struct {
	// Segment name.
	Name string
	// Percentage of total.
	Percent string
	// Absolute value.
	Value string
}

BusinessSegmentHistoryItem is one business/regional segment entry in a historical snapshot.

type BusinessSegmentItem

type BusinessSegmentItem struct {
	// Segment name.
	Name string
	// Percentage of total revenue.
	Percent string
}

BusinessSegmentItem is one business segment entry (latest snapshot).

type BusinessSegments

type BusinessSegments struct {
	// Report date.
	Date string
	// Total revenue.
	Total string
	// Reporting currency.
	Currency string
	// Business segment breakdown.
	Business []BusinessSegmentItem
}

BusinessSegments is the response for FundamentalContext.BusinessSegments.

type BusinessSegmentsHistoricalItem

type BusinessSegmentsHistoricalItem struct {
	// Report date.
	Date string
	// Total revenue.
	Total string
	// Reporting currency.
	Currency string
	// Business segment breakdown.
	Business []BusinessSegmentHistoryItem
	// Regional breakdown.
	Regionals []BusinessSegmentHistoryItem
}

BusinessSegmentsHistoricalItem is one historical business segments snapshot.

type BusinessSegmentsHistory

type BusinessSegmentsHistory struct {
	// Historical snapshots.
	Historical []BusinessSegmentsHistoricalItem
}

BusinessSegmentsHistory is the response for FundamentalContext.BusinessSegmentsHistory.

type BuybackData

type BuybackData struct {
	// Most recent buyback summary (TTM).
	RecentBuybacks *RecentBuybacks
	// Historical annual buyback data.
	BuybackHistory []BuybackHistoryItem
	// Buyback payout and cash-flow ratios.
	BuybackRatios []BuybackRatios
}

BuybackData is the response for FundamentalContext.Buyback.

type BuybackHistoryItem

type BuybackHistoryItem struct {
	// Fiscal year label, e.g. "FY2024".
	FiscalYear string
	// Fiscal year date range string.
	FiscalYearRange string
	// Net buyback amount.
	NetBuyback *decimal.Decimal
	// Net buyback yield.
	NetBuybackYield *decimal.Decimal
	// Year-over-year net buyback growth rate.
	NetBuybackGrowthRate *decimal.Decimal
	// Reporting currency.
	Currency string
}

BuybackHistoryItem is one historical annual buyback data point.

type BuybackRatios

type BuybackRatios struct {
	// Net buyback payout ratio.
	NetBuybackPayoutRatio *decimal.Decimal
	// Net buyback to free cash-flow ratio.
	NetBuybackToCashflowRatio *decimal.Decimal
}

BuybackRatios holds buyback payout and cash-flow ratios.

type CompanyOverview

type CompanyOverview struct {
	// Short name, e.g. "腾讯控股".
	Name string
	// Full legal name.
	CompanyName string
	// Founding date.
	Founded string
	// Listing date.
	ListingDate string
	// Primary listing market display name.
	Market string
	// Market region code, e.g. "HK".
	Region string
	// Registered address.
	Address string
	// Principal office address.
	OfficeAddress string
	// Company website.
	Website string
	// IPO issue price.
	IssuePrice *decimal.Decimal
	// Number of shares offered at IPO.
	SharesOffered string
	// Chairman name.
	Chairman string
	// Company secretary name.
	Secretary string
	// Auditing institution.
	AuditInst string
	// Company classification category.
	Category string
	// Fiscal year end, e.g. "12 月 31 日".
	YearEnd string
	// Number of employees.
	Employees string
	// Phone number.
	Phone string
	// Fax number.
	Fax string
	// Investor relations email.
	Email string
	// Legal representative.
	LegalRepr string
	// CEO / Managing Director.
	Manager string
	// Business licence number.
	BusLicense string
	// Accounting firm.
	AccountingFirm string
	// Securities representative.
	SecuritiesRep string
	// Legal counsel.
	LegalCounsel string
	// Postal code.
	ZipCode string
	// Exchange ticker code, e.g. "00700".
	Ticker string
	// URL to the company's logo icon.
	Icon string
	// Business profile / description.
	Profile string
	// ADS ratio (may be empty).
	AdsRatio string
	// Industry sector code.
	Sector int32
}

CompanyOverview is the response for FundamentalContext.Company.

type ConsensusDetail

type ConsensusDetail struct {
	// Metric key, e.g. "revenue", "eps".
	Key string
	// Display name.
	Name string
	// Metric description.
	Description string
	// Actual reported value (nil if not yet released).
	Actual *decimal.Decimal
	// Consensus estimate value.
	Estimate *decimal.Decimal
	// Actual minus estimate.
	CompValue *decimal.Decimal
	// Beat/miss description, e.g. "超出预期".
	CompDesc string
	// Comparison result code for colour coding.
	Comp string
	// Whether the actual results have been published.
	IsReleased bool
}

ConsensusDetail is the consensus estimate for one financial metric.

type ConsensusReport

type ConsensusReport struct {
	// Fiscal year, e.g. 2025.
	FiscalYear int32
	// Fiscal period code, e.g. "Q4".
	FiscalPeriod string
	// Human-readable period label, e.g. "Q4 FY2025".
	PeriodText string
	// Per-metric consensus details.
	Details []ConsensusDetail
}

ConsensusReport is the consensus report for one fiscal period.

type CorpActionItem

type CorpActionItem struct {
	// Internal event ID.
	ID string
	// Date in YYYYMMDD format, e.g. "20260601".
	Date string
	// Short display date, e.g. "06.01".
	DateStr string
	// Date type label, e.g. "派息日", "除权日".
	DateType string
	// Time zone description, e.g. "北京时间".
	DateZone string
	// Event category, e.g. "分配方案".
	ActType string
	// Human-readable event description.
	ActDesc string
	// Machine-readable action code, e.g. "DividendExDate".
	Action string
	// Whether this is a recent event.
	Recent bool
	// Whether publication was delayed.
	IsDelay bool
	// Delay announcement content (if IsDelay is true).
	DelayContent string
	// Associated live stream (if any).
	Live *CorpActionLive
	// Associated security info (rarely populated; preserved as raw JSON).
	Security *json.RawMessage
}

CorpActionItem is one corporate action event.

type CorpActionLive

type CorpActionLive struct {
	// Live stream ID.
	ID string
	// Status (raw JSON; API may return int or string).
	// 1=preview, 2=live, 3=ended, 4=replay, 5=processing.
	Status json.RawMessage
	// Start time.
	StartedAt string
	// Stream title.
	Name string
	// Icon URL.
	Icon string
}

CorpActionLive is the live stream associated with a corporate action.

type CorpActions

type CorpActions struct {
	// Corporate action events.
	Items []CorpActionItem
}

CorpActions is the response for FundamentalContext.CorpAction.

type DividendItem

type DividendItem struct {
	// Security symbol, e.g. "700.HK".
	Symbol string
	// Internal record ID.
	ID string
	// Human-readable description, e.g. "每股派息 5.3 HKD".
	Desc string
	// Record / book-close date, e.g. "2026.05.18".
	RecordDate string
	// Ex-dividend date, e.g. "2026.05.15".
	ExDate string
	// Payment date, e.g. "2026.06.01".
	PaymentDate string
}

DividendItem is a single dividend / distribution event.

type DividendList

type DividendList struct {
	// List of dividend events.
	List []DividendItem
}

DividendList is the response for FundamentalContext.Dividend and FundamentalContext.DividendDetail.

type ExecutiveGroup

type ExecutiveGroup struct {
	// Security symbol.
	Symbol string
	// Link to the company wiki page.
	ForwardURL string
	// Total number of executives.
	Total int32
	// Individual executive entries.
	Professionals []Professional
}

ExecutiveGroup holds executives for one security.

type ExecutiveList

type ExecutiveList struct {
	// Groups of executives per security (usually one group).
	ProfessionalList []ExecutiveGroup
}

ExecutiveList is the response for FundamentalContext.Executive.

type FinancialConsensus

type FinancialConsensus struct {
	// Per-period consensus reports.
	List []ConsensusReport
	// Index into List of the most recently released period.
	CurrentIndex int32
	// Reporting currency, e.g. "HKD".
	Currency string
	// Available period types, e.g. ["qf", "saf", "af"].
	OptPeriods []string
	// Currently returned period type.
	CurrentPeriod string
}

FinancialConsensus is the response for FundamentalContext.Consensus.

type FinancialReportKind

type FinancialReportKind int

FinancialReportKind identifies which financial statement to fetch.

const (
	// FinancialReportKindIncomeStatement fetches the income statement.
	FinancialReportKindIncomeStatement FinancialReportKind = iota
	// FinancialReportKindBalanceSheet fetches the balance sheet.
	FinancialReportKindBalanceSheet
	// FinancialReportKindCashFlow fetches the cash flow statement.
	FinancialReportKindCashFlow
	// FinancialReportKindAll fetches all statements.
	FinancialReportKindAll
)

type FinancialReportPeriod

type FinancialReportPeriod int

FinancialReportPeriod identifies the reporting period.

const (
	// FinancialReportPeriodAnnual is the annual report ("af").
	FinancialReportPeriodAnnual FinancialReportPeriod = iota
	// FinancialReportPeriodSemiAnnual is the semi-annual report ("saf").
	FinancialReportPeriodSemiAnnual
	// FinancialReportPeriodQ1 is the Q1 report.
	FinancialReportPeriodQ1
	// FinancialReportPeriodQ2 is the Q2 report.
	FinancialReportPeriodQ2
	// FinancialReportPeriodQ3 is the Q3 report.
	FinancialReportPeriodQ3
	// FinancialReportPeriodQuarterlyFull is the full quarterly report ("qf").
	FinancialReportPeriodQuarterlyFull
	// FinancialReportPeriodThreeQ is the three-quarter report ("3q").
	FinancialReportPeriodThreeQ
)

type FinancialReportSnapshot

type FinancialReportSnapshot struct {
	// Company name.
	Name string
	// Ticker code.
	Ticker string
	// Fiscal period start date.
	FpStart string
	// Fiscal period end date.
	FpEnd string
	// Reporting currency.
	Currency string
	// Report description.
	ReportDesc string
	// Forecast revenue.
	FoRevenue *SnapshotForecastMetric
	// Forecast EBIT.
	FoEbit *SnapshotForecastMetric
	// Forecast EPS.
	FoEps *SnapshotForecastMetric
	// Reported revenue.
	FrRevenue *SnapshotReportedMetric
	// Reported net profit.
	FrProfit *SnapshotReportedMetric
	// Reported operating cash flow.
	FrOperateCash *SnapshotReportedMetric
	// Reported investing cash flow.
	FrInvestCash *SnapshotReportedMetric
	// Reported financing cash flow.
	FrFinanceCash *SnapshotReportedMetric
	// Reported total assets.
	FrTotalAssets *SnapshotReportedMetric
	// Reported total liabilities.
	FrTotalLiability *SnapshotReportedMetric
	// ROE TTM.
	FrRoeTtm string
	// Profit margin.
	FrProfitMargin string
	// Profit margin TTM.
	FrProfitMarginTtm string
	// Asset turnover TTM.
	FrAssetTurnTtm string
	// Leverage TTM.
	FrLeverageTtm string
	// Debt-to-assets ratio.
	FrDebtAssetsRatio string
}

FinancialReportSnapshot is the response for FundamentalContext.FinancialReportSnapshot.

type FinancialReports

type FinancialReports struct {
	// Raw nested financial data keyed by report kind.
	List json.RawMessage
}

FinancialReports is the response for FundamentalContext.FinancialReport. The List field contains deeply-nested indicator/account/value data keyed by report kind ("IS", "BS", "CF"). The exact structure varies and is preserved as raw JSON.

type ForecastEps

type ForecastEps struct {
	// EPS forecast snapshots ordered by ForecastStartDate ascending.
	Items []ForecastEpsItem
}

ForecastEps is the response for FundamentalContext.ForecastEps.

type ForecastEpsItem

type ForecastEpsItem struct {
	// Median EPS estimate.
	ForecastEpsMedian *decimal.Decimal
	// Mean EPS estimate.
	ForecastEpsMean *decimal.Decimal
	// Lowest EPS estimate.
	ForecastEpsLowest *decimal.Decimal
	// Highest EPS estimate.
	ForecastEpsHighest *decimal.Decimal
	// Total number of forecasting institutions.
	InstitutionTotal int32
	// Number of institutions that raised their estimate.
	InstitutionUp int32
	// Number of institutions that lowered their estimate.
	InstitutionDown int32
	// Forecast window start.
	ForecastStartDate time.Time
	// Forecast window end.
	ForecastEndDate time.Time
}

ForecastEpsItem is one EPS forecast snapshot.

type FundHolder

type FundHolder struct {
	// Fund/ETF ticker code, e.g. "513050".
	Code string
	// Fund/ETF symbol.
	Symbol string
	// Reporting currency, e.g. "CNY".
	Currency string
	// Fund/ETF full name.
	Name string
	// Position ratio as a percentage decimal.
	PositionRatio decimal.Decimal
	// Report date, e.g. "2025.12.31".
	ReportDate string
}

FundHolder is a fund or ETF that holds the queried security.

type FundHolders

type FundHolders struct {
	// Funds and ETFs that hold the queried security.
	Lists []FundHolder
}

FundHolders is the response for FundamentalContext.FundHolder.

type FundamentalContext

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

FundamentalContext is a client for the Longbridge Fundamental OpenAPI.

Example:

conf, err := config.NewFromEnv()
fctx, err := fundamental.NewFromCfg(conf)
reports, err := fctx.FinancialReport(context.Background(), "700.HK",
    fundamental.FinancialReportKindAll, nil)

func NewFromCfg

func NewFromCfg(cfg *config.Config) (*FundamentalContext, error)

NewFromCfg creates a FundamentalContext from a *config.Config.

func NewFromEnv

func NewFromEnv() (*FundamentalContext, error)

NewFromEnv returns a FundamentalContext configured from environment variables.

func (*FundamentalContext) BusinessSegments

func (c *FundamentalContext) BusinessSegments(
	ctx context.Context,
	symbol string,
) (*BusinessSegments, error)

BusinessSegments fetches the latest business segment breakdown for a security.

Path: GET /v1/quote/fundamentals/business-segments

func (*FundamentalContext) BusinessSegmentsHistory

func (c *FundamentalContext) BusinessSegmentsHistory(
	ctx context.Context,
	symbol string,
	report string,
	cate string,
) (*BusinessSegmentsHistory, error)

BusinessSegmentsHistory fetches historical business segment breakdowns for a security.

Path: GET /v1/quote/fundamentals/business-segments/history

func (*FundamentalContext) Buyback

func (c *FundamentalContext) Buyback(
	ctx context.Context,
	symbol string,
) (*BuybackData, error)

Buyback fetches buyback data for a security.

Path: GET /v1/quote/buy-backs

func (*FundamentalContext) Company

func (c *FundamentalContext) Company(
	ctx context.Context,
	symbol string,
) (*CompanyOverview, error)

Company fetches company overview information.

Path: GET /v1/quote/comp-overview

func (*FundamentalContext) Consensus

func (c *FundamentalContext) Consensus(
	ctx context.Context,
	symbol string,
) (*FinancialConsensus, error)

Consensus fetches financial consensus estimates for a security.

Path: GET /v1/quote/financial-consensus-detail

func (*FundamentalContext) CorpAction

func (c *FundamentalContext) CorpAction(
	ctx context.Context,
	symbol string,
) (*CorpActions, error)

CorpAction fetches corporate actions (dividends, splits, buybacks, etc.).

Path: GET /v1/quote/company-act

func (*FundamentalContext) Dividend

func (c *FundamentalContext) Dividend(
	ctx context.Context,
	symbol string,
) (*DividendList, error)

Dividend fetches dividend history for a security.

Path: GET /v1/quote/dividends

func (*FundamentalContext) DividendDetail

func (c *FundamentalContext) DividendDetail(
	ctx context.Context,
	symbol string,
) (*DividendList, error)

DividendDetail fetches detailed dividend information for a security.

Path: GET /v1/quote/dividends/details

func (*FundamentalContext) Executive

func (c *FundamentalContext) Executive(
	ctx context.Context,
	symbol string,
) (*ExecutiveList, error)

Executive fetches executive and board member information.

Path: GET /v1/quote/company-professionals

func (*FundamentalContext) FinancialReport

func (c *FundamentalContext) FinancialReport(
	ctx context.Context,
	symbol string,
	kind FinancialReportKind,
	period *FinancialReportPeriod,
) (*FinancialReports, error)

FinancialReport fetches financial reports for a security.

Path: GET /v1/quote/financial-reports

func (*FundamentalContext) FinancialReportSnapshot

func (c *FundamentalContext) FinancialReportSnapshot(
	ctx context.Context,
	symbol string,
	report string,
	fiscalYear int,
	fiscalPeriod string,
) (*FinancialReportSnapshot, error)

FinancialReportSnapshot fetches a financial report snapshot (earnings snapshot) for a security.

Path: GET /v1/quote/financials/earnings-snapshot

func (*FundamentalContext) ForecastEps

func (c *FundamentalContext) ForecastEps(
	ctx context.Context,
	symbol string,
) (*ForecastEps, error)

ForecastEps fetches EPS forecasts for a security.

Path: GET /v1/quote/forecast-eps

func (*FundamentalContext) FundHolder

func (c *FundamentalContext) FundHolder(
	ctx context.Context,
	symbol string,
) (*FundHolders, error)

FundHolder fetches funds and ETFs that hold a security.

Path: GET /v1/quote/fund-holders

func (*FundamentalContext) IndustryPeers

func (c *FundamentalContext) IndustryPeers(
	ctx context.Context,
	counterID string,
	market string,
	industryID string,
) (*IndustryPeersResponse, error)

IndustryPeers fetches the industry peer chain for a security or industry.

Path: GET /v1/quote/industries/peers

counterID may be a regular symbol like "AAPL.US" (auto-converted) or an industry counter ID like "BK/US/123" (passed through as-is when it contains a "/").

func (*FundamentalContext) IndustryRank

func (c *FundamentalContext) IndustryRank(
	ctx context.Context,
	market string,
	indicator IndustryRankIndicator,
	sortType IndustryRankSortType,
	limit int,
) (*IndustryRankResponse, error)

IndustryRank fetches the industry rank for a market.

Path: GET /v1/quote/industry/rank

indicator is an IndustryRankIndicator constant ("0"–"7"). sortType is an IndustryRankSortType constant ("0" ascending, "1" descending).

func (*FundamentalContext) IndustryValuation

func (c *FundamentalContext) IndustryValuation(
	ctx context.Context,
	symbol string,
) (*IndustryValuationList, error)

IndustryValuation fetches valuation comparison against industry peers.

Path: GET /v1/quote/industry-valuation-comparison

func (*FundamentalContext) IndustryValuationDist

func (c *FundamentalContext) IndustryValuationDist(
	ctx context.Context,
	symbol string,
) (*IndustryValuationDist, error)

IndustryValuationDist fetches valuation distribution within the industry.

Path: GET /v1/quote/industry-valuation-distribution

func (*FundamentalContext) InstitutionRating

func (c *FundamentalContext) InstitutionRating(
	ctx context.Context,
	symbol string,
) (*InstitutionRating, error)

InstitutionRating fetches analyst ratings for a security by combining the latest snapshot and the consensus summary.

Paths: GET /v1/quote/institution-rating-latest

GET /v1/quote/institution-ratings

func (*FundamentalContext) InstitutionRatingDetail

func (c *FundamentalContext) InstitutionRatingDetail(
	ctx context.Context,
	symbol string,
) (*InstitutionRatingDetail, error)

InstitutionRatingDetail fetches historical analyst rating details for a security.

Path: GET /v1/quote/institution-ratings/detail

func (*FundamentalContext) InstitutionRatingViews

func (c *FundamentalContext) InstitutionRatingViews(
	ctx context.Context,
	symbol string,
) (*InstitutionRatingViews, error)

InstitutionRatingViews fetches historical institutional rating views for a security.

Path: GET /v1/quote/ratings/institutional

func (*FundamentalContext) InvestRelation

func (c *FundamentalContext) InvestRelation(
	ctx context.Context,
	symbol string,
) (*InvestRelations, error)

InvestRelation fetches investor relations / investment holdings.

Path: GET /v1/quote/invest-relations

func (*FundamentalContext) Operating

func (c *FundamentalContext) Operating(
	ctx context.Context,
	symbol string,
) (*OperatingList, error)

Operating fetches operating metrics and financial report summaries.

Path: GET /v1/quote/operatings

func (*FundamentalContext) Ratings

func (c *FundamentalContext) Ratings(
	ctx context.Context,
	symbol string,
) (*StockRatings, error)

Ratings fetches stock ratings for a security.

Path: GET /v1/quote/ratings

func (*FundamentalContext) Shareholder

func (c *FundamentalContext) Shareholder(
	ctx context.Context,
	symbol string,
) (*ShareholderList, error)

Shareholder fetches major shareholders for a security.

Path: GET /v1/quote/shareholders

func (*FundamentalContext) ShareholderDetail

func (c *FundamentalContext) ShareholderDetail(
	ctx context.Context,
	symbol string,
	objectID int64,
) (*ShareholderDetailResponse, error)

ShareholderDetail fetches the holding detail for a specific shareholder.

Path: GET /v1/quote/shareholders/holding

func (*FundamentalContext) ShareholderTop

func (c *FundamentalContext) ShareholderTop(
	ctx context.Context,
	symbol string,
) (*ShareholderTopResponse, error)

ShareholderTop fetches the top shareholders list for a security.

Path: GET /v1/quote/shareholders/top

func (*FundamentalContext) Valuation

func (c *FundamentalContext) Valuation(
	ctx context.Context,
	symbol string,
) (*ValuationData, error)

Valuation fetches valuation metrics (PE/PB/PS/dividend yield) for a security.

Path: GET /v1/quote/valuation

func (*FundamentalContext) ValuationComparison

func (c *FundamentalContext) ValuationComparison(
	ctx context.Context,
	symbol string,
	currency string,
	comparisonSymbols []string,
) (*ValuationComparisonResponse, error)

ValuationComparison fetches valuation comparison data for a symbol against a set of peer symbols.

Path: GET /v1/quote/compare/valuation

comparisonSymbols is a list of peer symbols (e.g. ["MSFT.US", "GOOG.US"]) that are converted to counter_ids and serialized as a JSON array string in the comparison_counter_ids query parameter.

func (*FundamentalContext) ValuationHistory

func (c *FundamentalContext) ValuationHistory(
	ctx context.Context,
	symbol string,
) (*ValuationHistoryResponse, error)

ValuationHistory fetches historical valuation data for a security.

Path: GET /v1/quote/valuation/detail

type IndustryPeerNode

type IndustryPeerNode struct {
	// Node name.
	Name string
	// Counter ID.
	CounterID string
	// Number of stocks in this node.
	StockNum int32
	// Change percentage.
	Chg string
	// Year-to-date change.
	YtdChg string
	// Child nodes (recursive).
	Next []IndustryPeerNode
}

IndustryPeerNode is a node in the recursive industry peer chain.

type IndustryPeersResponse

type IndustryPeersResponse struct {
	// Top-level industry node info.
	Top IndustryPeersTop
	// Root peer chain node (nil if no data).
	Chain *IndustryPeerNode
}

IndustryPeersResponse is the response for FundamentalContext.IndustryPeers.

type IndustryPeersTop

type IndustryPeersTop struct {
	// Industry name.
	Name string
	// Market code.
	Market string
}

IndustryPeersTop holds the top-level industry info.

type IndustryRankGroup

type IndustryRankGroup struct {
	// Items in this group.
	Lists []IndustryRankItem
}

IndustryRankGroup is a group of ranked industry items.

type IndustryRankIndicator

type IndustryRankIndicator string

IndustryRankIndicator identifies the metric used for industry ranking.

const (
	// IndustryRankIndicator0 is indicator 0.
	IndustryRankIndicator0 IndustryRankIndicator = "0"
	// IndustryRankIndicator1 is indicator 1.
	IndustryRankIndicator1 IndustryRankIndicator = "1"
	// IndustryRankIndicator2 is indicator 2.
	IndustryRankIndicator2 IndustryRankIndicator = "2"
	// IndustryRankIndicator3 is indicator 3.
	IndustryRankIndicator3 IndustryRankIndicator = "3"
	// IndustryRankIndicator4 is indicator 4.
	IndustryRankIndicator4 IndustryRankIndicator = "4"
	// IndustryRankIndicator5 is indicator 5.
	IndustryRankIndicator5 IndustryRankIndicator = "5"
	// IndustryRankIndicator6 is indicator 6.
	IndustryRankIndicator6 IndustryRankIndicator = "6"
	// IndustryRankIndicator7 is indicator 7.
	IndustryRankIndicator7 IndustryRankIndicator = "7"
)

type IndustryRankItem

type IndustryRankItem struct {
	// Industry / sector name.
	Name string
	// Counter ID of the industry.
	CounterID string
	// Change percentage.
	Chg string
	// Name of the leading stock.
	LeadingName string
	// Ticker of the leading stock.
	LeadingTicker string
	// Change percentage of the leading stock.
	LeadingChg string
	// Value label name.
	ValueName string
	// Value data.
	ValueData string
}

IndustryRankItem is one ranked industry item.

type IndustryRankResponse

type IndustryRankResponse struct {
	// Grouped rank items.
	Items []IndustryRankGroup
}

IndustryRankResponse is the response for FundamentalContext.IndustryRank.

type IndustryRankSortType

type IndustryRankSortType string

IndustryRankSortType specifies the sort direction for industry ranking.

const (
	// IndustryRankSortTypeAscending sorts ascending.
	IndustryRankSortTypeAscending IndustryRankSortType = "0"
	// IndustryRankSortTypeDescending sorts descending.
	IndustryRankSortTypeDescending IndustryRankSortType = "1"
)

type IndustryValuationDist

type IndustryValuationDist struct {
	// PE ratio distribution within the industry.
	PE *ValuationDist
	// PB ratio distribution within the industry.
	PB *ValuationDist
	// PS ratio distribution within the industry.
	PS *ValuationDist
}

IndustryValuationDist is the response for FundamentalContext.IndustryValuationDist.

type IndustryValuationHistory

type IndustryValuationHistory struct {
	// Unix timestamp string.
	Date string
	// Price-to-Earnings ratio.
	PE *decimal.Decimal
	// Price-to-Book ratio.
	PB *decimal.Decimal
	// Price-to-Sales ratio.
	PS *decimal.Decimal
}

IndustryValuationHistory is a historical valuation snapshot for an industry peer.

type IndustryValuationItem

type IndustryValuationItem struct {
	// Security symbol, e.g. "700.HK".
	Symbol string
	// Company name.
	Name string
	// Reporting currency.
	Currency string
	// Total assets.
	Assets *decimal.Decimal
	// Book value per share.
	Bps *decimal.Decimal
	// Earnings per share.
	Eps *decimal.Decimal
	// Dividends per share.
	Dps *decimal.Decimal
	// Dividend yield.
	DivYld *decimal.Decimal
	// Dividend payout ratio.
	DivPayoutRatio *decimal.Decimal
	// 5-year average dividends per share.
	FiveYAvgDps *decimal.Decimal
	// Current PE ratio.
	PE *decimal.Decimal
	// Historical PE/PB/PS snapshots.
	History []IndustryValuationHistory
}

IndustryValuationItem holds valuation data for one peer security.

type IndustryValuationList

type IndustryValuationList struct {
	// List of peer securities with their valuation data.
	List []IndustryValuationItem
}

IndustryValuationList is the response for FundamentalContext.IndustryValuation.

type InstitutionRating

type InstitutionRating struct {
	// Latest snapshot.
	Latest InstitutionRatingLatest
	// Consensus summary.
	Summary InstitutionRatingSummary
}

InstitutionRating is the combined analyst-rating response for FundamentalContext.InstitutionRating.

type InstitutionRatingDetail

type InstitutionRatingDetail struct {
	// Currency symbol, e.g. "HK$".
	CcySymbol string
	// Historical rating distribution time-series.
	Evaluate InstitutionRatingDetailEvaluate
	// Historical target price time-series.
	Target InstitutionRatingDetailTarget
}

InstitutionRatingDetail is the response for FundamentalContext.InstitutionRatingDetail.

type InstitutionRatingDetailEvaluate

type InstitutionRatingDetailEvaluate struct {
	// Weekly snapshots ordered from oldest to newest.
	List []InstitutionRatingDetailEvaluateItem
}

InstitutionRatingDetailEvaluate holds the historical rating distribution time-series.

type InstitutionRatingDetailEvaluateItem

type InstitutionRatingDetailEvaluateItem struct {
	// Number of "Buy" ratings.
	Buy int32
	// Date in "2021/05/14" format.
	Date string
	// Number of "Hold" ratings.
	Hold int32
	// Number of "Sell" ratings.
	Sell int32
	// Number of "Strong Buy" / "Outperform" ratings.
	StrongBuy int32
	// Number of "No Opinion" ratings.
	NoOpinion int32
	// Number of "Underperform" ratings.
	Under int32
}

InstitutionRatingDetailEvaluateItem is one weekly rating distribution snapshot.

type InstitutionRatingDetailTarget

type InstitutionRatingDetailTarget struct {
	// Prediction accuracy ratio (may be nil).
	DataPercent *decimal.Decimal
	// Overall prediction accuracy percentage.
	PredictionAccuracy *decimal.Decimal
	// Last updated display string.
	UpdatedAt string
	// Weekly target price snapshots.
	List []InstitutionRatingDetailTargetItem
}

InstitutionRatingDetailTarget holds the historical target price time-series.

type InstitutionRatingDetailTargetItem

type InstitutionRatingDetailTargetItem struct {
	// Average target price.
	AvgTarget *decimal.Decimal
	// Date in "2021/05/16" format.
	Date string
	// Highest target price.
	MaxTarget *decimal.Decimal
	// Lowest target price.
	MinTarget *decimal.Decimal
	// Whether the stock price reached the target.
	Meet bool
	// Actual stock price at this date.
	Price *decimal.Decimal
	// Unix timestamp string.
	Timestamp string
}

InstitutionRatingDetailTargetItem is one weekly target price snapshot.

type InstitutionRatingLatest

type InstitutionRatingLatest struct {
	// Rating distribution counts and date range.
	Evaluate RatingEvaluate
	// Target price range.
	Target RatingTarget
	// Industry classification ID.
	IndustryID int64
	// Industry name.
	IndustryName string
	// Rank of this security within the industry (1 = highest).
	IndustryRank int32
	// Total number of securities in the industry.
	IndustryTotal int32
	// Mean analyst count in the industry.
	IndustryMean int32
	// Median analyst count in the industry.
	IndustryMedian int32
}

InstitutionRatingLatest is the latest analyst-rating snapshot.

type InstitutionRatingSummary

type InstitutionRatingSummary struct {
	// Currency symbol, e.g. "HK$".
	CcySymbol string
	// Change vs previous period.
	Change *decimal.Decimal
	// Simplified rating distribution.
	Evaluate RatingSummaryEvaluate
	// Overall recommendation.
	Recommend InstitutionRecommend
	// Consensus target price.
	Target *decimal.Decimal
	// Last updated display string.
	UpdatedAt string
}

InstitutionRatingSummary is the consensus summary.

type InstitutionRatingViewItem

type InstitutionRatingViewItem struct {
	// Date of the snapshot.
	Date time.Time
	// Number of "Buy" ratings.
	Buy string
	// Number of "Outperform" ratings.
	Over string
	// Number of "Hold" ratings.
	Hold string
	// Number of "Underperform" ratings.
	Under string
	// Number of "Sell" ratings.
	Sell string
	// Total analyst count.
	Total string
}

InstitutionRatingViewItem is one historical rating distribution snapshot.

type InstitutionRatingViews

type InstitutionRatingViews struct {
	// Historical rating distribution snapshots.
	Elist []InstitutionRatingViewItem
}

InstitutionRatingViews is the response for FundamentalContext.InstitutionRatingViews.

type InstitutionRecommend

type InstitutionRecommend int

InstitutionRecommend encodes an analyst's consensus recommendation.

const (
	// InstitutionRecommendUnknown is an unknown recommendation.
	InstitutionRecommendUnknown InstitutionRecommend = iota
	// InstitutionRecommendStrongBuy is a strong-buy recommendation.
	InstitutionRecommendStrongBuy
	// InstitutionRecommendBuy is a buy recommendation.
	InstitutionRecommendBuy
	// InstitutionRecommendHold is a hold recommendation.
	InstitutionRecommendHold
	// InstitutionRecommendSell is a sell recommendation.
	InstitutionRecommendSell
	// InstitutionRecommendStrongSell is a strong-sell recommendation.
	InstitutionRecommendStrongSell
	// InstitutionRecommendUnderperform is an underperform recommendation.
	InstitutionRecommendUnderperform
	// InstitutionRecommendNoOpinion indicates no analyst opinion.
	InstitutionRecommendNoOpinion
)

type InvestRelations

type InvestRelations struct {
	// Link to the full investor-relations page.
	ForwardURL string
	// Securities in which the queried company holds a stake.
	InvestSecurities []InvestSecurity
}

InvestRelations is the response for FundamentalContext.InvestRelation.

type InvestSecurity

type InvestSecurity struct {
	// Internal company ID (string form; may be "0").
	CompanyID string
	// Company name (locale-aware).
	CompanyName string
	// Company name in English.
	CompanyNameEn string
	// Company name in Simplified Chinese.
	CompanyNameZhCN string
	// Security symbol of the invested company.
	Symbol string
	// Reporting currency.
	Currency string
	// Percentage of shares held.
	PercentOfShares *decimal.Decimal
	// Shareholder rank, e.g. "1" = largest shareholder.
	SharesRank string
	// Market value of the holding.
	SharesValue *decimal.Decimal
}

InvestSecurity is a security in which the queried company has an investment stake.

type OperatingFinancial

type OperatingFinancial struct {
	// Ticker code (may be empty).
	Code string
	// Symbol in CODE.MARKET format (may be empty).
	Symbol string
	// Reporting currency.
	Currency string
	// Company name.
	Name string
	// Market region.
	Region string
	// Report period code.
	Report string
	// Report period display text.
	ReportTxt string
	// Financial indicators.
	Indicators []OperatingIndicator
}

OperatingFinancial holds key financial metrics extracted from an operating report.

type OperatingIndicator

type OperatingIndicator struct {
	// Field name key, e.g. "operating_revenue".
	FieldName string
	// Display name, e.g. "营业收入".
	IndicatorName string
	// Formatted value, e.g. "8217 亿".
	IndicatorValue string
	// Year-over-year change.
	Yoy *decimal.Decimal
}

OperatingIndicator is one financial indicator in an operating report.

type OperatingItem

type OperatingItem struct {
	// Internal report ID.
	ID string
	// Report period code, e.g. "af" (annual), "qf" (quarterly).
	Report string
	// Report title, e.g. "2025 财年年报".
	Title string
	// Management discussion text.
	Txt string
	// Whether this is the most recent report.
	Latest bool
	// Keyword tags (structure undocumented; usually empty).
	Keywords []json.RawMessage
	// URL to the full community report page.
	WebURL string
	// Key financial metrics extracted from the report.
	Financial OperatingFinancial
}

OperatingItem is one operating summary report (annual / quarterly).

type OperatingList

type OperatingList struct {
	// List of operating summary reports.
	List []OperatingItem
}

OperatingList is the response for FundamentalContext.Operating.

type Professional

type Professional struct {
	// Internal wiki person ID.
	ID string
	// Full name.
	Name string
	// Full name in Simplified Chinese.
	NameZhCN string
	// Full name in English.
	NameEn string
	// Job title, e.g. "Co-Founder, Chairman & CEO".
	Title string
	// Biography text.
	Biography string
	// URL to the person's photo.
	Photo string
	// URL to the wiki profile page.
	WikiURL string
}

Professional is one executive / board member.

type RatingCategory

type RatingCategory struct {
	// Category type code.
	Kind int32
	// Sub-indicator groups within this category.
	SubIndicators []RatingSubIndicatorGroup
}

RatingCategory is one rating category (e.g. growth, profitability).

type RatingEvaluate

type RatingEvaluate struct {
	// Number of "Buy" ratings.
	Buy int32
	// Number of "Strong Buy" / "Outperform" ratings.
	Over int32
	// Number of "Hold" / "Neutral" ratings.
	Hold int32
	// Number of "Underperform" ratings.
	Under int32
	// Number of "Sell" ratings.
	Sell int32
	// Number of "No Opinion" ratings.
	NoOpinion int32
	// Total analyst count.
	Total int32
	// Window start (unix timestamp string; "0" means unset).
	StartDate string
	// Window end (unix timestamp string; "0" means unset).
	EndDate string
}

RatingEvaluate holds analyst rating distribution counts.

type RatingIndicator

type RatingIndicator struct {
	// Indicator display name.
	Name string
	// Score (raw JSON; may be int, float, or null).
	Score json.RawMessage
	// Letter grade.
	Letter string
}

RatingIndicator is a rating indicator node (may be a parent or a leaf).

type RatingLeafIndicator

type RatingLeafIndicator struct {
	// Indicator display name.
	Name string
	// Formatted value string.
	Value string
	// Value type hint, e.g. "percent".
	ValueType string
	// Score (raw JSON; may be int, float, or null).
	Score json.RawMessage
	// Letter grade.
	Letter string
}

RatingLeafIndicator is a leaf rating indicator with a raw value.

type RatingSubIndicatorGroup

type RatingSubIndicatorGroup struct {
	// Parent indicator for this group.
	Indicator RatingIndicator
	// Leaf sub-indicators.
	SubIndicators []RatingLeafIndicator
}

RatingSubIndicatorGroup is a group of sub-indicators under one category indicator.

type RatingSummaryEvaluate

type RatingSummaryEvaluate struct {
	// Number of "Buy" ratings.
	Buy int32
	// Date of the latest update.
	Date string
	// Number of "Hold" ratings.
	Hold int32
	// Number of "Sell" ratings.
	Sell int32
	// Number of "Strong Buy" ratings.
	StrongBuy int32
	// Number of "Underperform" ratings.
	Under int32
}

RatingSummaryEvaluate is the simplified rating distribution for the consensus summary.

type RatingTarget

type RatingTarget struct {
	// Highest price target.
	HighestPrice *decimal.Decimal
	// Lowest price target.
	LowestPrice *decimal.Decimal
	// Previous close price.
	PrevClose *decimal.Decimal
	// Window start (unix timestamp string).
	StartDate string
	// Window end (unix timestamp string).
	EndDate string
}

RatingTarget holds the analyst target price range.

type RecentBuybacks

type RecentBuybacks struct {
	// Reporting currency.
	Currency string
	// Net buyback amount TTM.
	NetBuybackTTM *decimal.Decimal
	// Net buyback yield TTM.
	NetBuybackYieldTTM *decimal.Decimal
}

RecentBuybacks is the TTM (trailing twelve months) buyback summary.

type Shareholder

type Shareholder struct {
	// Internal shareholder ID.
	ShareholderID string
	// Shareholder name.
	ShareholderName string
	// Institution type (may be empty).
	InstitutionType string
	// Percentage of shares held.
	PercentOfShares *decimal.Decimal
	// Change in shares held (positive = bought, negative = sold).
	SharesChanged *decimal.Decimal
	// Date of the most recent filing, e.g. "2026-05-04".
	ReportDate string
	// Other securities held by this shareholder (cross-holdings).
	Stocks []ShareholderStock
}

Shareholder is one major shareholder.

type ShareholderDetailResponse

type ShareholderDetailResponse struct {
	Data json.RawMessage
}

ShareholderDetailResponse holds the raw data for a single shareholder's holding details from GET /v1/quote/shareholders/holding.

type ShareholderList

type ShareholderList struct {
	// List of major shareholders.
	ShareholderList []Shareholder
	// Link to the full shareholder page.
	ForwardURL string
	// Total number of shareholders returned.
	Total int32
}

ShareholderList is the response for FundamentalContext.Shareholder.

type ShareholderStock

type ShareholderStock struct {
	// Security symbol of the cross-held stock.
	Symbol string
	// Ticker code, e.g. "BLK".
	Code string
	// Market, e.g. "US".
	Market string
	// Day change percentage, e.g. "-0.32%".
	Chg string
}

ShareholderStock is a security in an institutional shareholder's cross-holdings.

type ShareholderTopResponse

type ShareholderTopResponse struct {
	Data json.RawMessage
}

ShareholderTopResponse holds the raw data for the top shareholders list. The Data field contains the JSON payload from GET /v1/quote/shareholders/top.

type SnapshotForecastMetric

type SnapshotForecastMetric struct {
	// Actual value.
	Value string
	// Year-over-year change.
	Yoy string
	// Beat/miss description.
	CmpDesc string
	// Consensus estimate value.
	EstValue string
}

SnapshotForecastMetric is a forecast metric in the financial report snapshot.

type SnapshotReportedMetric

type SnapshotReportedMetric struct {
	// Actual value.
	Value string
	// Year-over-year change.
	Yoy string
}

SnapshotReportedMetric is a reported metric in the financial report snapshot.

type StockRatings

type StockRatings struct {
	// Style display name.
	StyleTxtName string
	// Scale display name.
	ScaleTxtName string
	// Report period display text.
	ReportPeriodTxt string
	// Composite score (raw JSON; may be int, float, or null).
	MultiScore json.RawMessage
	// Composite score letter grade.
	MultiLetter string
	// Score change vs previous period.
	MultiScoreChange int32
	// Industry name.
	IndustryName string
	// Industry rank (raw JSON; may be int or null).
	IndustryRank json.RawMessage
	// Total securities in the industry (raw JSON; may be int or null).
	IndustryTotal json.RawMessage
	// Industry mean score (raw JSON; may be float or null).
	IndustryMeanScore json.RawMessage
	// Industry median score (raw JSON; may be float or null).
	IndustryMedianScore json.RawMessage
	// Detailed rating categories.
	Ratings []RatingCategory
}

StockRatings is the response for FundamentalContext.Ratings.

type ValuationComparisonItem

type ValuationComparisonItem struct {
	// Symbol — converted from counter_id (e.g. "AAPL.US")
	Symbol      string
	Name        string
	Currency    string
	MarketValue string
	PriceClose  string
	Pe          string
	Pb          string
	Ps          string
	Roe         string
	Eps         string
	Bps         string
	Dps         string
	DivYld      string
	Assets      string
	History     []*ValuationHistoryPoint
}

ValuationComparisonItem is one security in the valuation comparison.

type ValuationComparisonResponse

type ValuationComparisonResponse struct {
	List []*ValuationComparisonItem
}

ValuationComparisonResponse is the response for FundamentalContext.ValuationComparison.

type ValuationData

type ValuationData struct {
	// Valuation metrics (PE / PB / PS / dividend yield).
	Metrics ValuationMetricsData
}

ValuationData is the response for FundamentalContext.Valuation.

type ValuationDist

type ValuationDist struct {
	// Minimum value in the industry.
	Low *decimal.Decimal
	// Maximum value in the industry.
	High *decimal.Decimal
	// Median value in the industry.
	Median *decimal.Decimal
	// Current value of the queried security.
	Value *decimal.Decimal
	// Percentile ranking (0–1 range).
	Ranking *decimal.Decimal
	// Ordinal rank index (1-based, as string).
	RankIndex string
	// Total number of securities in the industry (as string).
	RankTotal string
}

ValuationDist holds distribution statistics for one valuation metric within an industry.

type ValuationHistoryData

type ValuationHistoryData struct {
	// Historical metrics (PE / PB / PS).
	Metrics ValuationHistoryMetrics
}

ValuationHistoryData holds the historical valuation metrics container.

type ValuationHistoryMetric

type ValuationHistoryMetric struct {
	// Human-readable description.
	Desc string
	// Historical high over the period.
	High *decimal.Decimal
	// Historical low over the period.
	Low *decimal.Decimal
	// Historical median over the period.
	Median *decimal.Decimal
	// Historical data points.
	List []ValuationPoint
}

ValuationHistoryMetric holds the historical data for one valuation metric including statistical bounds.

type ValuationHistoryMetrics

type ValuationHistoryMetrics struct {
	// Price-to-Earnings history.
	PE *ValuationHistoryMetric
	// Price-to-Book history.
	PB *ValuationHistoryMetric
	// Price-to-Sales history.
	PS *ValuationHistoryMetric
}

ValuationHistoryMetrics holds PE/PB/PS historical data.

type ValuationHistoryPoint

type ValuationHistoryPoint struct {
	// Date — RFC 3339 (converted from Unix timestamp)
	Date string
	Pe   string
	Pb   string
	Ps   string
}

ValuationHistoryPoint is one historical valuation data point.

type ValuationHistoryResponse

type ValuationHistoryResponse struct {
	// Historical valuation data.
	History ValuationHistoryData
}

ValuationHistoryResponse is the response for FundamentalContext.ValuationHistory.

type ValuationMetricData

type ValuationMetricData struct {
	// Human-readable description with current value and percentile.
	Desc string
	// Historical high value.
	High *decimal.Decimal
	// Historical low value.
	Low *decimal.Decimal
	// Historical median value.
	Median *decimal.Decimal
	// Historical data points.
	List []ValuationPoint
}

ValuationMetricData holds the historical time-series for one valuation metric.

type ValuationMetricsData

type ValuationMetricsData struct {
	// Price-to-Earnings ratio history.
	PE *ValuationMetricData
	// Price-to-Book ratio history.
	PB *ValuationMetricData
	// Price-to-Sales ratio history.
	PS *ValuationMetricData
	// Dividend yield history.
	DvdYld *ValuationMetricData
}

ValuationMetricsData holds all valuation metrics containers.

type ValuationPoint

type ValuationPoint struct {
	// Date of the data point.
	Timestamp time.Time
	// Metric value.
	Value *decimal.Decimal
}

ValuationPoint is one valuation data point.

Directories

Path Synopsis
Package jsontypes contains raw JSON wire-format structs for the fundamental data API.
Package jsontypes contains raw JSON wire-format structs for the fundamental data API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL