Chess Cloud Database API Documentation

 

 

Brief

 

Chess Cloud Database(aka. "CDB") API has two parts, first is to probe the database, which can be achieved by reqesting CDB's HTTP-based RESTful API.

Then, as an extension to the existing UCI engine protocol, a few new options can be added so that the GUI and the engine can work better when handling results from CDB.

 

RESTful API Interface

 

CDB's API access point is: http://www.chessdb.cn/cdb.php?action=[ACTION]{&[OPTION1]=[VALUE1]...&[OPTIONn]=[VALUEn]}

 

In which the fields are defined as:

 

ACTION: Action type, for example, query all known moves (queryall), suggest a move (query / querybest), request analysis (queue), etc.

 

OPTION & VALUE: Options, for example, position to query (board) and automatic learning (learn), etc.

 

Query All Known Moves (queryall)

 

Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

 

Optional: showall, set to false if unknown moves should be omitted, e.g. &showall=0 or &showall=1, default is 0, only return known moves

 

Optional: egtbmetric, set to desired EGTB metric, e.g. &egtbmetric=dtz or &egtbmetric=dtm, default is dtz, using DTZ tablebases

 

Optional: learn, set to whether automatic learning should be enabled, e.g. &learn=0 or &learn=1, default is 1, enabling automatic learning

 

Return: move data separated by "|", of which each field is separated by ",", fields may contain "move", "score", "rank", "winrate" and "note"

 

If the position is invalid, "invalid board" is returned, if the position is unknown, "unknown" is returned, if the position is a checkmate or stalemate, "checkmate" or "stalemate" is returned

 

Suggest Best, Random or Candidate Moves (querybest/query/querysearch)

 

Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

 

Optional: endgame, set to whether only EGTB data should be returned, e.g. &endgame=0 or &endgame=1, default is 0, all data are returned

 

Optional: egtbmetric, set to desired EGTB metric, e.g. &egtbmetric=dtz or &egtbmetric=dtm, default is dtz, using DTZ tablebases

 

Optional: learn, set to whether automatic learning should be enabled, e.g. &learn=0 or &learn=1, default is 1, enabling automatic learning

 

Return: move data separated by "|", of which a normal move are returned as move:[MOVE], an EGTB move is returned as egtb:[MOVE], a candidate move is returned as search:[MOVE]

 

Candidate moves are a list of moves that may require further processing, such as sending them as "searchmoves" to an engine

 

If the position is invalid, "invalid board" is returned, if no satisfing move is found, "nobestmove" is returned

 

Query Evaluation Scores (queryscore)

 

Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

 

Optional: egtbmetric, set to desired EGTB metric, e.g. &egtbmetric=dtz or &egtbmetric=dtm, default is dtz, using DTZ tablebases

 

Optional: learn, set to whether automatic learning should be enabled, e.g. &learn=0 or &learn=1, default is 1, enabling automatic learning

 

Return: CDB's evaluation score of the position, as in eval:[SCORE]

 

If the position is invalid, "invalid board" is returned, if the position is unknown, "unknown" is returned

 

Query Analysis Lines (querypv)

 

Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

 

Optional: egtbmetric, set to desired EGTB metric, e.g. &egtbmetric=dtz or &egtbmetric=dtm, default is dtz, using DTZ tablebases

 

Optional: learn, set to whether automatic learning should be enabled, e.g. &learn=0 or &learn=1, default is 1, enabling automatic learning

 

Return: CDB's analysis line of the position, as in score:[SCORE],depth:[DEPTH],pv:[MOVE1]{...|[MOVEn]}

 

If the position is invalid, "invalid board" is returned, if the position is unknown, "unknown" is returned

 

Request for Analysis (queue)

 

Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

 

Return: ok means success

 

If the position is invalid, "invalid board" is returned, if the position is trivial, nothing is returned

 

Request for Analysis of a Particular Move (store)

 

Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

 

Mandatory: move, set to the desired move for analysis, e.g. &move=move:c3c4

 

Return: ok means success

 

If the position is invalid, "invalid board" is returned, if the position is trivial, nothing is returned

 

 

UCI Extensions

 

Usually, only GUIs should send API queries to CDB, engines do not need to make any network queries.

Preferably GUIs can inform the engines about the information returned from CDB via UCI, for example:

 

Opening Move Suggestion (bookmove)

 

While sending "go" commands to engines, append "bookmove [MOVE]" to suggest a move from opening book, engines can decide whether to immediately return "bestmove [MOVE]" or start their own search ignoring the suggestions.

 

This option is ignored in analysis mode (go infinite) or pondering (go ponder) and must be placed before "searchmoves"

 

Principal Variation Hints (hint)

 

During searches, sending "hint score [SCORE] depth [DEPTH] pv [MOVE1]{... [MOVEn]}" to inform engines about known principal variations.

 

EGTB Move Suggestion (egtbmove)

 

While sending "go" commands to engines, append "egtbmove [MOVE]" to suggest a move from EGTB, engines can decide whether to immediately return "bestmove [MOVE]" or start their own search ignoring the suggestions.

 

This option is ignored in analysis mode (go infinite) or pondering (go ponder) and must be placed before "searchmoves"