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
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
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
Return values
Expirationslookup()
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
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
Return values
Lookupoption_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
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
Return values
OptionChainsquotes()
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
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
Return values
Quotesstrikes()
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
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
Return values
StrikescanParseAsDate()
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
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):
- Method-level parameters (if provided)
- Client default parameters ($this->client->default_params)
- 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
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
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
validateDateRange()
Validate date range logic.
protected
validateDateRange(string|null $from, string|null $to[, int|null $countback = null ][, string $context = '' ]) : void
Rules:
- If
tois provided, it requires eitherfromORcountback(but not both) - If both
fromandtoare parseable dates, validates thatfrom<to - If
countbackis 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
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
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
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
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
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
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
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