# Option Quotes (Python SDK)

Retrieve quotes for one or more option symbols.

## Making Requests

Use the `quotes()` method on the `options` resource to fetch option quotes. The method supports multiple output formats and automatically handles multiple symbols by fetching them concurrently:

| Output Format | Return Type                                     | Description                                                                                                                                                                       |
|---------------|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame`        | Returns a DataFrame with option quotes indexed by optionSymbol (default).                                                                                                         |
| **INTERNAL**  | `OptionsQuotes` or `OptionsQuotesHumanReadable` | Returns an OptionsQuotes object containing lists of option quote data. When `use_human_readable=True`, returns an OptionsQuotesHumanReadable object 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.                                                                                                                          |

<a name="quotes"></a>
## quotes

```python
def quotes(
    symbols: str | list[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,
) -> OptionsQuotes | OptionsQuotesHumanReadable | dict | str | MarketDataClientErrorResult
```

Fetches option quotes for one or more option symbols. Note: `quotes()` takes option symbols (e.g., "AAPL271217C00250000"), not stock 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` (str | list[str])

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

- `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

- `OptionsQuotes` | `OptionsQuotesHumanReadable` | `dict` | `str` | `MarketDataClientErrorResult`

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

### Notes

- Multiple option symbols are fetched concurrently (up to 50 concurrent requests by default).
- When using `OutputFormat.DATAFRAME`, the DataFrame is indexed by the `optionSymbol` column.
- The OptionsQuotes object contains lists of equal length for each field, allowing you to iterate through options by index.

### Example (DataFrame)

```python
from marketdata import MarketDataClient

client = MarketDataClient()

# Get option quotes as DataFrame (default)
# symbols can be passed positionally or as keyword
# Note: quotes() takes option symbols, not stock symbols
df = client.options.quotes("AAPL271217C00250000")
# or
df = client.options.quotes(symbols="AAPL271217C00250000")

# Get quotes for multiple option symbols
df = client.options.quotes(["AAPL271217C00250000", "AAPL271217P00250000"])

print(df)
```

### Example (Internal)

```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get option quotes as internal object
quotes = client.options.quotes(
    ["AAPL271217C00250000", "AAPL271217P00250000"],
    output_format=OutputFormat.INTERNAL
)

# Access option data by index
print(f"Number of options: {len(quotes.optionSymbol)}")
print(f"First option symbol: {quotes.optionSymbol[0]}")
print(f"First option bid: {quotes.bid[0]}")
print(f"First option ask: {quotes.ask[0]}")
```

### Example (JSON)

```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get option quotes as JSON
quotes = client.options.quotes(
    ["AAPL271217C00250000", "AAPL271217P00250000"],
    output_format=OutputFormat.JSON
)

print(quotes)
```

### Example (CSV)

```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path

client = MarketDataClient()

# Get option quotes as CSV
csv_file = client.options.quotes(
    ["AAPL271217C00250000", "AAPL271217P00250000"],
    output_format=OutputFormat.CSV,
    filename=Path("options_quotes.csv")
)

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

### Example (Human Readable)

```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get option quotes in human-readable format
quotes = client.options.quotes(
    ["AAPL271217C00250000", "AAPL271217P00250000"],
    output_format=OutputFormat.INTERNAL,
    use_human_readable=True
)

# Access option data by index
print(f"Number of options: {len(quotes.Symbol)}")
print(f"First option symbol: {quotes.Symbol[0]}")
print(f"First option underlying: {quotes.Underlying[0]}")
print(f"First option expiration: {quotes.Expiration_Date[0]}")
print(f"First option strike: {quotes.Strike[0]}")
print(f"First option bid: {quotes.Bid[0]}")
print(f"First option ask: {quotes.Ask[0]}")
```

<a name="OptionsQuotes"></a>
## OptionsQuotes

```python
@dataclass
class OptionsQuotes:
    s: str
    optionSymbol: list[str]
    underlying: list[str]
    expiration: list[datetime.datetime]
    side: list[str]
    strike: list[float]
    firstTraded: list[datetime.datetime]
    dte: list[int]
    updated: list[datetime.datetime]
    bid: list[float]
    bidSize: list[int]
    mid: list[float]
    ask: list[float]
    askSize: list[int]
    last: list[float]
    openInterest: list[int]
    volume: list[int]
    inTheMoney: list[bool]
    intrinsicValue: list[float]
    extrinsicValue: list[float]
    underlyingPrice: list[float]
    iv: list[float]
    delta: list[float]
    gamma: list[float]
    theta: list[float]
    vega: list[float]
```

OptionsQuotes represents option quotes data with lists of equal length for each field. All lists have the same length, allowing you to access option data by index.

### Properties

- `s` (str): Status indicator ("ok" for successful responses).
- `optionSymbol` (list[str]): List of option symbols.
- `underlying` (list[str]): List of underlying symbols.
- `expiration` (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
- `side` (list[str]): List of option sides ("call" or "put").
- `strike` (list[float]): List of strike prices.
- `firstTraded` (list[datetime.datetime]): List of first traded dates (automatically converted from timestamps).
- `dte` (list[int]): List of days to expiration.
- `updated` (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).
- `bid` (list[float]): List of bid prices.
- `bidSize` (list[int]): List of bid sizes.
- `mid` (list[float]): List of mid prices.
- `ask` (list[float]): List of ask prices.
- `askSize` (list[int]): List of ask sizes.
- `last` (list[float]): List of last traded prices.
- `openInterest` (list[int]): List of open interest values.
- `volume` (list[int]): List of trading volumes.
- `inTheMoney` (list[bool]): List indicating if options are in the money.
- `intrinsicValue` (list[float]): List of intrinsic values.
- `extrinsicValue` (list[float]): List of extrinsic values.
- `underlyingPrice` (list[float]): List of underlying prices.
- `iv` (list[float]): List of implied volatilities.
- `delta` (list[float]): List of Delta values.
- `gamma` (list[float]): List of Gamma values.
- `theta` (list[float]): List of Theta values.
- `vega` (list[float]): List of Vega values.

### Notes

- All lists have the same length, allowing you to access option data by index (e.g., `quotes.optionSymbol[0]`, `quotes.bid[0]`, etc.).
- Timestamp fields (`expiration`, `firstTraded`, `updated`) are automatically converted to `datetime.datetime` objects.

<a name="OptionsQuotesHumanReadable"></a>
## OptionsQuotesHumanReadable

```python
@dataclass
class OptionsQuotesHumanReadable:
    Symbol: list[str]
    Underlying: list[str]
    Expiration_Date: list[datetime.datetime]
    Option_Side: list[str]
    Strike: list[float | int]
    First_Traded: list[datetime.datetime]
    Days_To_Expiration: list[int]
    Date: list[datetime.datetime]
    Bid: list[float]
    Bid_Size: list[int]
    Mid: list[float]
    Ask: list[float]
    Ask_Size: list[int]
    Last: list[float]
    Open_Interest: list[int]
    Volume: list[int]
    In_The_Money: list[bool]
    Intrinsic_Value: list[float]
    Extrinsic_Value: list[float]
    Underlying_Price: list[float]
    IV: list[float]
    Delta: list[float]
    Gamma: list[float]
    Theta: list[float]
    Vega: list[float]
```

OptionsQuotesHumanReadable represents option quotes in human-readable format with capitalized field names and formatted values.

### Properties

- `Symbol` (list[str]): List of option symbols.
- `Underlying` (list[str]): List of underlying symbols.
- `Expiration_Date` (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
- `Option_Side` (list[str]): List of option sides ("call" or "put").
- `Strike` (list[float | int]): List of strike prices.
- `First_Traded` (list[datetime.datetime]): List of first traded dates (automatically converted from timestamps).
- `Days_To_Expiration` (list[int]): List of days to expiration.
- `Date` (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).
- `Bid` (list[float]): List of bid prices.
- `Bid_Size` (list[int]): List of bid sizes.
- `Mid` (list[float]): List of mid prices.
- `Ask` (list[float]): List of ask prices.
- `Ask_Size` (list[int]): List of ask sizes.
- `Last` (list[float]): List of last traded prices.
- `Open_Interest` (list[int]): List of open interest values.
- `Volume` (list[int]): List of trading volumes.
- `In_The_Money` (list[bool]): List indicating if options are in the money.
- `Intrinsic_Value` (list[float]): List of intrinsic values.
- `Extrinsic_Value` (list[float]): List of extrinsic values.
- `Underlying_Price` (list[float]): List of underlying prices.
- `IV` (list[float]): List of implied volatilities.
- `Delta` (list[float]): List of Delta values.
- `Gamma` (list[float]): List of Gamma values.
- `Theta` (list[float]): List of Theta values.
- `Vega` (list[float]): List of Vega values.

### Notes

- All lists have the same length, allowing you to access option data by index (e.g., `quotes.Symbol[0]`, `quotes.Bid[0]`, etc.).
- Timestamp fields (`Expiration_Date`, `First_Traded`, `Date`) are automatically converted to `datetime.datetime` objects.
- Field names use capitalized format with underscores (e.g., `Expiration_Date` instead of `expiration`, `Option_Side` instead of `side`, `Open_Interest` instead of `openInterest`).