MarketData SDK

Options
in package
uses UniversalParameters, ValidatesInputs

Class Options

Handles API requests related to options data.

Table of Contents

Constants

BASE_URL  = "v1/options/"
The base URL for options-related API endpoints.

Properties

$client  : Client
The MarketDataApp API client instance.

Methods

__construct()  : mixed
Options constructor.
expirations()  : Expirations
Get a list of current or historical option expiration dates for an underlying symbol. If no optional parameters are used, the endpoint returns all expiration dates in the option chain.
lookup()  : Lookup
Generate a properly formatted OCC option symbol based on the user's human-readable description of an option.
option_chain()  : OptionChains
Get a current or historical end of day options chain for an underlying ticker symbol. Optional parameters allow for extensive filtering of the chain. Use the optionSymbol returned from this endpoint to get quotes, greeks, or other information using the other endpoints.
quotes()  : Quotes
Get current or historical end of day quotes for one or more options contracts.
strikes()  : Strikes
Get a list of current or historical options strikes for an underlying symbol. If no optional parameters are used, the endpoint returns the strikes for every expiration in the chain.
canParseAsDate()  : bool
Check if a string can be parsed as a date.
execute()  : object
Execute a single API request with universal parameters.
execute_in_parallel()  : array<string|int, mixed>
Execute multiple API requests in parallel with universal parameters.
mergeParameters()  : Parameters
Merge method-level parameters with client default parameters.
mergeQuotesResponses()  : Quotes
Merge multiple quotes responses into a single Quotes object.
parseDateToTimestamp()  : int|null
Parse a date string to unix timestamp.
quotesMultiple()  : Quotes
Get quotes for multiple option symbols concurrently.
quotesMultipleCsv()  : Quotes
Handle CSV format for multiple option symbols.
validateCountryCode()  : void
Validate ISO 3166 two-letter country code.
validateDateRange()  : void
Validate date range logic.
validateNonEmptyArray()  : void
Validate that an array is non-empty.
validateNonEmptyString()  : void
Validate that a string is non-empty.
validateNumericRange()  : void
Validate that min < max when both are provided.
validatePositiveInteger()  : void
Validate that an integer is positive if provided.
validatePositiveNumber()  : void
Validate that a number (int or float) is positive if provided.
validateResolution()  : void
Validate resolution format.
validateSymbols()  : void
Validate symbols array (trim and ensure non-empty).

Constants

BASE_URL

The base URL for options-related API endpoints.

public mixed BASE_URL = "v1/options/"

Properties

$client

The MarketDataApp API client instance.

private Client $client

Methods

__construct()

Options constructor.

public __construct(Client $client) : mixed
Parameters
$client : Client

The MarketDataApp API client instance.

expirations()

Get a list of current or historical option expiration dates for an underlying symbol. If no optional parameters are used, the endpoint returns all expiration dates in the option chain.

public expirations(string $symbol[, int|float|null $strike = null ][, string|null $date = null ][, Parameters|null $parameters = null ]) : Expirations
APIYes
Parameters
$symbol : string

The underlying ticker symbol for the options chain you wish to lookup.

$strike : int|float|null = null

Limit the lookup of expiration dates to the strike provided. This will cause the endpoint to only return expiration dates that include this strike. Accepts decimal values (e.g., 12.5) for non-standard strikes.

$date : string|null = null

Use to lookup a historical list of expiration dates from a specific previous trading day. If date is omitted the expiration dates will be from the current trading day during market hours or from the last trading day when the market is closed. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

$parameters : Parameters|null = null

Universal parameters for all methods (such as format).

Tags
link

API Documentation

see
strikes()

For available strike prices

see
option_chain()

For full option chain data

example

// Get all expiration dates for AAPL $expirations = $client->options->expirations('AAPL');

// Get expirations that have a $200 strike $expirations = $client->options->expirations('AAPL', strike: 200);

throws
ApiException|GuzzleException
Return values
Expirations

lookup()

Generate a properly formatted OCC option symbol based on the user's human-readable description of an option.

public lookup(string $input[, Parameters|null $parameters = null ]) : Lookup
APIYes

This endpoint converts text such as "AAPL 7/28/23 $200 Call" to OCC option symbol format: AAPL230728C00200000.

Parameters
$input : string

The human-readable string input that contains

  • (1) stock symbol
  • (2) strike
  • (3) expiration date
  • (4) option side (i.e. put or call).
$parameters : Parameters|null = null

Universal parameters for all methods (such as format).

This endpoint will translate the user's input into a valid OCC option symbol. Example: "AAPL 7/28/23 $200 Call".

Tags
link

API Documentation

see
quotes()

Use the returned OCC symbol to get option quotes

example

// Convert human-readable description to OCC symbol $lookup = $client->options->lookup('AAPL 7/28/23 $200 Call'); echo $lookup->option_symbol; // AAPL230728C00200000

Return values
Lookup

option_chain()

Get a current or historical end of day options chain for an underlying ticker symbol. Optional parameters allow for extensive filtering of the chain. Use the optionSymbol returned from this endpoint to get quotes, greeks, or other information using the other endpoints.

public option_chain(string $symbol[, string|null $date = null ][, string|Expiration $expiration = null ][, string|null $from = null ][, string|null $to = null ][, int|null $month = null ][, int|null $year = null ][, bool $weekly = true ][, bool $monthly = true ][, bool $quarterly = true ][, bool $non_standard = null ][, int|null $dte = null ][, string|float|null $delta = null ][, Side|null $side = null ][, Range $range = Range::ALL ][, string|null $strike = null ][, int|null $strike_limit = null ][, float|null $min_bid = null ][, float|null $max_bid = null ][, float|null $min_ask = null ][, float|null $max_ask = null ][, float|null $max_bid_ask_spread = null ][, float|null $max_bid_ask_spread_pct = null ][, int|null $min_open_interest = null ][, int|null $min_volume = null ][, bool|null $am = null ][, bool|null $pm = null ][, Parameters|null $parameters = null ]) : OptionChains
APIYes
Parameters
$symbol : string

The ticker symbol of the underlying asset.

$date : string|null = null

Use to lookup a historical end of day options chain from a specific trading day. If no date is specified the chain will be the most current chain available during market hours. When the market is closed the chain will be from the last trading day. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

$expiration : string|Expiration = null
                                             - Limits the option chain to a specific expiration date.
                                             Accepted date inputs: ISO 8601, unix, spreadsheet. This
                                             parameter is only required if requesting a quote along with the
                                             chain. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.
  • If omitted the next monthly expiration for real-time quotes or the next monthly expiration relative to the date parameter for historical quotes will be returned.

  • Use the keyword all to return the complete option chain.

CAUTION: Combining the all parameter with large options chains such as SPX, SPY, QQQ, etc. can cause you to consume your requests very quickly. The full SPX option chain has more than 20,000 contracts. A request is consumed for each contact you request with a price in the option chain.

$from : string|null = null

Limit the option chain to expiration dates after from (inclusive). Should be combined with to create a range. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

$to : string|null = null

Limit the option chain to expiration dates before to (not inclusive). Should be combined with from to create a range. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

$month : int|null = null

Limit the option chain to options that expire in a specific month (1-12).

$year : int|null = null

Limit the option chain to options that expire in a specific year.

$weekly : bool = true

Limit the option chain to weekly expirations by setting weekly to true and omitting the monthly and quarterly parameters. If set to false, no weekly expirations will be returned.

$monthly : bool = true

Limit the option chain to standard monthly expirations by setting monthly to true and omitting the weekly and quarterly parameters. If set to false, no monthly expirations will be returned.

$quarterly : bool = true

Limit the option chain to quarterly expirations by setting quarterly to true and omitting the weekly and monthly parameters. If set to false, no quarterly expirations will be returned.

$non_standard : bool = null

Include non-standard contracts by nonstandard to true. If set to false, no non-standard options expirations will be returned. If no parameter is provided, the output will default to false.

$dte : int|null = null

Days to expiry. Limit the option chain to a single expiration date closest to the dte provided. Should not be used together with from and to. Take care before combining with weekly, monthly, quarterly, since that will limit the expirations dte can return. If you are using the date parameter, dte is relative to the date provided.

$delta : string|float|null = null
                                             - Limit the option chain to a single strike closest to the
                                             delta provided. (e.g. .50)
                                             - Limit the option chain to a specific set of deltas (e.g.
                                             .60,.30)
                                             - Limit the option chain to an open interval of strikes using a
                                             logical expression (e.g. >.50)
                                             - Limit the option chain to a closed interval of strikes by
                                             specifying both endpoints. (e.g. .30-.60)

TIP: Filter strikes using the aboslulte value of the delta. The values used will always return both sides of the chain (e.g. puts & calls). This means you must filter using side to exclude puts or calls. Delta cannot be used to filter the side of the chain, only the strikes.

$side : Side|null = null

Limit the option chain to either call or put. If omitted, both sides will be returned.

$range : Range = Range::ALL

Limit the option chain to strikes that are in the money, out of the money, at the money, or include all. If omitted all options will be returned.

$strike : string|null = null
  • Limit the option chain to options with the specific strike specified. (e.g. 400)
  • Limit the option chain to a specific set of strikes (e.g. 400,405)
  • Limit the option chain to an open interval of strikes using a logical expression (e.g. >400)
  • Limit the option chain to a closed interval of strikes by specifying both endpoints. (e.g. 400-410)
$strike_limit : int|null = null

Limit the number of total strikes returned by the option chain. For example, if a complete chain included 30 strikes and the limit was set to 10, the 20 strikes furthest from the money will be excluded from the response.

TIP: If strikeLimit is combined with the range or side parameter, those parameters will be applied first. In the above example, if the range were set to itm (in the money) and side set to call, all puts and out of the money calls would be first excluded by the range parameter and then strikeLimit will return a maximum of 10 in the money calls that are closest to the money. If the side parameter has not been used but range has been specified, then strikeLimit will return the requested number of calls and puts for each side of the chain, but duplicating the number of strikes that are received.

$min_bid : float|null = null

Limit the option chain to options with a bid price greater than or equal to the number provided.

$max_bid : float|null = null

Limit the option chain to options with a bid price less than or equal to the number provided.

$min_ask : float|null = null

Limit the option chain to options with an ask price greater than or equal to the number provided.

$max_ask : float|null = null

Limit the option chain to options with an ask price less than or equal to the number provided.

$max_bid_ask_spread : float|null = null

Limit the option chain to options with a bid-ask spread less than or equal to the number provided.

$max_bid_ask_spread_pct : float|null = null

Limit the option chain to options with a bid-ask spread less than or equal to the percent provided (relative to the underlying). For example, a value of 0.5% would exclude all options trading with a bid-ask spread greater than $1.00 in an underlying that trades at $200.

$min_open_interest : int|null = null

Limit the option chain to options with an open interest greater than or equal to the number provided.

$min_volume : int|null = null

Limit the option chain to options with a volume transacted greater than or equal to the number provided.

$am : bool|null = null

Limit the option chain to AM-settled index options. These are options that settle based on the opening price of the index on expiration day. Only applicable to index options like SPX. When true, only AM-settled options are returned.

$pm : bool|null = null

Limit the option chain to PM-settled index options. These are options that settle based on the closing price of the index on expiration day. Only applicable to index options like SPX. When true, only PM-settled options are returned.

$parameters : Parameters|null = null

Universal parameters for all methods (such as format).

Tags
link

API Documentation

see
expirations()

For available expiration dates

see
strikes()

For available strike prices

see
quotes()

For individual option quotes

example

// Get calls for a specific expiration $chain = $client->options->option_chain('AAPL', expiration: '2025-01-17', side: Side::CALL);

// Get ATM options with delta filtering $chain = $client->options->option_chain('SPY', expiration: '2025-01-17', delta: 0.50);

throws
GuzzleException|ApiException
Return values
OptionChains

quotes()

Get current or historical end of day quotes for one or more options contracts.

public quotes(string|array<string|int, mixed> $option_symbols[, string|null $date = null ][, string|null $from = null ][, string|null $to = null ][, Parameters|null $parameters = null ]) : Quotes
APIYes

When multiple option symbols are provided, requests are made concurrently using a sliding window of up to 50 concurrent requests for optimal throughput.

Parameters
$option_symbols : string|array<string|int, mixed>

The option symbol(s) (as defined by the OCC) for the option(s) you wish to lookup. Use the current OCC option symbol format, even for historic options that quoted before the format change in 2010. Can be a single string or an array of strings for multiple symbols.

$date : string|null = null

Use to lookup a historical end of day quote from a specific trading day. If no date is specified the quote will be the most current price available during market hours. When the market is closed the quote will be from the last trading day. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

$from : string|null = null

Use to lookup a series of end of day quotes. From is the oldest (leftmost) date to return (inclusive). If from/to is not specified the quote will be the most current price available during market hours. When the market is closed the quote will be from the last trading day. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

$to : string|null = null

Use to lookup a series of end of day quotes. To is the newest (rightmost) date to return (exclusive). If from/to is not specified the quote will be the most current price available during market hours. When the market is closed the quote will be from the last trading day. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

$parameters : Parameters|null = null

Universal parameters for all methods (such as format).

Tags
link

API Documentation

see
option_chain()

For full option chain data

see
lookup()

To convert human-readable descriptions to OCC symbols

example

// Get quote for a single option $quotes = $client->options->quotes('AAPL250117C00200000');

// Get quotes for multiple options (concurrent requests) $quotes = $client->options->quotes(['AAPL250117C00180000', 'AAPL250117C00200000']);

throws
ApiException|GuzzleException|Throwable
Return values
Quotes

strikes()

Get a list of current or historical options strikes for an underlying symbol. If no optional parameters are used, the endpoint returns the strikes for every expiration in the chain.

public strikes(string $symbol[, string|null $expiration = null ][, string|null $date = null ][, Parameters|null $parameters = null ]) : Strikes
APIYes
Parameters
$symbol : string

The underlying ticker symbol for the options chain you wish to lookup.

$expiration : string|null = null

Limit the lookup of strikes to options that expire on a specific expiration date.

$date : string|null = null

Use to lookup a historical list of strikes from a specific previous trading day. If date is omitted the expiration dates will be from the current trading day during market hours or from the last trading day when the market is closed. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.

$parameters : Parameters|null = null

Universal parameters for all methods (such as format).

Tags
link

API Documentation

see
expirations()

For available expiration dates

see
option_chain()

For full option chain data

example

// Get all strikes for AAPL $strikes = $client->options->strikes('AAPL');

// Get strikes for a specific expiration $strikes = $client->options->strikes('AAPL', expiration: '2025-01-17');

throws
ApiException|GuzzleException
Return values
Strikes

canParseAsDate()

Check if a string can be parsed as a date.

protected canParseAsDate(string|null $value) : bool

Similar to Python SDK's check_is_date() function. Returns true if the value contains "-" or "/" (indicating parseable date format) or is numeric (unix timestamp or spreadsheet format).

This allows relative dates ("today", "yesterday", "-5 days") and option expiration dates ("December expiration") to pass through without validation.

Parameters
$value : string|null

The value to check

Return values
bool

True if the value can be parsed as a date

execute()

Execute a single API request with universal parameters.

protected execute(string $method, array<string|int, mixed> $arguments, Parameters|null $parameters) : object
Parameters
$method : string

The API method to call.

$arguments : array<string|int, mixed>

The arguments for the API call.

$parameters : Parameters|null

Optional Parameters object for additional settings.

Return values
object

The API response as an object.

execute_in_parallel()

Execute multiple API requests in parallel with universal parameters.

protected execute_in_parallel(array<string|int, mixed> $calls[, Parameters|null $parameters = null ][, array<string|int, mixed>|null &$failedRequests = null ]) : array<string|int, mixed>
Parameters
$calls : array<string|int, mixed>

An array of method calls, each containing the method name and arguments.

$parameters : Parameters|null = null

Optional Parameters object for additional settings.

$failedRequests : array<string|int, mixed>|null = null

Optional by-reference array to collect failed requests instead of throwing. When provided, exceptions are stored here keyed by their call index.

Tags
throws
Throwable

When $failedRequests is not provided and any request fails.

Return values
array<string|int, mixed>

An array of API responses. When $failedRequests is provided, results are keyed by original call index.

mergeParameters()

Merge method-level parameters with client default parameters.

protected mergeParameters(Parameters|null $methodParams) : Parameters

Priority order (highest to lowest):

  1. Method-level parameters (if provided)
  2. Client default parameters ($this->client->default_params)
  3. Default Parameters() values
Parameters
$methodParams : Parameters|null

Method-level parameters, or null to use only client defaults.

Return values
Parameters

Merged parameters instance.

mergeQuotesResponses()

Merge multiple quotes responses into a single Quotes object.

protected mergeQuotesResponses(array<string|int, mixed> $responses[, array<string|int, mixed> $failedRequests = [] ][, array<string|int, mixed> $symbols = [] ]) : Quotes
Parameters
$responses : array<string|int, mixed>

Array of response objects from execute_in_parallel, keyed by call index.

$failedRequests : array<string|int, mixed> = []

Array of exceptions from failed requests, keyed by call index.

$symbols : array<string|int, mixed> = []

Original symbols array for error reporting.

Return values
Quotes

Merged quotes response.

parseDateToTimestamp()

Parse a date string to unix timestamp.

protected parseDateToTimestamp(string|null $value) : int|null

Handles ISO 8601, unix timestamps, spreadsheet dates, and American format.

Parameters
$value : string|null

The date string to parse

Return values
int|null

Unix timestamp or null if cannot be parsed

quotesMultiple()

Get quotes for multiple option symbols concurrently.

protected quotesMultiple(array<string|int, mixed> $option_symbols, string|null $date, string|null $from, string|null $to, Parameters|null $parameters) : Quotes

Uses a sliding window of up to 50 concurrent requests. As each request completes, the next one starts immediately for optimal throughput.

Parameters
$option_symbols : array<string|int, mixed>

Array of option symbols (OCC format).

$date : string|null

Historical date for EOD quotes.

$from : string|null

Start date for series of EOD quotes.

$to : string|null

End date for series of EOD quotes.

$parameters : Parameters|null

Universal parameters.

Tags
throws
Throwable
Return values
Quotes

Merged quotes from all symbols.

quotesMultipleCsv()

Handle CSV format for multiple option symbols.

protected quotesMultipleCsv(array<string|int, mixed> $symbols, string|null $date, string|null $from, string|null $to, Parameters|null $parameters, Parameters $mergedParams) : Quotes

Makes separate requests for each symbol, with headers=true on the first request (unless user explicitly set add_headers=false) and headers=false on subsequent requests. Combines all responses into a single CSV output.

Parameters
$symbols : array<string|int, mixed>

Deduplicated and trimmed option symbols.

$date : string|null

Historical date for EOD quotes.

$from : string|null

Start date for series of EOD quotes.

$to : string|null

End date for series of EOD quotes.

$parameters : Parameters|null

Original parameters from caller.

$mergedParams : Parameters

Merged parameters with defaults applied.

Tags
throws
Throwable
Return values
Quotes

Quotes object containing combined CSV.

validateCountryCode()

Validate ISO 3166 two-letter country code.

protected validateCountryCode(string $country) : void
Parameters
$country : string

The country code to validate

Tags
throws
InvalidArgumentException

If country code is invalid

validateDateRange()

Validate date range logic.

protected validateDateRange(string|null $from, string|null $to[, int|null $countback = null ][, string $context = '' ]) : void

Rules:

  • If to is provided, it requires either from OR countback (but not both)
  • If both from and to are parseable dates, validates that from < to
  • If countback is provided, it must be a positive integer

This allows relative dates and option expiration dates to pass through without strict format validation.

Parameters
$from : string|null

The start date

$to : string|null

The end date

$countback : int|null = null

The countback value

$context : string = ''

Optional context for error messages

Tags
throws
InvalidArgumentException

If validation fails

validateNonEmptyArray()

Validate that an array is non-empty.

protected validateNonEmptyArray(array<string|int, mixed> $value, string $fieldName) : void
Parameters
$value : array<string|int, mixed>

The value to validate

$fieldName : string

The field name for error messages

Tags
throws
InvalidArgumentException

If array is empty

validateNonEmptyString()

Validate that a string is non-empty.

protected validateNonEmptyString(string $value, string $fieldName) : void
Parameters
$value : string

The value to validate

$fieldName : string

The field name for error messages

Tags
throws
InvalidArgumentException

If value is empty

validateNumericRange()

Validate that min < max when both are provided.

protected validateNumericRange(float|null $min, float|null $max, string $minField, string $maxField) : void
Parameters
$min : float|null

The minimum value

$max : float|null

The maximum value

$minField : string

The minimum field name for error messages

$maxField : string

The maximum field name for error messages

Tags
throws
InvalidArgumentException

If min >= max

validatePositiveInteger()

Validate that an integer is positive if provided.

protected validatePositiveInteger(int|null $value, string $fieldName) : void
Parameters
$value : int|null

The value to validate

$fieldName : string

The field name for error messages

Tags
throws
InvalidArgumentException

If value is not positive

validatePositiveNumber()

Validate that a number (int or float) is positive if provided.

protected validatePositiveNumber(int|float|null $value, string $fieldName) : void
Parameters
$value : int|float|null

The value to validate

$fieldName : string

The field name for error messages

Tags
throws
InvalidArgumentException

If value is not positive

validateResolution()

Validate resolution format.

protected validateResolution(string $resolution) : void

Valid resolutions: minutely, hourly, daily, weekly, monthly, yearly, or numeric with optional suffix (1, 3, 5, 15, 30, 45, H, 1H, 2H, D, 1D, 2D, etc.)

Parameters
$resolution : string

The resolution to validate

Tags
throws
InvalidArgumentException

If resolution is invalid

validateSymbols()

Validate symbols array (trim and ensure non-empty).

protected validateSymbols(array<string|int, mixed> $symbols) : void
Parameters
$symbols : array<string|int, mixed>

The symbols array to validate

Tags
throws
InvalidArgumentException

If symbols array is invalid


        
On this page

Search results