Candle Scanner API

Overview

Candle scanner apis are part of dhelm-candlescanner, version 1.0.0 package.
This apis can be used as a one stop entry point to automatically identify candle pattern formed by a particular OHLC data over a period of time, provided that sufficient and proper input are provided.

OHLC stands for <Open,High,Low,Close>.

Now, if you are aware of stock market terminologies, then you know that, an individual candle stick can be categorized into some basic candle forms. Again a basic candle be long or short depending on certain parameters.

There are also some well accepted patterns formed by one or more candle sticks. The history and arts behind those patterns are beyond the scope of this article. You can found lots of resources around about them.

The goal behind this dhelm-candlescanner package is to ease the identification of those candle stick patterns, by idenfying them using computer program.

Input Formatting

In the course of identifying the candle patterns automatically, there are four main apis:

1. public CandleTypeBasic getBasicCandleType(...)
2. public CandlePatternSingleLine getSingleLinePattern(...)
3. public  CandlePatternDoubleLine getDoubleLinePattern(...)
4. public  CandlePatternDoubleLine getMultiLinePattern(...)

To identify the candle patterns you need to provide these methods some parameters:

  List<Double> open : List of opening prices.
  List<Double> high : list of high prices.
  List<Double> low  : List of low prices.
  List<Double> close: list of closing prices.

The above four lists needs to be formatted in certain manner.
– All the four lists must be of same size.
– A particular index in all the four list represents the OHLC data for a particular time instance.
e.g the set {open.get(0),high.get(0),low.get(0),close.get(0)} represents the latest OHLC data.

Next question is how much OHLC data should be provided? The answer lies in the following parameter:
– Map scanParams
This HashMap must be formatted in a particular way. It should strictly contain the following pairs:
“body_reference_number” : Must be an integer > 0. For certain patterns the body of a candle needs to be larger than the bodies of certain number of previous candles. Now obviously the number of previous candles to take into account is a user defined phenomenon.
“length_reference_number” : Must be an integer > 0. For a particular candle to be long or short, it must be longer than the length of certain number of previous candles. Again the number of previous candles to take into account is a user defined phenomenon.
“long_short_reference_percentage” : Must be a double > 0. It is the percentage by which if a candle is longer than the length of certain previous candles(as specified by the ‘length_reference_number’), it will be treated as long candle, otherwise short.
“previous_trend_reference_number” : Must be an integer > 0. It is the number of previous candles to take into account prior to the pattern, to identify the previous trend.
“lower_shadow_reference_percentage” : Must be a double > 0. For certain patterns(e.g Bearish belthold) to be valid, the lower shadow must be only a certain prespecified percentage of the actual body of the candle.
“upper_shadow_reference_percentage” : Must be a double > 0. For certain patterns(e.g Bullish belthold) to be valid, the upper shadow must be only a certain prespecified percentage of the actual body of the candle.

An example for the Map scanParams from the test class:

Map<String,Object> scanParams=new HashMap<String, Object>();
scanParams.put("body_reference_number","5");
scanParams.put("length_reference_number","10");
scanParams.put("long_short_reference_percentage","70");
scanParams.put("previous_trend_reference_number","25");
scanParams.put("lower_shadow_reference_percentage","25");
scanParams.put("upper_shadow_reference_percentage","25");

[ NB: The values in the Object field form the scanParams Map is only for testing purpose. Users are required to set their own values according to their need.]

Now there is something to discuss about the length of OHLC data.
The length of the List variables open,high,low and close must be greater than[value of(“previous_trend_reference_number”)+max(value of(“body_reference_number”),value of(“length_reference_number”))+1]

For ordering of the parameters see the apis usage.

The basic candle pattern identification api

/**
*@return Returns the basic candle stick type if something is generated.
*@param open : list of opening prices where the last item is the latest data
*@param high : list of high prices where the last item is the latest data
*@param low : list of low prices where the last item is the latest data
*@param close : list of closing prices where the last item is the latest data
*@param scanParams contains body_reference_number, an integer greater than 0,
*length_reference_number, an integer greater than 0,long_short_reference_percentage, a double value greater than 0
*previous_trend_reference_number, an integer value greater than 0,lower_shadow_reference_percentage,  a double value greater than 0
*and upper_shadow_reference_percentage, a double value greater than 0.
*@throws DataException if sufficient data not available. 
*/
public  CandleTypeBasic getBasicCandleType(List<Double> open,List<Double> high,List<Double>low,List<Double>close,Map<String,Object> scanParams)throws DataException{
....}

If you notice the return type of the above method, you can see that return type is CandleTypeBasic, which is a set of enum constatnts.
If valid input is provided to this api, you will get the enum constant corresponding to the formed basic candle stick type from the following list:

{
  /**
   * Long White Candle
   */
  LONG_WHITE_CANDLE,
  /**
   * Short White Candle
   */
  SHORT_WHITE_CANDLE,
  /**
   * White Candle
   */
  WHITE_CANDLE,
  /**
   * White Marubozu Candle
   */
  WHITE_MARUBOZU,
  /**
   * Closing White Marubozu Candle
   */
  CLOSING_WHITE_MARUBOZU,
  /**
   * Opening White Marubozu Candle
   */
  OPENING_WHITE_MARUBOZU,
  /**
   * White Spinning Top
   */
  WHITE_SPINNING_TOP,
  /**
   * Long Black Candle
   */
  LONG_BLACK_CANDLE,
  /**
   * Short Black Candle
   */
  SHORT_BLACK_CANDLE,
  /**
   * Black Candle
   */
  BLACK_CANDLE,
  /**
   * Black Marubozu Candle 
   */
  BLACK_MARUBOZU,
  /**
   * Closing Black Marubozu Candle
   */   
  CLOSING_BLACK_MARUBOZU,
  /**
   * Opening Black Marubozu Candle
   */
  OPENING_BLACK_MARUBOZU,
  /**
   * Black Spinning Top Candle
   */
  BLACK_SPINNING_TOP,
  /**
   * Doji Candle
   */
  DOJI,
  /**
   * Long Legged Doji Candle
   */
  LONG_LEGGED_DOJI,
  /**
   * Gravestone Doji Candle
   */
  GRAVESTONE_DOJI,
  /**
   * Dragonfly Doji Candle
   */
  DRAGONFLY_DOJI,
  /**
   * Four Price Doji Candle
   */
  FOUR_PRICE_DOJI,
  /**
   * Highwave Candle
   */
  HIGHWAVE,
  /**
   * If None from the Above
   */
  NOT_SPECIFIC
}

Now as mentioned earlier, among the basic candle sticks, some are long and some are short. To find that if the basic candle type formed is long or short, just call

/**
*@return returns the generated  candlestick basic pattern type length. The returned value set is from {LONG,SHORT,NOT_APPLICABLE}
*/
public CandleBasicLength getCandleBasicLength(){
.....
}

Here also you will get the length form the enum constant set CandleBasicLength, which consists of the following:

{
  /**
   * A long candlestick.
   */
  LONG,
  /**
   * A short candlestick
   */
  SHORT,
  /**
   * Where long or short property is not applicable.
   */
  NOT_APPLICABLE;
  }

The single line candle pattern identification api

/**
*@param open : list of opening prices where the last item is the latest data
*@param high : list of high prices where the last item is the latest data
*@param low : list of low prices where the last item is the latest data
*@param close : list of closing prices where the last item is the latest data
*@param scanParams contains body_reference_number, an integer greater than 0,
*length_reference_number, an integer greater than 0,long_short_reference_percentage, a double value greater than 0
*previous_trend_reference_number, an integer value greater than 0,lower_shadow_reference_percentage,  a double value greater than 0
*and upper_shadow_reference_percentage, a double value greater than 0.
*@return Returns the single line candle stick pattern if something is generated.
*@throws DataException if sufficient data not available. 
*/
public CandlePatternSingleLine getSingleLinePattern(List<Double> open,List<Double> high,List<Double>low,List<Double>close,Map<String,Object> scanParams)throws DataException{
...............
}

If valid input is provided to this api, you will get the enum constant from the enum CandlePatternSingleLine corresponding to the formed single line pattern from the following list:

{
 /**
  * Bullish belthold pattern.
  */
 BullishBeltHold,
 /**
  * Bearish bethold pattern
  */
 BearishBeltHold,
 /**
  * Hammer pattern
  */
 Hammer,
 /**
  * Hanging man pattern
  */
 HangingMan,
 /**
  * Southern doji pattern
  */
 SouthernDoji,
 /**
  * Northern doji pattern
  */
 NorthernDoji,
 /**
  * Gapping up doji pattern
  */
 GappingUpDoji,
 /**
  * Gapping down doji pattern
  */
 GappingDownDoji,
 /**
  * Takuri line pattern
  */
 TakuriLine,
 /**
  * One candle shooting star pattern
  */
 OneCandleShootingStar,
 /**
  * Bullish strong line pattern
  */
 BullishStrongLine,
 /**
  * Bearish strong line pattern
  */
 BearishStrongLine,
 /**
  * If no single line pattern is generated from above.
  */
 NotApplicable;
 }

The double line candle pattern identification api

/**
*@param open : list of opening prices where the last item is the latest data
*@param high : list of high prices where the last item is the latest data
*@param low : list of low prices where the last item is the latest data
*@param close : list of closing prices where the last item is the latest data
*@param scanParams contains body_reference_number, an integer greater than 0,
*length_reference_number, an integer greater than 0,long_short_reference_percentage, a double value greater than 0
*previous_trend_reference_number, an integer value greater than 0,lower_shadow_reference_percentage,  a double value greater than 0
*and upper_shadow_reference_percentage, a double value greater than 0.
*@return Returns the double line candle stick pattern if something is generated.
*@throws DataException if sufficient data not available.
*/
public  CandlePatternDoubleLine getDoubleLinePattern(List<Double> open,List<Double> high,List<Double>low,List<Double>close,Map<String,Object> scanParams)throws DataException{
....
}

If valid input is provided to this api, you will get the enum constant from the enum CandlePatternDoubleLine corresponding to the formed double line pattern from the following list:

{
/**
 * Bullish harami pattern
 */
BullishHarami,
/**
 * Bearish harami pattern
 */
BearishHarami,
/**
 * Bullish engulfing pattern
 */
BullishEngulfing,
/**
 * Bearish engulfing pattern
 */
BearishEngulfing,
/**
 * Bullish kicking pattern
 */
BullishKicking,
/**
 * Bearish kicking pattern
 */
BearishKicking,
/**
 * Matching low pattern
 */
MatchingLow,
/**
 * Matching high pattern
 */
MatchingHigh,
/**
 * Bullish harami cross pattern
 */
BullishHaramiCross,
/**
 * Bearish harami cross pattern
 */
BearishHaramiCross,
/**
 * Bullish doji start pattern
 */
BullishDojiStar,
/**
 * Bearish doji star pattern
 */
BearishDojiStar,
/**
 * Dark cloud cover pattern
 */
DarkCloudCover,
/**
 * Piercing line pattern
 */
PiercingLine,
/**
 * Descending hawk pattern
 */
DescendingHawk,
/**
 * Homing pigeon pattern
 */
HomingPigeon,
/**
 * If none of the above
 */
NotApplicable;
}

The multiple line candle pattern identification api

/**
*@param open : list of opening prices where the last item is the latest data
*@param high : list of high prices where the last item is the latest data
*@param low : list of low prices where the last item is the latest data
*@param close : list of closing prices where the last item is the latest data
*@param scanParams contains body_reference_number, an integer greater than 0,
*length_reference_number, an integer greater than 0,long_short_reference_percentage, a double value greater than 0
*previous_trend_reference_number, an integer value greater than 0,lower_shadow_reference_percentage,  a double value greater than 0
*and upper_shadow_reference_percentage, a double value greater than 0.
*@return Returns the multi-line candle stick pattern if something is generated.
*@throws DataException if sufficient data not available.
*/
public  CandlePatternMultiLine getMultiLinePattern(List<Double> open,List<Double> high,List<Double>low,List<Double>close,Map<String,Object> scanParams)throws DataException{    
....
}

If valid input is provided to this api, you will get the enum constant from the enum CandlePatternMultiLine corresponding to the formed multiple line pattern from the following list:

{
 /**
  * Bullish abandoned baby pattern
  */
 BullishAbandonedBaby,
 /**
  * Bearish abandoned baby pattern
  */
 BearishAbandonedBaby,
 /**
  * Three inside up pattern
  */
 ThreeInsideUp,
 /**
  * Three inside down pattern
  */
 ThreeInsideDown,
 /**
  * Three outside up pattern
  */
 ThreeOutsideUp,
 /**
  * Three outside down pattern
  */
 ThreeOutsideDown,
 /**
  * Three white soldiers pattern
  */
 ThreeWhiteSoldiers,
 /**
  * Three Black crows pattern
  */
 ThreeBlackCrows,
 /**
  * Morning doji star pattern
  */
 MorningDojiStar,
 /**
  * Evening doji star pattern
  */
 EveningDojiStar,
 /**
  * Morning star pattern
  */
 MorningStar,
 /**
  * Evening star pattern
  */
 EveningStar,
 /**
  * Upside tasuki gap pattern
  */
 UpsideTasukiGap,
 /**
  * Down side tasuki gap pattern
  */
 DownsideTasukiGap,
 /**
  * Bullish side by side white lines pattern
  */
 BullishSidebySideWhiteLines,
 /**
  * Bearish side by side white lines pattern
  */
 BearishSidebySideWhiteLines,
 /**
  * Rising three pattern
  */
 RisingThreeMethod,
 /**
  * If none of the above
  */
 NotApplicable;
 }

Pattern Significance

From the single, double and multiple line patterns, it is generally said that some are bullish and some are bearish in nature.
To get the general nature of the form, the following api is provided:

/**
*@return returns the generated  candlestick pattern type. The returned value set is from {BULLISH,BEARISH,NOT_APPLICABLE}
*/
public CandleSignalType getCandleSignalType(){
.....
}

DISCLAIMER

The bullish or bearish nature of a candle pattern is general in nature. Other market factors sometimes play a significant role in setting the future price dirrection. So it is recommended to get the bullish or bearish nature of the pattern to be taken for granted only if other market factors are supportive.

Example Usage

  public void test(List<Double> open,List<Double> high,List<Double>low,List<Double>close) {
    CandleTypeBasic ctb;
    CandleBasicLength cbl;
    CandlePatternSingleLine cpsl;
    CandlePatternDoubleLine cpdl;
    CandlePatternMultiLine cpml;
    CandleSignalType cst;
    CANDLETYPE  l=new CANDLETYPE();
    Map<String,Object> scanParams=new HashMap<String, Object>();
    scanParams.put("body_reference_number","5");
    scanParams.put("length_reference_number","10");
    scanParams.put("long_short_reference_percentage","70");
    scanParams.put("previous_trend_reference_number","25");
    scanParams.put("lower_shadow_reference_percentage","25");
    scanParams.put("upper_shadow_reference_percentage","25");
    try{			   
      ctb=l.getBasicCandleType(open, high, low, close, scanParams);
      cbl=l.getCandleBasicLength();
      System.out.println("Basic Candle Type : "+ctb.toString());
      System.out.println("Basic Candle Type Length : "+cbl.toString());
      cpsl=l.getSingleLinePattern(open, high, low, close, scanParams);
      cst=l.getCandleSignalType();
      System.out.println("One line Candle pattern : "+cpsl.toString());
      System.out.println("One line Candle pattern type : "+cst.toString());
      cpdl=l.getDoubleLinePattern(open,high,low,close,scanParams);
      cst=l.getCandleSignalType();
      System.out.println("Double line Candle pattern : "+cpdl.toString());
      System.out.println("Double line Candle pattern type : "+cst.toString());
      cpml=l.getMultiLinePattern(open,high,low,close,scanParams);
      cst=l.getCandleSignalType();
      System.out.println("Multi line Candle pattern : "+cpml.toString());
      System.out.println("Multi line Candle pattern type : "+cst.toString());
      }
      catch(DataException e){
       e.printStackTrace();
      }
 }

Guideline to include the apis

To include this package in your project, include the following dependency:

<dependency>
    <groupId>in.kncsolutions.dhelm.candlescanner</groupId>
    <artifactId>dhelm-candlescanner</artifactId>
    <version>1.0.0</version>
</dependency>

Alternatively you can add the library to your project by downloading this from the download section.

You can get the necessary information for including this in your project from here.

Source Code maintainance

You can get the source code for this package here.