> This page is for TWS API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://ibkrcampus.com/docs/llms.txt.

# Market Scanner Subscription

## Introduction

Some scans in the TWS Advanced Market Scanner can be accessed via the TWS API through `EClient.reqScannerSubscription`. Results are delivered via `EWrapper.scannerData` and the `EWrapper.scannerDataEnd` marker will indicate when all results have been delivered. The returned results to `scannerData` simply consist of a list of contracts. There are no market data fields (bid, ask, last, volume, …) returned from the scanner, and so if these are desired they have to be requested separately with the `reqMktData` function. Since the scanner results do not include any market data fields, it is not necessary to have market data subscriptions to use the API scanner. However to use filters, market data subscriptions are generally required.

Since the `EClient.reqScannerSubscription` request keeps a subscription open you will keep receiving periodic updates until the request is cancelled via `EClient.cancelScannerSubscription`.

Scans are limited to a maximum result of 50 results per scan code, and only 10 API scans can be active at a time.

`scannerSubscriptionFilterOptions` has been added to the API to allow for generic filters. This field is entered as a list of TagValues which have a tag followed by its value, e.g. TagValue("usdMarketCapAbove", "10000") indicates a market cap above 10000 USD. Available filters can be found using the `EClient.reqScannerParameters` function.

**Important:** remember the TWS API is just an interface to the TWS. If you are having problems defining a scanner, always make sure you can create a similar scanner using the TWS' [Advanced Market Scanner](https://ibkrguides.com/tws/usersguidebook/mosaic/advancedscanner.htm).

The XML tree returned by `reqScannerParameters` will relay a tree containing a corresponding code to each `ScannerSubscription` field:

**instrument:** `<ScanParameterResponse> <InstrumentList> <Instrument> <type>`

**Location Code:** `<ScanParameterResponse> <LocationTree> <Location> <LocationTree> <Location> <locationCode>`

**Scan Code:** `<ScanParameterResponse> <ScanTypeList> <ScanType> <scanCode>`

**Subscription Options** should be an empty array of TagValues.

**Filter Options:** `<ScanParameterResponse> <FilterList> <RangeFilter> <AbstractField> <code>`

---

## Request Market Scanner Subscription

`EClient.reqScannerSubscription(reqId, subscription, scannerSubscriptionOptions, scannerSubscriptionFilterOptions)`

Starts a subscription to market scan results based on the provided parameters.

**`reqId`** `int`

Request identifier used for tracking data.

---

**`subscription`** `ScannerSubscription`

Object containing details on what values should be used to construct and sort the list.

---

**`scannerSubscriptionOptions`** `List`

Internal use only.

---

**`scannerSubscriptionFilterOptions`** `List`

List of values used to filter the results of the scanner subscription. May result in an empty scanner response from over-filtering.

---

\


#### Python

```python
self.reqScannerSubscription(7002, scannerSubscription, [], filterTagvalues)
```

#### Java

```java
client.reqScannerSubscription(7002, scannerSubscription, null, FilterTagValues);
```

#### C++

```cpp
m_pClient->reqScannerSubscription(7002, scannerSubscription, TagValueListSPtr(), filterTagValues);
```

#### C\#

```csharp
client.reqScannerSubscription(7002, scannerSubscription, null, filterTagValues);
```

#### VB.NET

```vbnet
client.reqScannerSubscription(7002, scannerSubscription, Nothing, filterTagValues)
```

---

## Receive Market Scanner Subscription

`EWrapper.scannerData(reqid, rank, contractDetails, distance, benchmark, projection, legStr)`

Provides the data resulting from the market scanner request.

**`reqid`** `int`

Request identifier used to track data.

---

**`rank`** `int`

The ranking position of the contract in the scanner sort.

---

**`contractDetails`** `ContractDetails`

Contract object of the resulting object.

---

**`distance`** `string`

Internal use only.

---

**`benchmark`** `string`

Internal use only.

---

**`projection`** `string`

Internal use only.

---

**`legStr`** `string`

Describes the combo legs when the scanner is returning EFP.

---

\


#### Python

```python
def scannerData(self, reqId: int, rank: int, contractDetails: ContractDetails, distance: str, benchmark: str, projection: str, legsStr: str):
	print("ScannerData. ReqId:", reqId, ScanData(contractDetails.contract, rank, distance, benchmark, projection, legsStr))
```

#### Java

```java
@Override
public void scannerData(int reqId, int rank, ContractDetails contractDetails, String distance, String benchmark, String projection, String legsStr) {
	System.out.println("ScannerData: " + EWrapperMsgGenerator.scannerData(reqId, rank, contractDetails, distance, benchmark, projection, legsStr));
}
```

#### C++

```cpp
void TestCppClient::scannerData(int reqId, int rank, const ContractDetails& contractDetails, const std::string& distance, const std::string& benchmark, const std::string& projection, const std::string& legsStr) {
    printf( "ScannerData. %d - Rank: %d, Symbol: %s, SecType: %s, Currency: %s, Distance: %s, Benchmark: %s, Projection: %s, Legs String: %s\n", reqId, rank, contractDetails.contract.symbol.c_str(), contractDetails.contract.secType.c_str(), contractDetails.contract.currency.c_str(), distance.c_str(), benchmark.c_str(), projection.c_str(), legsStr.c_str());
}
```

#### C\#

```csharp
public virtual void scannerData(int reqId, int rank, ContractDetails contractDetails, string distance, string benchmark, string projection, string legsStr)
{
	Console.WriteLine("ScannerData. "+reqId+" - Rank: "+rank+", Symbol: "+contractDetails.Contract.Symbol+", SecType: "+contractDetails.Contract.SecType+", Currency: "+contractDetails.Contract.Currency +", Distance: "+distance+", Benchmark: "+benchmark+", Projection: "+projection+", Legs String: "+legsStr);
}
```

#### VB.NET

```vbnet
Public Sub scannerData(reqId As Integer, rank As Integer, contractDetails As IBApi.ContractDetails, distance As String, benchmark As String, projection As String, legsStr As String) Implements IBApi.EWrapper.scannerData
	Console.WriteLine("ScannerData. " & reqId & " - Rank: " & rank & ", : " & contractDetails.Contract.Symbol & ", SecType: " &contractDetails.Contract.SecType & ", Currency: " & contractDetails.Contract.Currency & ", Distance: " & distance & ", Benchmark: " & benchmark & ", Projection: " & projection & ", Legs String: " & legsStr)
End Sub
```

---

## Cancel Market Scanner Subscription

`EClient.cancelScannerSubscription(tickerId)`

Cancels the specified scanner subscription using the tickerId.

**`tickerId`** `int`

Request identifier used to track data.

---

\


#### Python

```python
self.cancelScannerSubscription(7003)
```

#### Java

```java
client.cancelScannerSubscription(7003);
```

#### C++

```cpp
m_pClient->cancelScannerSubscription(7002);
```

#### C\#

```csharp
client.cancelScannerSubscription(7003);
```

#### VB.NET

```vbnet
client.cancelScannerSubscription(7003)
```