Skip to main content

Historical Data

This guide covers handling historical data in Bookmap add-ons, including pre-subscription data, backfill, and the transition to real-time data.

Types of Historical Data​

TypeDescription
Pre-subscription dataCollected by Bookmap before the add-on was enabled
Backfill dataUp to 48 hours of data from Bookmap servers
Historical dataReplay data stored in Bookmap's .bmf files

HistoricalDataListener​

Implement HistoricalDataListener to handle pre-subscription market data. This allows your add-on to process data that was collected before it was enabled.

HistoricalModeListener​

Use HistoricalModeListener to get notified when pre-subscription data processing completes and real-time data begins.

Key Method​

void onRealtimeStart()

Called when the add-on transitions from processing historical data to receiving real-time data.

Example: VWAP with Historical Mode Detection​

@Layer1SimpleAttachable
@Layer1StrategyName("Market Data Listener")
@Layer1ApiVersion(Layer1ApiVersionValue.VERSION1)
public class MarketDataListener implements CustomModuleAdapter, TradeDataListener, HistoricalModeListener {

    private final Vwap buyers = new Vwap();
    private final Vwap sellers = new Vwap();
    private double minPriceIncrement;
    private Api api;

    @Override
    public void initialize(String alias, InstrumentInfo info, Api api, InitialState initialState) {
        this.api = api;
        minPriceIncrement = info.pips;
    }

    @Override
    public void onTrade(double price, int size, TradeInfo tradeInfo) {
        (tradeInfo.isBidAggressor ? buyers : sellers).onTrade(price, size);
    }

    @Override
    public void stop() {
        double vwapBuy = minPriceIncrement * buyers.priceSize / buyers.volume;
        double vwapSell = minPriceIncrement * sellers.priceSize / sellers.volume;
        double vwap = minPriceIncrement * (buyers.priceSize + sellers.priceSize) / (buyers.volume + sellers.volume);
        Log.info(String.format("VWAP Buy: %.2f, Sell: %.2f, Total: %.2f", vwapBuy, vwapSell, vwap));
    }

    @Override
    public void onRealtimeStart() {
        // Historical data processing complete, real-time data starting
        Log.info("Real-time data started. Unloading...");
        api.unload();
    }
}

Use Cases​

Calculate Metrics from Historical Data​

Use HistoricalModeListener to:

  1. Process all historical data
  2. Calculate metrics (VWAP, volume profile, etc.)
  3. Either continue with real-time or unload

Reset State at Real-time Start​

@Override
public void onRealtimeStart() {
    // Reset accumulators for real-time only tracking
    buyers.reset();
    sellers.reset();
    Log.info("Switched to real-time mode - accumulators reset");
}

Different Behavior for Historical vs Real-time​

private boolean isRealtime = false;

@Override
public void onRealtimeStart() {
    isRealtime = true;
}

@Override
public void onTrade(double price, int size, TradeInfo tradeInfo) {
    if (isRealtime) {
        // Only process real-time trades
        processRealtimeTrade(price, size, tradeInfo);
    } else {
        // Accumulate historical data differently
        accumulateHistoricalTrade(price, size, tradeInfo);
    }
}

See Also​