Bookmap API highlights

Custom indicators, trading strategies, data export and recording and more...
Posts: 113
Joined: Mon Jun 11, 2018 12:40 pm
Has thanked: 15 times
Been thanked: 35 times

Bookmap API highlights

Post by Serg » Mon Oct 22, 2018 11:55 am

Related and recommended material: Key features
  • Receive trades as Times & Sales with ability to "reconstruct" the size of the aggressive order
  • Receive full market depth as Market-by-price (MBP) or Market-by-order (MBO)
  • Unique: Receive recent history of market depth data
  • Draw indicators on chart or indicators panel with unlimited resolution
  • Implement automatic trading strategies
  • Create custom settings panel
  • Implement custom windows and widgets (detached from Bookmap chart)
  • Simple, fast, and transparent
  • Free access to API for all Bookmap users
  • Use any Java supporting IDE for development
  • Offer your custom module on marketplace (in progress) for other traders
  • It's recommended to keep Bookmap updated.
  • Your Bookmap license should be enabled for API. Until the self-enabling mechanism is ready, please send a request to and include either your license key or Bookmap registration email.
US stocks data
Bookmap is required to block the API access for dxFeed US stocks data. It's a requirement of dxFeed and US stock exchanges because API gives access to "Non-display data". For further information please contact dxFeed directly via

The new Bookmap API (previously called L1/L2) is free for all Bookmap customers even for those who prefer the free Bookmap package. It allows seamless development of custom modules such as indicators, automated trading strategies, data export and recording, and more. These custom modules can be used with any connectivity without any change. Note: For Bookmap Connect or Quant solutions please visit the corresponding forum.
API quick intro.png
API quick intro.png (245.92 KiB) Viewed 43421 times
The API was developed by Bookmap team based on its experience with dozens of API's of trading platforms, data vendors, and exchanges. The resulting API combines unprecedented levels of both simplicity and transparency. This gives users an ability to develop within minutes or hours custom modules that utilize truly unfiltered and unaggregated market data (including full market depth) and may use complete trading functionality. The main advantages of Bookmap API are:
  • Simplicity (see examples below).
  • Transparency. For instance, custom modules that require market depth data may receive it from the beginning of the session and continue in real-time, i.e. not only from the moment of custom module activation. This is a unique feature, not available in other trading platforms API such as NT8.
  • Performance. Bookmap can support hundreds of indicators and together they may add many millions of data points on a typical daily chart without noticeably affecting Bookmap performance.
The example package contains different types of custom modules.

Weighted Midprice indicator
This indicator provides a basic demonstration of Bookmap API usage by drawing a Size-Weighted mid-price on the main Bookmap chart. It subscribes to market depth data and manages itself the Order book. Whenever a trade occurs, it calculates the size-weighted mid-price and updates the indicator line, but it doesn't use the trade data itself. Alternatively, it could add new points every custom time period such as 100 milliseconds by implementing IntervalListener interface. Also, since it relies only on best bid/ask levels, it could implement BboListener interface instead of DepthDataListener. Here is this simplest indicator in action:

ESZ8.CME@RITHMIC_screenshot_20181002_161512_906-000.png (134.58 KiB) Viewed 43795 times
And here is its entire source code. Note that instead of this particular functionality, a custom module could similarly easy record the data in a custom format or export it to Excel in real-time, perform some other computations, or perhaps draw more than one indicator line.

Code: Select all

public class WeightedMidprice implements CustomModule, TradeDataListener, DepthDataListener {

    Indicator indicator;
    OrderBook orderBook = new OrderBook();

    public void initialize(String alias, InstrumentInfo info, Api api) {
        indicator = api.registerIndicator("Weighted Midprice", GraphType.PRIMARY, Color.WHITE);

    public void onDepth(boolean isBid, int price, int size) {
        orderBook.onDepth(isBid, price, size);

    public void onTrade(double price, int size, TradeInfo tradeInfo) {
        double bestBid = (double) orderBook.bids.firstKey();
        int bestBidSize = orderBook.bids.firstEntry().getValue();
        double bestAsk = (double) orderBook.asks.firstKey();
        int bestAskSize = orderBook.asks.firstEntry().getValue();
        double weightedMidprice = (bestBid * bestAskSize + bestAsk * bestBidSize) / (bestBidSize + bestAskSize);
As you may have noticed, this custom module uses an object of a class called OrderBook. It is accessible in the API as a helper class, but as you can see below it would take just a minute for a junior Java developer to implement such class himself. This simple Order book implementation can manage over 100 thousands of price levels on each side (e.g. full market depth of GOOG stock) and process over 15 million data updates in less than a second. Here is its entire source code:

Code: Select all

public class OrderBookBase {

    public TreeMap<Integer, Integer> bids = new TreeMap<>(Collections.reverseOrder());
    public TreeMap<Integer, Integer> asks = new TreeMap<>();

    public int onDepth(boolean isBid, int price, int size) {
        Map<Integer, Integer> book = isBid ? bids : asks;
        Integer sizePrevious = (size == 0) ? book.remove(price) : book.put(price, size);
        return (sizePrevious == null) ? 0 : sizePrevious;
Liquidity Tracker indicator
Displays the total size at 10 bid price levels and 10 ask price levels. It demonstrates how to receive periodic updates via onBar() function which provides actual for the Bar's close Order Book and a Bar object. In addition to regular OHLCV, the Bar objects contains separate Buy and Sell volume and VWAP, and the total VWAP. In this example our indicator subscribes to bars period of 100 milliseconds and recalculates the Bid/Ask liquidity on every update. Here is the resulting indicator as two lines displayed on the indicators panel.
CLX8.NYMEX@RITHMIC_screenshot_20181002_154336_434-004.png (413.31 KiB) Viewed 43795 times
And here is the entire source code of this Liquidity Tracker indicator. In this case no additional code was necessary.

Code: Select all

public class LiquidityTracker implements CustomModule, BarDataListener {

    Indicator indicatorBid;
    Indicator indicatorAsk;
    int depth = 10; // number of price levels
    public void initialize(String alias, InstrumentInfo info, Api api) {
        indicatorBid = api.registerIndicator("Liquidity Bid", GraphType.BOTTOM, Color.GREEN);
        indicatorAsk = api.registerIndicator("Liquidity Ask", GraphType.BOTTOM, Color.RED);
    public long getBarInterval() {
        return Intervals.INTERVAL_100_MILLISECONDS;
    public void onBar(OrderBook orderBook, Bar bar) {
        int bidSizeDepth = getBookSizeSum(orderBook, true);
        int askSizeDepth = getBookSizeSum(orderBook, false);

    private int getBookSizeSum(OrderBook orderBook, boolean isBid) {
        TreeMap<Integer, Long> levels = isBid ? orderBook.getBidMap() : orderBook.getAskMap();
        Integer price = levels.firstKey();
        int size = 0;
        int n = Math.min(depth, levels.size());
        for (int i = 0; i < n; i++) {
            Long q = levels.get(price);
            if (q != null) {
                size += q;
            price += isBid ? -1 : 1;
        return size;
Custom settings panel
API modules can create entirely custom settings panel. It may include any control and display components including an ability to launch another Java application from it. Here is an example custom settings panel from ATR Trailing Stop indicator.

API Custom Settings.png
API Custom Settings.png (499.94 KiB) Viewed 43795 times
Its code is published in the example project. The API also provides an interface for saving the settings of custom modules and getting them when the module is launched again:

Code: Select all

    public static class Settings {
    	// various settings of the custom module

    Settings settings;
    Api api;

    public void initialize(String alias, InstrumentInfo info, Api api, InitialState initialState) {
        this.api = api;
        this.settings = api.getSettings(Settings.class);

    public void stop() {
        api.setSettings(settings); // save settings before exit

In order to try it yourself visit How to import custom API modules into Bookmap