Skip to main content

Quotes

Retrieve live quotes for any supported stock symbol.

Making Requests​

Use the quotes() method on the stocks resource to fetch stock quotes. The method supports multiple output formats:

Output FormatReturn TypeDescription
DATAFRAMEpandas.DataFrame or polars.DataFrameReturns a DataFrame with quotes indexed by symbol (default).
INTERNALlist[StockQuote] or list[StockQuotesHumanReadable]Returns a list of StockQuote objects. When use_human_readable=True, returns a list of StockQuotesHumanReadable objects with capitalized field names.
JSONdictReturns the raw JSON response as a dictionary.
CSVstrWrites CSV data to file and returns the filename string.

quotes​

def quotes(
    symbols: list[str] | str,
    *,
    use_52_week: bool = None,
    extended: bool = 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[StockQuote] | list[StockQuotesHumanReadable] | dict | str | MarketDataClientErrorResult

Fetches stock quotes for one or more symbols. The symbols parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.

Parameters​

  • symbols (list[str] | str)

    A single symbol string or a list of symbol strings for which to fetch quotes.

  • use_52_week (bool, optional)

    Whether to use the 52 week high and low. Uses API alias 52week.

  • extended (bool, optional)

    Whether to use the extended quotes.

  • 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. If not provided, all available columns are returned. See Settings for details.

  • add_headers (optional)

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

  • use_human_readable (optional)

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

  • mode (Mode, optional)

    The data feed mode to use. Available options: Mode.LIVE, Mode.CACHED, Mode.DELAYED. See Settings for details.

  • filename (str | Path, optional)

    File path for CSV output (only used with output_format=OutputFormat.CSV). Must end with .csv. Directory must exist. File must not already exist. If not provided, a timestamped file is created in output/ directory.

Returns​

  • list[StockQuote] | list[StockQuotesHumanReadable] | dict | str | MarketDataClientErrorResult

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

Notes​

  • When using OutputFormat.DATAFRAME, the DataFrame is indexed by the symbol column.
  • When using OutputFormat.INTERNAL, timestamps are automatically converted to datetime.datetime objects.
  • When using OutputFormat.CSV, the method writes to a file and returns the filename string.
from marketdata.client import MarketDataClient

client = MarketDataClient()

# Get stock quotes as DataFrame (default)
# symbols can be passed positionally or as keyword
df = client.stocks.quotes("AAPL")
# or
df = client.stocks.quotes(symbols="AAPL")

# Get quotes for multiple symbols
df = client.stocks.quotes(["AAPL", "MSFT"])

print(df)

Output​

       ask  askSize    bid  bidSize      mid      last   change  changepct    volume      updated
symbol                                                                                              
AAPL  278.02      100  277.97      100  277.995  278.0188  -0.0112         0.0  4964676  2025-01-13 16:21:46

StockQuote​

@dataclass
class StockQuote:
    symbol: str
    ask: float
    askSize: int
    bid: float
    bidSize: int
    mid: float
    last: float
    change: float
    changepct: float
    volume: int
    updated: datetime.datetime

StockQuote represents a single stock quote, encapsulating various details such as prices, volumes, and timestamps.

Properties​

  • symbol (str): The stock symbol.
  • ask (float): The asking price for the stock.
  • askSize (int): The size (quantity) of the ask.
  • bid (float): The bidding price for the stock.
  • bidSize (int): The size (quantity) of the bid.
  • mid (float): The mid price calculated between the ask and bid prices.
  • last (float): The last traded price for the stock.
  • change (float): The price change.
  • changepct (float): The percentage change in price.
  • change_percent (float): Property that returns changepct for convenience.
  • volume (int): The trading volume for the stock.
  • updated (datetime.datetime): The time when the quote was last updated (automatically converted from timestamp).

Notes​

  • The updated field is automatically converted to a datetime.datetime object from a Unix timestamp.
  • The change_percent property provides convenient access to the changepct field.

StockQuotesHumanReadable​

@dataclass
class StockQuotesHumanReadable:
    Symbol: str
    Ask: float
    Ask_Size: int
    Bid: float
    Bid_Size: int
    Mid: float
    Last: float
    Change_Price: float
    Change_Percent: float
    Volume: int
    Date: datetime.datetime

StockQuotesHumanReadable represents a stock quote in human-readable format with capitalized field names and formatted values.

Properties​

  • Symbol (str): The stock symbol.
  • Ask (float): The asking price for the stock.
  • Ask_Size (int): The size (quantity) of the ask.
  • Bid (float): The bidding price for the stock.
  • Bid_Size (int): The size (quantity) of the bid.
  • Mid (float): The mid price calculated between the ask and bid prices.
  • Last (float): The last traded price for the stock.
  • Change_Price (float): The price change.
  • Change_Percent (float): The percentage change in price.
  • Volume (int): The trading volume for the stock.
  • Date (datetime.datetime): The time when the quote was last updated (automatically converted from timestamp).

Notes​

  • The Date field is automatically converted to a datetime.datetime object from a Unix timestamp.
  • Field names use capitalized format with underscores (e.g., Ask_Size instead of askSize).