How to Query Market Scanner in the Web API

Articles From: Interactive Brokers
Website: Interactive Brokers

Quant

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, ref: 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.

The views and opinions expressed herein are those of the author and do not necessarily reflect the views of Interactive Brokers, its affiliates, or its employees.

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.

Disclosure: Security Futures

Security futures involve a high degree of risk and are not suitable for all investors. The amount you may lose may be greater than your initial investment. Before trading security futures, please read the Security Futures Risk Disclosure Statement. For a copy visit ibkr.com

Disclosure: Futures Trading

Futures are not suitable for all investors. The amount you may lose may be greater than your initial investment. Before trading futures, please read the CFTC Risk Disclosure. A copy and additional information are available at ibkr.com.