Instruments


GET instruments

Description

Get the full list of instrument definitions matching the supplied filter criteria. Unsorted, but order is consistent.

Resource URL

https://api.optionscity.com/instruments
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object Instrument Set
Response Type Standard

Parameters

NameDescriptionRequired?Type
product_group_id The ID for the instruments' product group. No Number
product_group_symbol The symbol for the instruments' product group. No String
parent_symbol The parent symbol for the instruments' product. No String
exchange The exchange for the instruments' product group. No String
instrument_type The instrument type (future, option, spread) for the instruments. No String
security_id The exchange assigned unique identifier. No String
min_expiration The minimum expiration date for the instruments. Defaults to a filter with expirations greater than or equal to 'today'. No DateTime*
max_expiration The maximum expiration date for the instruments. No DateTime*
min_display_expiration The minimum display expiration date for the instruments. Defaults to a filter with expirations greater than or equal to 'today'. No DateTime*
max_display_expiration The maximum display expiration date for the instruments. No DateTime*
min_strike The minimum strike price for the instruments. No Number
max_strike The maximum strike price for the instruments. No Number
symbol Return only instruments assigned the specified symbol. (Symbols can be re-used by the exchange, but City API keeps a complete history of instruments.) No String
spread_code Return only spreads with the given code. No String
exercise_procedure Return only instruments matching exercise procedure ('American' or 'European'). No String
search Return only instruments matching by symbol or name. No String
min_delisted_after The minimum delisted after date for the instruments. This should be provided if you wish to filter out instruments that have been delisted but not necessarily expired. This is necessary because some spreads on some exchanges are known to be delisted before their expiration date. No DateTime*
page 1-indexed page to retrieve. Default is 1. No Number
per_page Number of entries returned per page. Default is 10000. No Number

Example Request

GET https://api.optionscity.com/instruments?product_group_symbol=ES

Example Response

{
  "instruments" : [ {
    "id" : 1,
    "symbol" : "ESH4 C1770",
    "name" : "ES MAR 2014 1770 CALL",
    "product_id" : 1,
    "instrument_type" : "Option",
    "security_id" : "ySqZU5k9jS9cqAs8QHa4",
    "expiration_date" : "2014-03-20T08:30:00.000-06:00",
    "display_expiration_date" : "2014-03-01",
    "option_type" : "Call",
    "strike" : 177000,
    "underlying_id" : 2
  } ],
  "products" : [ {
    "id" : 1,
    "group_id" : 2,
    "parent_symbol" : "ES",
    "clearing_symbol" : "ES",
    "instrument_type" : "Option",
    "is_weekly" : false,
    "settlement_type" : "Cash",
    "exercise_procedure" : "American",
    "expiration_type" : "S",
    "display_factor" : 0.01,
    "tick_size" : 25,
    "tick_value" : 12.5,
    "tick_boundaries" : [ ],
    "tick_sizes" : [ ],
    "base_factor" : 1,
    "session_start_times" : [ 1020, 2460, 3900, 5340, 6780 ],
    "session_end_times" : [ 2415, 3855, 5295, 6735, 8175 ]
  } ],
  "product_groups" : [ {
    "id" : 1,
    "symbol" : "ES",
    "category" : "Equities",
    "sub_category" : "US Indexes",
    "name" : "E-mini S&P 500 Options",
    "time_zone" : "America/Chicago",
    "exchange" : "CME",
    "market_data_group" : "CME",
    "mic" : "XCME",
    "currency" : "USD"
  } ]
}

GET instruments/:id

Description

Get the full definition for an instrument with a given ID. This includes properties like a human-readable name, instrument type (future, option, spread), expiration date, etc.

Resource URL

https://api.optionscity.com/instruments/:id
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object Instrument
Response Type Standard

Parameters

NameDescriptionRequired?Type
id The unique City API identifier for the instrument. Yes Number
embed_product Whether product and product group details should be embedded in each instrument definition. No Boolean

Example Request

GET https://api.optionscity.com/instruments/1

Example Response

[ {
  "id" : 1,
  "symbol" : "ESH4 C1770",
  "name" : "ES MAR 2014 1770 CALL",
  "product_id" : 1,
  "instrument_type" : "Option",
  "security_id" : "ySqZU5k9jS9cqAs8QHa4",
  "expiration_date" : "2014-03-20T08:30:00.000-06:00",
  "display_expiration_date" : "2014-03-01",
  "option_type" : "Call",
  "strike" : 177000,
  "underlying_id" : 2
} ]

POST lookupspread

Description

This API allows lookup of the full definition for a spread by its legs. If the spread is listed, the full definition will be returned. You may optionally request that the spread be listed by the exchange in the case where it is not listed already. Note that request parameters should be encoded as JSON and included in the HTTP body.

Resource URL

https://api.optionscity.com/lookupspread
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object Look Up Spread Response
Response Type Standard

Parameters

NameDescriptionRequired?Type
legs An array of leg definitions as defined in the spread leg object above. Yes ObjectArray
create_if_missing Whether or not to request that the spread be listed by the exchange. Only applicable if the spread is not already listed. Default is 'false'. No Boolean
acct_id The account ID to use for any exchange requests. Only required if a request to list is submitted. No Number

Example Request

POST https://api.optionscity.com/lookupspread
{
  "legs" : [ {
    "leg_type" : "OutrightLeg",
    "instrument_id" : 131489,
    "side" : "Sell",
    "quantity" : 1
  }, {
    "leg_type" : "OutrightLeg",
    "instrument_id" : 131491,
    "side" : "Buy",
    "quantity" : 1
  } ],
  "create_if_missing" : true,
  "acct_id" : 2
}

Example Response

{
  "response_type" : "FoundSpread",
  "spread" : {
    "id" : 1,
    "symbol" : "EMDU4-EMDM5",
    "name" : "EMD-CECLSPRD Sep14 F :-1 | Jun15 F :1",
    "product_id" : 1,
    "instrument_type" : "SpreadInst",
    "security_id" : "ySqZU5k9jS9cqAs8QHa4",
    "expiration_date" : "2014-09-19T13:30:00Z",
    "display_expiration_date" : "2014-09-01",
    "legs" : [ {
      "leg_type" : "OutrightLeg",
      "instrument_id" : 131489,
      "side" : "Sell",
      "symbol" : "EMDU4",
      "quantity" : 1
    }, {
      "leg_type" : "OutrightLeg",
      "instrument_id" : 131491,
      "side" : "Buy",
      "symbol" : "EMDM5",
      "quantity" : 1
    } ],
    "spread_code" : "CECLSPRD",
    "spread_description" : "CECLSPRD"
  }
}

Instrument Object

Description

Some financial instrument represented by a unique symbol on an exchange or set of exchanges (i.e. future, option or spread).

Fields

Field Type Optional Subtypes Description
id Number No All Identifier assigned by the City API.
symbol String No All The symbol supplied by the source exchange.
product_id Number No All Identifies the product to which the instrument belongs.
instrument_type String No All Identifies the type of instrument. One of 'Option', 'Future' or 'Spread'.
security_id String No All Exchange assigned unique identifier.
name String No All Nicely formatted name suitable for display.
expiration_date DateTime* No Future Option The expiration date and time for derivative contracts.
display_expiration_date DateTime* No Future Option Local date whose month represents how expirations are commonly quoted, which may or may not match the expiration date month.
option_type String No Option 'Call' or 'Put'
strike Number No Option Raw, exchange-supplied trike price of an option.
underlying_id Number No Option An option's underlying future ID.
trading_status String Yes All 'Open', 'Rotation', 'Closed', 'PreOpen', 'PreClosed', 'Halted' or 'Disabled'.
legs ObjectArray No Spread The spread leg definitions for a spread.
spread_code String No Spread Short, unique code used to classify spread.
spread_description String No Spread Brief spread type desciption (e.g. 'Butterfly' or 'Iron Condor').

JSON Sample

[ {
  "id" : 1,
  "symbol" : "ESH4 C1770",
  "name" : "ES MAR 2014 1770 CALL",
  "product_id" : 1,
  "instrument_type" : "Option",
  "security_id" : "ySqZU5k9jS9cqAs8QHa4",
  "expiration_date" : "2014-03-20T08:30:00.000-06:00",
  "display_expiration_date" : "2014-03-01",
  "option_type" : "Call",
  "strike" : 177000,
  "underlying_id" : 2
} ]

Spread Leg Object

Description

Represents a single leg of a spread, including covered spread legs.

Fields

Field Type Optional Subtypes Description
leg_type String No All Indicates the type of spread leg, either 'OutrightLeg' or 'VolatilityLeg'.
instrument_id Number No All Identifies the leg's instrument by City API ID. The instrument must be a future if the leg is a cover.
quantity Number No OutrightLeg The leg quantity for outright legs.
side String No All The direction of the leg.
delta Number No VolatilityLeg The (rounded) number of futures contracts traded per option contract for a covered spread.
price Number No VolatilityLeg The future price of the cover.

JSON Sample

{
  "leg_type" : "OutrightLeg",
  "instrument_id" : 1,
  "side" : "Buy",
  "quantity" : 1
}

Instrument Set Object

Description

A set of instruments returned as the response to a query. All products and product groups referenced are included in separate arrays.

Fields

Field Type Optional Description
instruments ObjectArray No Array of all instrument definitions.
products ObjectArray No Array of all product definitions referenced by instruments.
product_groups ObjectArray No Array of all product group definitions referenced by products.

JSON Sample

{
  "instruments" : [ {
    "id" : 1,
    "symbol" : "ESH4 C1770",
    "name" : "ES MAR 2014 1770 CALL",
    "product_id" : 1,
    "instrument_type" : "Option",
    "security_id" : "ySqZU5k9jS9cqAs8QHa4",
    "expiration_date" : "2014-03-20T08:30:00.000-06:00",
    "display_expiration_date" : "2014-03-01",
    "option_type" : "Call",
    "strike" : 177000,
    "underlying_id" : 2
  } ],
  "products" : [ {
    "id" : 1,
    "group_id" : 2,
    "parent_symbol" : "ES",
    "clearing_symbol" : "ES",
    "instrument_type" : "Option",
    "is_weekly" : false,
    "settlement_type" : "Cash",
    "exercise_procedure" : "American",
    "expiration_type" : "S",
    "display_factor" : 0.01,
    "tick_size" : 25,
    "tick_value" : 12.5,
    "tick_boundaries" : [ ],
    "tick_sizes" : [ ],
    "base_factor" : 1,
    "session_start_times" : [ 1020, 2460, 3900, 5340, 6780 ],
    "session_end_times" : [ 2415, 3855, 5295, 6735, 8175 ]
  } ],
  "product_groups" : [ {
    "id" : 1,
    "symbol" : "ES",
    "category" : "Equities",
    "sub_category" : "US Indexes",
    "name" : "E-mini S&P 500 Options",
    "time_zone" : "America/Chicago",
    "exchange" : "CME",
    "market_data_group" : "CME",
    "mic" : "XCME",
    "currency" : "USD"
  } ]
}

Look Up Spread Response Object

Description

The response to a look up spread request.

Fields

Field Type Optional Subtypes Description
response_type String No All One of 'FoundSpread', 'DidNotFindSpread', 'RequestedCreation', or 'CannotCreateSpread'.
spread Object Yes FoundSpread RequestedCreation The full spread definition. May not be provided if spread creation failed at the exchange.
error_msg String No CannotCreateSpread Explanation as to why the spread cannot be created.

JSON Sample

{
  "response_type" : "FoundSpread",
  "spread" : {
    "id" : 1,
    "symbol" : "EMDU4-EMDM5",
    "name" : "EMD-CECLSPRD Sep14 F :-1 | Jun15 F :1",
    "product_id" : 1,
    "instrument_type" : "SpreadInst",
    "security_id" : "ySqZU5k9jS9cqAs8QHa4",
    "expiration_date" : "2014-09-19T13:30:00Z",
    "display_expiration_date" : "2014-09-01",
    "legs" : [ {
      "leg_type" : "OutrightLeg",
      "instrument_id" : 131489,
      "side" : "Sell",
      "symbol" : "EMDU4",
      "quantity" : 1
    }, {
      "leg_type" : "OutrightLeg",
      "instrument_id" : 131491,
      "side" : "Buy",
      "symbol" : "EMDM5",
      "quantity" : 1
    } ],
    "spread_code" : "CECLSPRD",
    "spread_description" : "CECLSPRD"
  }
}

* Date and time elements are ISO-8601 string representations