Skip to main content

Candles

Retrieve historical OHLC candles for a mutual fund. Each candle reports the fund's net asset value (NAV) for one period, with its Time normalized to US Eastern.

Making Requests​

Fetch fund candles with the Candles method on the client.Funds service. It comes in two call styles:

MethodReturnDescription
GetCandles(symbol, ...opts)([]funds.Candle, error)Convenience; uses a background context and discards response metadata.
Candles(ctx, symbol, ...opts)([]funds.Candle, *response.Response, error)Context-aware; also returns the raw response plus rate-limit metadata.

Candles​

func (s *Service) Candles(ctx context.Context, symbol string, opts ...funds.CandleOption) ([]funds.Candle, *response.Response, error)
func (s *Service) GetCandles(symbol string, opts ...funds.CandleOption) ([]funds.Candle, error)

Get historical OHLC candles for a mutual fund from the /v1/funds/candles/{resolution}/{symbol}/ endpoint. Dates are sent to the API in YYYY-MM-DD form, so any time-of-day component is ignored.

Parameters​

  • ctx (context.Context) — request context for cancellation and deadlines (context method only).
  • symbol (string) — the fund's ticker, for example "VFINX". Required; an empty symbol returns a validation error without making a request.
  • Options:
    • funds.WithResolution(r funds.Resolution) — the candle timeframe. Defaults to funds.ResolutionDaily. The funds endpoint supports funds.ResolutionDaily ("D"), funds.ResolutionWeekly ("W"), funds.ResolutionMonthly ("M"), and funds.ResolutionYearly ("Y") only. The resolution becomes part of the request path, so an unsupported value causes the API to reject the request.
    • funds.WithCandleWindow(w funds.DateWindow) — the date range, expressed as a single DateWindow value. Omitting it lets the API return its default recent window.

Returns​

  • []funds.Candle — one Candle per period, oldest first.
  • *response.Response — raw response plus rate-limit metadata (context method only).
  • error — non-nil on request or decoding failure. A missing symbol returns a *marketdata.ValidationError.

Notes​

  • Mutual funds price once per day at market close, so daily resolution is the most common choice.
  • When the API responds 404 because no data exists for the requested symbol or range, both call styles return a nil slice and a nil error. With the context method, the returned *response.Response has its NoData field set to true.
  • The date parameters (date, from, to, countback) are mutually exclusive by construction: a DateWindow is a single sealed value, so an illegal pairing such as "from plus countback" cannot be expressed.
package main

import (
	"fmt"
	"log"

	"github.com/MarketDataApp/sdk-go/v2/marketdata"
	"github.com/MarketDataApp/sdk-go/v2/marketdata/funds"
)

func main() {
	client, err := marketdata.NewClient() // reads MARKETDATA_TOKEN from env / .env
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	// The 5 most recent daily candles for the Vanguard 500 Index Fund.
	candles, err := client.Funds.GetCandles("VFINX",
		funds.WithCandleWindow(funds.LastN(5)),
	)
	if err != nil {
		log.Fatal(err)
	}
	for _, candle := range candles {
		fmt.Println(candle)
	}
}

Output​

2023-01-03 O: 352.76 H: 352.76 L: 352.76 C: 352.76
2023-01-04 O: 355.43 H: 355.43 L: 355.43 C: 355.43
2023-01-05 O: 351.35 H: 351.35 L: 351.35 C: 351.35
2023-01-06 O: 359.38 H: 359.38 L: 359.38 C: 359.38

Candle​

type Candle struct {
	Time  time.Time `json:"t"` // Time is the candle timestamp (US Eastern).
	Open  float64   `json:"o"` // Open is the opening price (NAV).
	High  float64   `json:"h"` // High is the highest price.
	Low   float64   `json:"l"` // Low is the lowest price.
	Close float64   `json:"c"` // Close is the closing price (NAV).
}

Candle represents an OHLC candle for a fund. Because mutual funds report a single NAV per period, the open, high, low, and close are typically identical.

Fields​

  • Time (time.Time) — the candle timestamp, normalized to US Eastern.
  • Open (float64) — the opening NAV.
  • High (float64) — the highest price during the period.
  • Low (float64) — the lowest price during the period.
  • Close (float64) — the closing NAV.

Methods​

  • String() string — a concise one-line summary, e.g. 2023-01-03 O: 352.76 H: 352.76 L: 352.76 C: 352.76.
  • Range() float64 — the high-low range (High - Low).
Zero values and null data

Numeric fields are value types, not pointers. When the API returns null for a field, it decodes as the zero value, so a 0 may represent either an actual zero or the absence of data.

Resolution​

type Resolution string

const (
	ResolutionDaily   Resolution = "D"
	ResolutionWeekly  Resolution = "W"
	ResolutionMonthly Resolution = "M"
	ResolutionYearly  Resolution = "Y"
)

Resolution selects the candle timeframe passed to WithResolution. The funds candles endpoint supports daily, weekly, monthly, and yearly only (quarterly is not accepted). Resolution has a String() method that returns the underlying code.