Field Conventions & Units
This document details field naming conventions, schema mappings, and unit representations across the WSO Options Data API.
Endpoint Field Mapping
| Concept | Schema | Field Name | Format / Units | Notes |
|---|---|---|---|---|
| Underlying Symbol | QuoteResponse | symbol | string (ticker) | Primary underlying equity ticker symbol. |
| Underlying Symbol | FlowTradePrint | ticker | string (ticker) | Underlying equity ticker in options flow trade prints. |
| Underlying Symbol | OptionQuote | underlying | string (ticker) | Reference to underlying equity ticker in contract quote objects. |
| Option Contract Symbol | OptionQuote | optionSymbol | string (OCC format) | Standard OCC option symbol (e.g. SPY270917C00800000; up to 21 chars). |
| Option Contract Symbol | FilterResult | optionKey | string (OCC format) | Contract key in screener candidate rows. |
| Underlying Spot Price | QuoteResponse | price | number (dollars) | Current underlying equity spot price in USD. |
| Underlying Spot Price | OptionQuote | underlyingPrice | number (dollars) | Underlying equity spot price at option quote capture. |
| Underlying Spot Price | FlowTradePrint | underlyingPrice | number (dollars) | Underlying stock price at options flow trade execution. |
| Underlying Spot Price | FilterResult | stockPrice | number (dollars) | Underlying equity price at screener evaluation time. |
| Bid & Ask Prices | OptionQuote | bid | number (dollars/share) | Highest buying price per share in market quote. |
| Bid & Ask Prices | OptionQuote | ask | number (dollars/share) | Lowest selling price per share in market quote. |
| Bid & Ask Prices | FilterResult | bidPrice | number (dollars/share) | Best bid price per share in screener candidate contracts. |
| Option Side & Type | OptionQuote | side | "call" | "put" | Contract flavor in options chain and quote responses. |
| Option Side & Type | FlowTradePrint | side | "ask" | "bid" | "mid" | "unknown" | Trade execution / fill side on the tape. |
| Option Side & Type | FlowTradePrint | optionType | "call" | "put" | Contract flavor (call or put) in options flow trade prints. |
| Option Side & Type | FilterResult | type | "call" | "put" | Contract flavor in screener results. |
| Expiration & Timestamps | OptionQuote | expiration | string (YYYY-MM-DD) | Option contract expiration calendar date. |
| Expiration & Timestamps | FilterResult | expiration | string (ISO-8601) | Contract expiration timestamp in screener results. |
| Expiration & Timestamps | OptionQuote | asOf | string (ISO-8601 UTC) or null | Timestamp of market quote snapshot, or null if unknown. |
| Expiration & Timestamps | QuoteResponse | asOf | string (ISO-8601 UTC) or null | Timestamp of equity quote snapshot, or null if unknown. |
| Volatility & Greeks | OptionQuote | iv | number (percentage) | Implied volatility expressed as percentage (e.g. 22.37 represents 22.37%). |
| Volatility & Greeks | OptionQuote | delta | number (decimal fraction) | Option delta sensitivity, bounded between -1.0 and 1.0. |
| Volatility & Greeks | OptionQuote | gamma | number (decimal) | Option gamma rate of change per $1 move in underlying. |
| Volatility & Greeks | OptionQuote | theta | number (dollars/day) | Option time decay per calendar day. |
| Volatility & Greeks | OptionQuote | vega | number (dollars/% IV) | Option price change per 1% change in implied volatility. |
| Volatility & Greeks | TopIvStock | stockIV | number (percentage) | Underlying equity 30-day annualized implied volatility percentage. |
| Volatility & Greeks | TopIvStock | ivr | number (0–100 rank) | Implied Volatility Rank over 52-week high/low range. |
| Gamma Exposure & Grid | GexHeatmapCell | callGex | number (dollars/1% move) | Dealer gamma exposure from call open interest at cell coordinate. |
| Gamma Exposure & Grid | GexHeatmapCell | putGex | number (dollars/1% move) | Dealer gamma exposure from put open interest at cell coordinate. |
| Gamma Exposure & Grid | GexHeatmapCell | netGex | number (dollars/1% move) | Net dealer gamma exposure at strike/expiration cell. |
| Net Flow Time Series | NetFlowPoint | netCallPremium | number (dollars) | Net call premium flow for the 1-minute aggregation interval. |
Key Unit Representations
Implied Volatility (IV)
Standard contract IV (iv) and equity volatility (stockIV) are expressed as percentages: 22.37 represents 22.37%. IV rank (ivr) is an integer or decimal percentile ranking between 0 and 100.
Bid-Ask Spreads
Percentage spread fields (spreadPercent, bidAskSpreadPct, bidAskSpreadPctMax) are expressed as percentages: 8 represents 8%. Absolute spread fields (bidAskSpreadAbs) represent dollar amounts.
Greeks & Sensitivities
Delta is a signed decimal ratio bounded strictly between -1.0 and 1.0 (e.g. -0.25). Other Greeks have unit-based dimensions: gamma is delta change per $1 underlying move, theta is daily decay in dollars, and vega is dollar change per 1% move in implied volatility.
OCC Option Symbols
Option contract keys follow standard OCC symbology up to 21 characters: 1–6 character underlying ticker root, 6-digit expiration date (YYMMDD), contract type ('C' or 'P'), and 8-digit strike price in thousandths of a dollar (e.g. SPY270917C00800000).