This website uses cookies to collect usage information in order to offer a better browsing experience. By browsing this site or by clicking on the "ACCEPT COOKIES" button you accept our Cookie Policy.

Duration: 5:00

Level: Intermediate

How to Query Market Scanner in the Web API

The market scanner allows you to quickly scan relevant markets and return the top contracts based on a defined set of instrument, parameter, location, and filtering criteria. The endpoint /iserver/scanner/params can be used to determine the available values.

Please be sure to authenticate first in order to resolve the below URLs.
For authentication details, visit https://interactivebrokers.github.io/cpwebapi/index.html#login

GET
https://localhost:5000/v1/api/iserver/scanner/params
Response: 

{ 

scan_type_list     Array of objects
                   The available scanner parameters 
Array () [
{


display_name    string
                The scanner parameter name  

code            string
                The code for scanner parameter  

instruments     string 
                The list of available instruments that are supported

   ]
},

instrument_list  Array of objects
                 The available types of instruments

Array () [  
{

display_name   string                                         
               The instrument name

type           string
               The asset class 

filters        string
               The available data points that can be used to filter instruments  
]

},

filter_list  Array of objects 
             Defines the filters returned in instrument_list 
Array () [
{

group       string 
            The group of filter 

display_name       string 
                   The filter name 

code      string 
          The code for filter name 

type      string 
          The category for the filter 

location_tree Array of objects
                The available locations 
Array () [
{

display_name    string 
                The name for the region and asset class

type            string 
                Asset Class

locations       Array of objects 
                List of available locations

Array () [
{

display_name     string 
                 Name of the location

type             string 
                Formatted asset_Class.Exchange

  }, ] } ] 

Once you know the available params, send the endpoint /iserver/scanner/run to run a market scanner.
POST
https://localhost:5000/v1/api/iserver/scanner/run

 

Request Body:

{

instrument      string
The asset class, this would be the type returned in instrument_list

type                 string
The scanner parameter, this would be the code returned in scan_type_list

filter                Array of objects
List of filters
Array () [
{

code       string
The filter value, this would be the filters from instrument_list

value      number
The value of the filter

},
]

location          string
The region and asset class formatted

size                  number
The number of contracts returned. A max of 50 is returned.

]

Response:

contracts                 Array of objects
List of contracts returned

Array () [
{

server_id:                                  number
Position Number max of 50 returned.

column_name                         string
Market Data column that should be included with scanner list.

symbol                                           string
Contract Symbol

conidex                                      string
Format either conid@exchange or conid

con_id                                            string
Contract identifier

available_chart_periods       string
The chart period available for contract

company_name                      string
Company Name of the contract

contract_description_1           string
IBKR contract symbol

listing_exchange                        string
Listing exchange

sec_type                                       string
Asset Class
},
]

scan_data_column_name     string
Name of market data column displayed for scanner.

]

Please be sure to authenticate first in order to resolve the below URLs.
For authentication details, visit https://interactivebrokers.github.io/cpwebapi/index.html#login

Example:

Using the endpoint /iserver/scanner/params to see what scanner parameters are available.

Request:

POST
https://localhost:5000/v1/api/iserver/scanner/params
Response: 

{ 

  "scan_type_list": [ 

    { 

      "display_name": "Top % Gainers", 

      "code": "TOP_PERC_GAIN", 

      "instruments": [ 

        "STK", 

        "FUT.US", 

        "IND.US", 

        "STOCK.NA", 

        "STOCK.EU", 

        "FUT.EU", 

        "IND.EU", 

        "SSF.EU", 

        "STOCK.HK", 

        "FUT.HK", 

        "SSF.HK" 

      ] 

    }, 

    { 

      "display_name": "Most Active", 

      "code": "MOST_ACTIVE", 

      "instruments": [ 

        "STK", 

        "FUT.US", 

        "SLB.US", 

        "STOCK.NA", 

        "STOCK.EU", 

        "FUT.EU", 

        "SSF.EU", 

        "STOCK.HK", 

        "FUT.HK", 

        "SSF.HK" 

      ] 

    }, 

… 

  ], 

  "instrument_list": [ 

    { 

      "display_name": "US Stocks", 

      "type": "STK", 

      "filters": [ 

        "afterHoursChangePerc", 

        "avgOptVolume", 

        "avgPriceTarget", 

        "avgRating", 

        "avgAnalystTarget2PriceRatio", 

        "avgVolume", 

        "avgUsdVolume", 

        "changeOpenPerc", 

        "changePerc", 

        "curEMA20", 

        "curEMA50", 

        "curEMA100", 

… 

  ], 

  "filter_list": [ 

    { 

      "group": "afterHoursChangePercAbove", 

      "display_name": "After-Hours Change (%) Above", 

      "code": "afterHoursChangePercAbove", 

      "type": "non-range" 

    }, 

    { 

      "group": "afterHoursChangePercBelow", 

      "display_name": "After-Hours Change (%) Below", 

      "code": "afterHoursChangePercBelow", 

      "type": "non-range" 

    }, 

    { 

      "group": "avgOptVolumeAbove", 

      "display_name": "Average Opt. Volume Above", 

      "code": "avgOptVolumeAbove", 

      "type": "non-range" 

    }, 

… 

  ], 

  "location_tree": [ 

    { 

      "display_name": "US Stocks", 

      "type": "STK", 

      "locations": [ 

        { 

          "display_name": "Listed/NASDAQ", 

          "type": "STK.US.MAJOR", 

          "locations": [] 

        } 

      ] 

    }, 

    { 

      "display_name": "US Futures", 

      "type": "FUT.US", 

      "locations": [ 

        { 

          "display_name": "GLOBEX", 

          "type": "FUT.GLOBEX" 

        }, 

… 

        } 

      ] 

    } 

  ] 

} 

Sending the endpoint /iserver/scanner/run to query a market scanner.

Request:

POST
https://localhost:5000/v1/api/iserver/scanner/run

Request Body: 
{ 

  "instrument": "STK", 

  "type": "MOST_ACTIVE_USD", 

  "filter": [ 

    { 

      "code": "priceAbove", 

      "value": 5 

    }, 

    { 

      "code": "volumeAbove", 

      "value": 500 

    }, 

  ], 

  "location": "STK.US.MAJOR", 

  "size": "25" 

} 

 
 
Response: 
{ 

  "contracts": [ 

    { 

      "server_id": "0", 

      "column_name": "Volume", 

      "symbol": "PTPI", 

      "conidex": "458378565", 

      "con_id": 458378565, 

      "available_chart_periods": "#R|1", 

      "company_name": "PETROS PHARMACEUTICALS INC", 

      "contract_description_1": "PTPI", 

      "listing_exchange": "NASDAQ.SCM", 

      "sec_type": "STK" 

    }, 

    { 

      "server_id": "1", 

      "symbol": "PTN", 

      "conidex": "79464103", 

      "con_id": 79464103, 

      "available_chart_periods": "#R|1", 

      "company_name": "PALATIN TECHNOLOGIES INC", 

      "contract_description_1": "PTN", 

      "listing_exchange": "AMEX", 

      "sec_type": "STK" 

    }, 

    { 

      "server_id": "2", 

      "symbol": "SQQQ", 

      "conidex": "440504393", 

      "con_id": 440504393, 

      "available_chart_periods": "#R|1", 

      "company_name": "PROSHARES ULTRAPRO SHORT QQQ", 

      "contract_description_1": "SQQQ", 

      "listing_exchange": "NASDAQ.NMS", 

      "sec_type": "STK" 

    }, 

… 

    } 

  ], 

  "scan_data_column_name": "Volume" 

} 

If you have any further questions or issues creating a market scanner, please reach out to the API Group,

https://www.interactivebrokers.com/en/index.php?f=47047

Visit the IBKR API Center for Downloads, Resources, and Technical Details:
https://www.interactivebrokers.com/en/trading/ib-api.php


Disclosure: Interactive Brokers

The analysis in this material is provided for information only and is not and should not be construed as an offer to sell or the solicitation of an offer to buy any security. To the extent that this material discusses general market activity, industry or sector trends or other broad-based economic or political conditions, it should not be construed as research or investment advice. To the extent that it includes references to specific securities, commodities, currencies, or other instruments, those references do not constitute a recommendation by IBKR to buy, sell or hold such investments. This material does not and is not intended to take into account the particular financial conditions, investment objectives or requirements of individual customers. Before acting on this material, you should consider whether it is suitable for your particular circumstances and, as necessary, seek professional advice.

Supporting documentation for any claims and statistical information will be provided upon request.

Any stock, options or futures symbols displayed are for illustrative purposes only and are not intended to portray recommendations.

Disclosure: API Examples Discussed

Throughout the lesson, please keep in mind that the examples discussed are purely for technical demonstration purposes, and do not constitute trading advice. Also, it is important to remember that placing trades in a paper account is recommended before any live trading.

trading top
Translate »