Prices

Retrieve stock prices for any supported stock symbol.

Making Requests

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

Output Format	Return Type	Description
DATAFRAME	pandas.DataFrame or polars.DataFrame	Returns a DataFrame with prices indexed by symbol (default).
INTERNAL	list[StockPrice] or list[StockPricesHumanReadable]	Returns a list of StockPrice objects. When use_human_readable=True, returns a list of StockPricesHumanReadable 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.

prices

def prices(
    symbols: list[str] | str,
    *,
    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[StockPrice] | list[StockPricesHumanReadable] | dict | str | MarketDataClientErrorResult

Fetches stock prices 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 prices.

• 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 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[StockPrice] | list[StockPricesHumanReadable] | dict | str | MarketDataClientErrorResult

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

Example (DataFrame)

from marketdata import MarketDataClient

client = MarketDataClient()

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

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

print(df)

Example (Internal)

from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get stock prices as internal objects
prices = client.stocks.prices("AAPL", output_format=OutputFormat.INTERNAL)

# Access individual price properties
for price in prices:
    print(f"Symbol: {price.symbol}")
    print(f"Mid: {price.mid}")
    print(f"Change: {price.change}")
    print(f"Change Percent: {price.changepct}")
    print(f"Updated: {price.updated}")

Example (JSON)

from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get stock prices as JSON
prices = client.stocks.prices(["AAPL", "MSFT"], output_format=OutputFormat.JSON)

print(prices)

Example (CSV)

from marketdata import MarketDataClient, OutputFormat
from pathlib import Path

client = MarketDataClient()

# Get stock prices as CSV
csv_file = client.stocks.prices(
    ["AAPL", "MSFT"],
    output_format=OutputFormat.CSV,
    filename=Path("prices.csv")
)

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

Example (Human Readable)

from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get stock prices in human-readable format
prices = client.stocks.prices(
    "AAPL",
    output_format=OutputFormat.INTERNAL,
    use_human_readable=True
)

for price in prices:
    print(f"Symbol: {price.Symbol}")
    print(f"Mid: {price.Mid}")
    print(f"Change Price: {price.Change_Price}")
    print(f"Change Percent: {price.Change_Percent}")
    print(f"Date: {price.Date}")

StockPrice

@dataclass
class StockPrice:
    s: str
    symbol: str
    mid: float
    change: float
    changepct: float
    updated: datetime.datetime

StockPrice represents a single stock price, encapsulating various details such as prices and timestamps.

Properties

• s (str): Status indicator ("ok" for successful responses).
• symbol (str): The stock symbol.
• mid (float): The mid price calculated between the ask and bid prices.
• change (float): The price change.
• changepct (float): The percentage change in price.
• updated (datetime.datetime): The time when the price was last updated (automatically converted from timestamp).

Notes

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

StockPricesHumanReadable

@dataclass
class StockPricesHumanReadable:
    Symbol: str
    Mid: float
    Change_Price: float
    Change_Percent: float
    Date: datetime.datetime

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

Properties

• Symbol (str): The stock symbol.
• Mid (float): The mid price calculated between the ask and bid prices.
• Change_Price (float): The price change.
• Change_Percent (float): The percentage change in price.
• Date (datetime.datetime): The time when the price 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., Change_Price instead of change).