Candles

Retrieve historical price candles for any supported fund symbol.

Making Requests

Use the candles() method on the funds resource to fetch fund candles. The method supports multiple output formats:

Output Format	Return Type	Description
DATAFRAME	pandas.DataFrame or polars.DataFrame	Returns a DataFrame with candles data (default).
INTERNAL	list[FundsCandle] or list[FundsCandlesHumanReadable]	Returns a list of FundsCandle objects. When use_human_readable=True, returns a list of FundsCandlesHumanReadable objects with capitalized field names.
JSON	dict	Returns the raw JSON response as a dictionary.
CSV	str	Writes CSV data to file and returns the filename string.

candles

def candles(
    symbol: str,
    *,
    resolution: str = "D",
    from_date: str | datetime.datetime = None,
    to_date: str | datetime.datetime = None,
    date: str | datetime.datetime = None,
    countback: int = None,
    output_format: OutputFormat = OutputFormat.DATAFRAME,
    date_format: DateFormat = None,
    columns: list[str] = None,
    add_headers: bool = None,
    use_human_readable: bool = False,
    mode: Mode = None,
    filename: str | Path = None,
) -> list[FundsCandle] | list[FundsCandlesHumanReadable] | dict | str | MarketDataClientErrorResult

Fetches historical candles (OHLC) data for a fund symbol. The symbol parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.

Parameters

• symbol (str)

  The fund symbol for which to fetch candles data.

• resolution (str, optional)

  The granularity of the candle data (e.g., "1D", "1W", "1M"). Defaults to "D" (daily).

• from_date (str | datetime.datetime, optional)

  Start date for the date range.

• to_date (str | datetime.datetime, optional)

  End date for the date range.

• date (str | datetime.datetime, optional)

  Specific date for the candles data.

• countback (int, optional)

  Number of candles to return, counting backwards from the to_date.

• output_format (OutputFormat, optional)

  The format of the returned data. Defaults to OutputFormat.DATAFRAME. See Settings for details.

• date_format (DateFormat, optional)

  The date format to use in the response. Defaults to DateFormat.UNIX. See Settings for details.

• columns (optional)

  Specify which columns to include in the response. See Settings for details.

• add_headers (optional)

  Whether to include headers in the response. See Settings for details.

• use_human_readable (optional)

  Whether to use human-readable format for values. Only applies when output_format=OutputFormat.INTERNAL. See Settings for details.

• mode (Mode, optional)

  The data feed mode to use. See Settings for details.

• filename (str | Path, optional)

  File path for CSV output (only used with output_format=OutputFormat.CSV).

Returns

• list[FundsCandle] | list[FundsCandlesHumanReadable] | dict | str | MarketDataClientErrorResult

  The candles data in the requested format, or a MarketDataClientErrorResult if an error occurred.

Example (DataFrame)

from marketdata.client import MarketDataClient

client = MarketDataClient()

# Get fund candles as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.funds.candles("VFINX")
# or
df = client.funds.candles(symbol="VFINX")

# Get candles for a date range
df = client.funds.candles(
    "VFINX",
    resolution="1D",
    from_date="2023-01-01",
    to_date="2023-01-31"
)

print(df)

Example (Internal)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get fund candles as internal objects
candles = client.funds.candles(
    "VFINX",
    resolution="1D",
    from_date="2023-01-01",
    to_date="2023-01-31",
    output_format=OutputFormat.INTERNAL
)

# Access individual candle properties
for candle in candles:
    print(f"Time: {candle.t}")
    print(f"Open: {candle.o}")
    print(f"High: {candle.h}")
    print(f"Low: {candle.l}")
    print(f"Close: {candle.c}")

Example (JSON)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get fund candles as JSON
candles = client.funds.candles(
    "VFINX",
    resolution="1D",
    from_date="2023-01-01",
    to_date="2023-01-31",
    output_format=OutputFormat.JSON
)

print(candles)

Example (CSV)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat
from pathlib import Path

client = MarketDataClient()

# Get fund candles as CSV
csv_file = client.funds.candles(
    "VFINX",
    resolution="1D",
    from_date="2023-01-01",
    to_date="2023-01-31",
    output_format=OutputFormat.CSV,
    filename=Path("funds_candles.csv")
)

print(f"CSV file saved to: {csv_file}")

Example (Human Readable)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get fund candles in human-readable format
candles = client.funds.candles(
    "VFINX",
    resolution="1D",
    from_date="2023-01-01",
    to_date="2023-01-31",
    output_format=OutputFormat.INTERNAL,
    use_human_readable=True
)

# Access individual candle properties
for candle in candles:
    print(f"Date: {candle.Date}")
    print(f"Open: {candle.Open}")
    print(f"High: {candle.High}")
    print(f"Low: {candle.Low}")
    print(f"Close: {candle.Close}")

FundsCandle

@dataclass
class FundsCandle:
    t: datetime.datetime
    o: float
    h: float
    l: float
    c: float

FundsCandle represents a single fund candle (OHLC data), encapsulating price information for a specific time period.

Properties

• t (datetime.datetime): The timestamp for the candle (automatically converted from Unix timestamp).
• o (float): The opening price.
• h (float): The highest price.
• l (float): The lowest price.
• c (float): The closing price.

Notes

• The t field is automatically converted to a datetime.datetime object from a Unix timestamp.

FundsCandlesHumanReadable

@dataclass
class FundsCandlesHumanReadable:
    Date: datetime.datetime
    Open: float
    High: float
    Low: float
    Close: float

FundsCandlesHumanReadable represents a fund candle in human-readable format with capitalized field names and formatted values.

Properties

• Date (datetime.datetime): The timestamp for the candle (automatically converted from Unix timestamp).
• Open (float): The opening price.
• High (float): The highest price.
• Low (float): The lowest price.
• Close (float): The closing price.

Notes

• The Date field is automatically converted to a datetime.datetime object from a Unix timestamp.
• Field names use capitalized format (e.g., Open instead of o, Date instead of t).