# Stock Candles (Python SDK) Retrieve historical price candles for any supported stock symbol. ## Making Requests Use the `candles()` method on the `stocks` resource to fetch stock candles. The method supports multiple output formats and automatically handles large date ranges by splitting them into year-long chunks and fetching them concurrently: | Output Format | Return Type | Description | |---------------|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with candles data indexed by timestamp (default). | | **INTERNAL** | `list[StockCandle]` or `list[StockCandlesHumanReadable]` | Returns a list of StockCandle objects. When `use_human_readable=True`, returns a list of StockCandlesHumanReadable 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, adjust_splits: bool = None, extended: bool = None, exchange: str = 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[StockCandle] | list[StockCandlesHumanReadable] | dict | str | MarketDataClientErrorResult ``` Fetches historical candles (OHLCV) data for a stock symbol. Supports various timeframes (minutely, hourly, daily, weekly, monthly, yearly) and automatically handles large date ranges by splitting them into year-long chunks and fetching them concurrently. 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 stock symbol for which to fetch candles data. - `resolution` (str, optional) The granularity of the candle data (e.g., "1m", "5m", "1H", "4H", "1D", "1W", "1M", "1Y"). 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`. - `adjust_splits` (bool, optional) Whether to adjust for stock splits. Uses API alias `adjustsplits`. - `extended` (bool, optional) Whether to include extended hours data. - `exchange` (str, optional) Filter by exchange. - `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[StockCandle]` | `list[StockCandlesHumanReadable]` | `dict` | `str` | `MarketDataClientErrorResult` The candles data in the requested format, or a `MarketDataClientErrorResult` if an error occurred. ### Notes - For intraday resolutions (minutely/hourly), large date ranges are automatically split into year-long chunks and fetched concurrently (up to 50 concurrent requests by default). - When using `OutputFormat.DATAFRAME`, the DataFrame is indexed by the timestamp column (`t` or `Date`). - When using `OutputFormat.INTERNAL`, timestamps are automatically converted to `datetime.datetime` objects. ### Example (DataFrame) ```python from marketdata import MarketDataClient client = MarketDataClient() # Get stock candles as DataFrame (default) # symbol can be passed positionally or as keyword df = client.stocks.candles("AAPL", resolution="4H", from_date="2023-01-01", to_date="2023-01-04") # or df = client.stocks.candles(symbol="AAPL", resolution="4H", from_date="2023-01-01", to_date="2023-01-04") print(df) ``` **Output** ``` open high low close volume t 2023-01-03 09:30:00 130.28 130.90 124.19 124.65 64192007 2023-01-03 13:30:00 124.67 125.42 124.17 125.05 30727802 2023-01-04 09:30:00 126.89 128.66 125.08 127.26 49096197 2023-01-04 13:30:00 127.26 127.87 125.28 126.38 28870578 ``` ### Example (Internal) ```python from marketdata import MarketDataClient, OutputFormat client = MarketDataClient() # Get stock candles as internal objects candles = client.stocks.candles( "AAPL", resolution="4H", from_date="2023-01-01", to_date="2023-01-04", 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}") print(f"Volume: {candle.v}") ``` ### Example (JSON) ```python from marketdata import MarketDataClient, OutputFormat client = MarketDataClient() # Get stock candles as JSON candles = client.stocks.candles( "AAPL", resolution="4H", from_date="2023-01-01", to_date="2023-01-04", output_format=OutputFormat.JSON ) print(candles) ``` ### Example (CSV) ```python from marketdata import MarketDataClient, OutputFormat from pathlib import Path client = MarketDataClient() # Get stock candles as CSV csv_file = client.stocks.candles( "AAPL", resolution="4H", from_date="2023-01-01", to_date="2023-01-04", output_format=OutputFormat.CSV, filename=Path("candles.csv") ) print(f"CSV file saved to: {csv_file}") ``` ### Example (Human Readable) ```python from marketdata import MarketDataClient, OutputFormat client = MarketDataClient() # Get stock candles in human-readable format candles = client.stocks.candles( "AAPL", resolution="4H", from_date="2023-01-01", to_date="2023-01-04", 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}") print(f"Volume: {candle.Volume}") ``` ## StockCandle ```python @dataclass class StockCandle: t: datetime.datetime o: float h: float l: float c: float v: int ``` StockCandle represents a single stock candle (OHLCV data), encapsulating price and volume 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. - `v` (int): The trading volume. ### Notes - The `t` field is automatically converted to a `datetime.datetime` object from a Unix timestamp. ## StockCandlesHumanReadable ```python @dataclass class StockCandlesHumanReadable: Date: datetime.datetime Open: float High: float Low: float Close: float Volume: int ``` StockCandlesHumanReadable represents a stock 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. - `Volume` (int): The trading volume. ### 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`).