Lookup

Lookup an option symbol from a human-readable string format.

Making Requests

Use the lookup() method on the options resource to lookup option symbols. The method supports multiple output formats:

Output Format	Return Type	Description
DATAFRAME	pandas.DataFrame or polars.DataFrame	Returns a DataFrame with option lookup data indexed by optionSymbol (default).
INTERNAL	OptionsLookup or OptionsLookupHumanReadable	Returns an OptionsLookup object. When use_human_readable=True, returns an OptionsLookupHumanReadable 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.

lookup

def lookup(
    lookup: 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,
) -> OptionsLookup | OptionsLookupHumanReadable | dict | str | MarketDataClientErrorResult

Fetches option lookup data for a given lookup string. The lookup string should contain the underlying symbol, expiration date, strike price, and option side in the format: "SYMBOL DD-MM-YYYY STRIKE SIDE" (e.g., "AAPL 20-12-2024 150.0 call"). The lookup parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.

Parameters

• lookup (str)

  The lookup string in the format "SYMBOL DD-MM-YYYY STRIKE SIDE" (e.g., "AAPL 20-12-2024 150.0 call").

• 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 feed mode to use. See Settings for details.

• filename (str | Path, optional)

  File path for CSV output (only used with output_format=OutputFormat.CSV).

Returns

• OptionsLookup | OptionsLookupHumanReadable | dict | str | MarketDataClientErrorResult

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

Notes

• The lookup string format is: "SYMBOL DD-MM-YYYY STRIKE SIDE"
• Example: "AAPL 20-12-2024 150.0 call" or "AAPL 20-12-2024 150.0 put"
• When using OutputFormat.DATAFRAME, the DataFrame is indexed by the optionSymbol column.

Example (DataFrame)

from marketdata.client import MarketDataClient

client = MarketDataClient()

# Get option lookup as DataFrame (default)
# lookup can be passed positionally or as keyword
df = client.options.lookup("AAPL 20-12-2024 150.0 call")
# or
df = client.options.lookup(lookup="AAPL 20-12-2024 150.0 call")

print(df)

Example (Internal)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get option lookup as internal object
lookup_result = client.options.lookup(
    "AAPL 20-12-2024 150.0 call",
    output_format=OutputFormat.INTERNAL
)

# Access lookup properties
print(f"Option Symbol: {lookup_result.optionSymbol}")

Example (JSON)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get option lookup as JSON
lookup_result = client.options.lookup(
    "AAPL 20-12-2024 150.0 call",
    output_format=OutputFormat.JSON
)

print(lookup_result)

Example (CSV)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat
from pathlib import Path

client = MarketDataClient()

# Get option lookup as CSV
csv_file = client.options.lookup(
    "AAPL 20-12-2024 150.0 call",
    output_format=OutputFormat.CSV,
    filename=Path("lookup.csv")
)

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

Example (Human Readable)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get option lookup in human-readable format
lookup_result = client.options.lookup(
    "AAPL 20-12-2024 150.0 call",
    output_format=OutputFormat.INTERNAL,
    use_human_readable=True
)

# Access lookup properties
print(f"Symbol: {lookup_result.Symbol}")

OptionsLookup

@dataclass
class OptionsLookup:
    s: str
    optionSymbol: str

OptionsLookup represents the result of an option symbol lookup, containing the resolved option symbol.

Properties

• s (str): Status indicator ("ok" for successful responses).
• optionSymbol (str): The resolved option symbol.

OptionsLookupHumanReadable

@dataclass
class OptionsLookupHumanReadable:
    Symbol: str

OptionsLookupHumanReadable represents an option symbol lookup result in human-readable format with capitalized field names.

Properties

• Symbol (str): The resolved option symbol.

Notes

• Field names use capitalized format (e.g., Symbol instead of optionSymbol).