# Fund Candles (Python SDK)
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
```python
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](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/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)
```python
from marketdata 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)
```python
from marketdata import MarketDataClient, 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)
```python
from marketdata import MarketDataClient, 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)
```python
from marketdata import MarketDataClient, 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)
```python
from marketdata import MarketDataClient, 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
```python
@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
```python
@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`).