Documentation

Chess API for Web Apps

The ChesslaBlab Chess API allows to create chess web apps using GET and POST HTTP requests. It is open-source and can be hosted on a custom domain.

GET /autocomplete

Returns autocomplete data for chess events and players.

curl https://pchess.net/api/autocomplete

Response

{
  "events": [
    { "Event": "1/2 Coupe de France" },
    { "Event": "1/4 Coupe de France" },
    ...
    { "Event": "Zvenigorodskaya Open A" },
    { "Event": "Zwolle op" }
  ],
  "players": [
    { "name": "A-Ali,Sali Abbas Abdulzahra" },
    { "name": "Aaberg,A" },
    ...
    { "name": "Zytogorski, Adolf" },
    { "name": "Zyulyarkin" }
  ]
}
GET /stats/opening

Returns statistics about the chess openings available in the database: Draw rate, win rate for White and win rate for Black.

curl https://pchess.net/api/stats/opening

Response

{
  "drawRate": [
    {
      "ECO": "C42",
      "total": 2964
    },
    ...
    {
      "ECO": "B23",
      "total": 1044
    }
  ],
  "winRateForWhite": [
    {
      "ECO": "A45",
      "total": 2880
    },
    ...
    {
      "ECO": "B51",
      "total": 1053
    }
  ],
  "winRateForBlack": [
    {
      "ECO": "A45",
      "total": 2658
    },
    ...
    {
      "ECO": "D10",
      "total": 732
    }
  ]
}
POST /download/image

Downloads an image.

Parameters

Name Description Required
variant Accepts:
  • 960
  • capablanca80
  • classical
 Yes
fen A FEN string. Yes
flip Accepts:
  • w
  • b
 Yes

Example

curl https://pchess.net/api/download/image \
  -H "Content-Type: application/json" \
  --data-raw '{
    "variant": "classical",
    "fen": "r1bq1rk1/pppnn1bp/3p2p1/3Ppp2/2P1P3/2N2P2/PP2B1PP/R1BQNRK1 w - f6",
    "flip": "w"
  }' \
  --output image.png

Response

Chess position
POST /download/mp4

Downloads a video.

Parameters

Name Description Required
variant Accepts:
  • 960
  • capablanca80
  • classical
 Yes
fen A FEN string. No
movetext A portable game notation (PGN) movetext. Yes
startPos Start position in a Fischer Random game, also known as Chess960. Only in a Chess960 game.
flip Accepts:
  • w
  • b
 Yes

Example

Downloads a classical game from the start position.

curl https://pchess.net/api/download/mp4 \
  -H "Content-Type: application/json" \
  --data-raw '{
    "variant": "classical",
    "movetext": "1.d4 Nf6 2.c4 g6 3.Nc3 Bg7 4.e4 d6",
    "flip": "b"
  }' \
  --output video.mp4

Response

Example

Downloads a classical game from a FEN position.

curl https://pchess.net/api/download/mp4 \
  -H "Content-Type: application/json" \
  --data-raw '{
    "variant": "classical",
    "fen": "4k2r/pp1b1pp1/8/3pPp1p/P2P1P2/1P3N2/1qr3PP/R3QR1K w k -",
    "movetext": "1.Rb1 Qa2",
    "flip": "w"
  }' \
  --output video.mp4

Response

Example

Downloads a Chess960 game from a FEN position.

curl https://pchess.net/api/download/mp4 \
  -H "Content-Type: application/json" \
  --data-raw '{
    "variant": "960",
    "fen": "rnkbnqbr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNKBNQBR w KQkq e6",
    "movetext": "1.Nf3 Nc6",
    "startPos": "RNKBNQBR",
    "flip": "b"
  }' \
  --output video.mp4

Response

Example

Downloads a Capablanca game from a FEN position.

curl https://pchess.net/api/download/mp4 \
  -H "Content-Type: application/json" \
  --data-raw '{
    "variant": "capablanca80",
    "fen": "rnabqkbcnr/ppppp1pppp/10/5p4/5P4/10/PPPPP1PPPP/RNABQKBCNR w KQkq f6",
    "movetext": "1.Cg3 Ad6",
    "flip": "w"
  }' \
  --output video.mp4

Response

POST /engine/stockfish

Returns Stockfish's move in LAN format.

Parameters

Name Description Required
movetext A long algebraic notation (LAN) movetext. Yes
skillLevel Accepts an integer value between 0 and 20. Yes
depth Accepts an integer value between 1 and 15. Yes

Example

curl https://pchess.net/api/engine/stockfish \
  -H "Content-Type: application/json" \
  --data-raw '{
    "movetext": "e2e4 e7e5",
    "skillLevel": "9",
    "depth": "3"
  }'

Response

{
  "move": "b1c3",
  "fen": "rnbqkbnr/pppp1ppp/8/4p3/4P3/2N5/PPPP1PPP/R1BQKBNR b KQkq -",
  "isCheck": false,
  "isMate": false,
  "movetext": "1.e4 e5 2.Nc3"
}
POST /grandmaster

Returns a chess game played by a random FIDE titled player.

Parameters

Name Description Required
movetext A portable game notation (PGN) movetext. Yes

Example

curl https://pchess.net/api/grandmaster \
  -H "Content-Type: application/json" \
  --data-raw '{
    "movetext": "1.e4 c6 2.Nc3"
  }'

Response

[
  {
    "id": 157019,
    "Event": "38th Olympiad",
    "Site": "Dresden GER",
    "Date": "2008.11.22",
    "White": "Can,E",
    "Black": "Nielsen,PH",
    "Result": "1/2-1/2",
    "WhiteElo": "2464",
    "BlackElo": "2662",
    "ECO": "B11",
    "FEN": null,
    "movetext": "1.e4 c6 2.Nc3 d5 3.Nf3 Bg4 4.h3 Bxf3 5.Qxf3 e6 6.d4 dxe4 7.Nxe4 Qxd4 8.Bd3 Nd7 9.Be3 Qd5 10.O-O Ne5 11.Qg3 Nxd3 12.cxd3 Nf6 13.Bg5 Be7 14.Bxf6 Bxf6 15.Qc7 Qd7 16.Nd6+ Ke7 17.Nf5+ Ke8 18.Nd6+ Ke7 19.Nf5+ Ke8"
  }
]
POST /opening

Finds up to 25 chess openings matching the criteria.

Parameters

Name Description Required
eco Encyclopaedia of Chess Openings (ECO) code. No
name Opening name. No
movetext Opening moves. No

Example

curl https://pchess.net/api/opening \
  -H "Content-Type: application/json" \
  --data-raw '{
    "eco": "B90"
  }'

Response

[
  {
    "id": 4820,
    "eco": "B90",
    "name": "Sicilian Defense: Scheveningen Variation, English Attack",
    "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Be3 e6 7.f3"
  },
  {
    "id": 4813,
    "eco": "B90",
    "name": "Sicilian Defense: Najdorf Variation, Dekker Gambit",
    "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.g4"
  },
  {
    "id": 4815,
    "eco": "B90",
    "name": "Sicilian Defense: Najdorf Variation, English Attack, Anti-English",
    "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Be3 Ng4"
  },
  {
    "id": 4816,
    "eco": "B90",
    "name": "Sicilian Defense: Najdorf Variation, Freak Attack",
    "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Rg1"
  },
  {
    "id": 4814,
    "eco": "B90",
    "name": "Sicilian Defense: Najdorf Variation, English Attack",
    "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Be3"
  },
  {
    "id": 4812,
    "eco": "B90",
    "name": "Sicilian Defense: Najdorf Variation, Adams Attack",
    "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.h3"
  },
  {
    "id": 4818,
    "eco": "B90",
    "name": "Sicilian Defense: Scheveningen Variation, Delayed Keres Attack",
    "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Be3 e6 7.g4"
  },
  {
    "id": 4811,
    "eco": "B90",
    "name": "Sicilian Defense: Najdorf Variation",
    "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6"
  },
  {
    "id": 4819,
    "eco": "B90",
    "name": "Sicilian Defense: Scheveningen Variation, Delayed Keres Attack, Perenyi Gambit",
    "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Be3 e6 7.g4 e5 8.Nf5 g6 9.g5"
  },
  {
    "id": 4817,
    "eco": "B90",
    "name": "Sicilian Defense: Najdorf Variation, Lipnitsky Attack",
    "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Bc4"
  }
]
POST /play/lan

Plays chess in long algebraic notation (LAN) format.

Parameters

Name Description Required
variant Accepts:
  • 960
  • capablanca80
  • classical
 Yes
startPos Start position in a Fischer Random game, also known as Chess960. Only in a Chess960 game.
movetext A long algebraic notation (LAN) movetext. Yes

Example

curl https://pchess.net/api/play/lan \
  -H "Content-Type: application/json" \
  --data-raw '{
    "variant": "960",
    "startPos": "RQKBBNNR",
    "movetext": "e2e4 e7e5"
  }'

Response

{
  "fen": "rqkbbnnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RQKBBNNR w KQkq e6",
  "isCheck": false,
  "isMate": false,
  "movetext": "1.e4 e5"
}
POST /play/pgn

Plays chess in portable game notation (PGN) format.

Parameters

Name Description Required
variant Accepts:
  • 960
  • capablanca80
  • classical
 Yes
startPos Start position in a Fischer Random game, also known as Chess960. Only in a Chess960 game.
movetext A portable game notation (PGN) movetext. Yes

Example

curl https://pchess.net/api/play/pgn \
  -H "Content-Type: application/json" \
  --data-raw '{
    "variant": "960",
    "startPos": "RQKBBNNR",
    "movetext": "1.e4 e5"
  }'

Response

{
  "fen": "rqkbbnnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RQKBBNNR w KQkq e6",
  "isCheck": false,
  "isMate": false,
  "movetext": "1.e4 e5"
}
POST /search

Finds up to 25 games matching the criteria.

Parameters

Name Description Required
Event The name of the event. No
Date The year in which the event took place. No
White The player with the white pieces. No
Black The player with the black pieces. No
Result Accepts:
  • 1-0
  • 0-1
  • 1/2-1/2
 No
ECO Encyclopaedia of Chess Openings (ECO) code. No

Example

curl https://pchess.net/api/search \
  -H "Content-Type: application/json" \
  --data-raw '{
    "Black": "Kasparov,G",
    "ECO": "D37"
  }'

Response

[
  {
    "id": 156639,
    "Event": "Rapid",
    "Site": "Reykjavik ISL",
    "Date": "2004.03.20",
    "White": "Nielsen,PH",
    "Black": "Kasparov,G",
    "Result": "1\/2-1\/2",
    "WhiteElo": "2638",
    "BlackElo": "2831",
    "ECO": "D37",
    "FEN": null,
    "movetext": "1.d4 Nf6 2.c4 e6 3.Nf3 d5 4.Nc3 Be7 5.Bf4 O-O 6.e3 c5 7.dxc5 Bxc5 8.a3 Nc6 9.Rc1 a6 10.b4 Bd6 11.Bg5 a5 12.b5 Ne7 13.Bxf6 gxf6 14.a4 Bb4 15.Be2 dxc4 16.O-O Nd5 17.Na2 Nb6 18.Qc2 e5 19.Nxb4 axb4 20.Bxc4 Nxc4 21.Qxc4 Rxa4 22.Rfd1 Qb6 23.Nh4 Be6 24.Qe4 Qxb5 25.Qf3 Kg7 26.Nf5+ Bxf5 27.Qxf5 b3 28.Rd6 b2 29.Qxf6+ Kg8 30.Qg5+ Kh8 31.Qf6+"
  },
  {
    "id": 369145,
    "Event": "Corus",
    "Site": "Wijk aan Zee NED",
    "Date": "2001.01.27",
    "White": "Van Wely,L",
    "Black": "Kasparov,G",
    "Result": "1\/2-1\/2",
    "WhiteElo": "2700",
    "BlackElo": "2849",
    "ECO": "D37",
    "FEN": null,
    "movetext": "1.d4 Nf6 2.c4 e6 3.Nf3 d5 4.Nc3 Be7 5.Bf4 O-O 6.e3 c5 7.dxc5 Bxc5 8.cxd5 Nxd5 9.Nxd5 exd5 10.a3 Nc6 11.Bd3 Bb6 12.O-O Bg4 13.h3 Bh5 14.b4 Re8 15.Rc1 a6 16.g4 Bg6 17.Bxg6 hxg6 18.Rc3 d4 19.Rd3 Qd5 20.exd4 Re4 21.Be3 Rd8 22.Re1 f6 23.Kg2 f5 24.gxf5 gxf5 25.Qb3 Qxb3 26.Rxb3 f4 27.d5 fxe3 28.dxc6 Re6 29.fxe3 Rxc6 30.Kf2 Rf8 31.Ke2 Rc2+ 32.Nd2 Rd8 33.Rd3 Ra2 34.Rxd8+ Bxd8 35.Rc1 Bf6 36.Rc7 b5 37.Rc6 Rxa3 38.Ne4 Be7 39.Nc5 a5 40.Rb6 axb4 41.Rxb5 Ra2+ 42.Kd3 Rh2 43.Na6"
  },
  {
    "id": 332967,
    "Event": "Corus",
    "Site": "Wijk aan Zee NED",
    "Date": "2001.01.27",
    "White": "Van Wely,L",
    "Black": "Kasparov,G",
    "Result": "1\/2-1\/2",
    "WhiteElo": "2700",
    "BlackElo": "2849",
    "ECO": "D37",
    "FEN": null,
    "movetext": "1.d4 Nf6 2.c4 e6 3.Nf3 d5 4.Nc3 Be7 5.Bf4 O-O 6.e3 c5 7.dxc5 Bxc5 8.cxd5 Nxd5 9.Nxd5 exd5 10.a3 Nc6 11.Bd3 Bb6 12.O-O Bg4 13.h3 Bh5 14.b4 Re8 15.Rc1 a6 16.g4 Bg6 17.Bxg6 hxg6 18.Rc3 d4 19.Rd3 Qd5 20.exd4 Re4 21.Be3 Rd8 22.Re1 f6 23.Kg2 f5 24.gxf5 gxf5 25.Qb3 Qxb3 26.Rxb3 f4 27.d5 fxe3 28.dxc6 Re6 29.fxe3 Rxc6 30.Kf2 Rf8 31.Ke2 Rc2+ 32.Nd2 Rd8 33.Rd3 Ra2 34.Rxd8+ Bxd8 35.Rc1 Bf6 36.Rc7 b5 37.Rc6 Rxa3 38.Ne4 Be7 39.Nc5 a5 40.Rb6 axb4 41.Rxb5 Ra2+ 42.Kd3 Rh2 43.Na6"
  },
  {
    "id": 369372,
    "Event": "Rapid",
    "Site": "Reykjavik ISL",
    "Date": "2004.03.20",
    "White": "Nielsen,PH",
    "Black": "Kasparov,G",
    "Result": "1\/2-1\/2",
    "WhiteElo": "2638",
    "BlackElo": "2831",
    "ECO": "D37",
    "FEN": null,
    "movetext": "1.d4 Nf6 2.c4 e6 3.Nf3 d5 4.Nc3 Be7 5.Bf4 O-O 6.e3 c5 7.dxc5 Bxc5 8.a3 Nc6 9.Rc1 a6 10.b4 Bd6 11.Bg5 a5 12.b5 Ne7 13.Bxf6 gxf6 14.a4 Bb4 15.Be2 dxc4 16.O-O Nd5 17.Na2 Nb6 18.Qc2 e5 19.Nxb4 axb4 20.Bxc4 Nxc4 21.Qxc4 Rxa4 22.Rfd1 Qb6 23.Nh4 Be6 24.Qe4 Qxb5 25.Qf3 Kg7 26.Nf5+ Bxf5 27.Qxf5 b3 28.Rd6 b2 29.Qxf6+ Kg8 30.Qg5+ Kh8 31.Qf6+"
  }
]
POST /stats/event

Returns statistics about opening results in chess events.

Parameters

Name Description Required
Event The name of the event. No
Result Accepts:
  • 1-0
  • 0-1
  • 1/2-1/2
 No

Example

curl https://pchess.net/api/stats/event \
  -H "Content-Type: application/json" \
  --data-raw '{
    "Event": "FIDE Candidates 2022",
    "Result": "0-1"
  }'

Response

[
	{
		"ECO": "C42",
		"total": 2
	},
	{
		"ECO": "C65",
		"total": 2
	},
    ...
	{
		"ECO": "A20",
		"total": 1
	},
	{
		"ECO": "E06",
		"total": 1
	}
]
POST /stats/player

Returns statistics about opening results by chess player.

Parameters

Name Description Required
White The player with the white pieces. No
Black The player with the black pieces. No
Result Accepts:
  • 1-0
  • 0-1
  • 1/2-1/2
 No

Example

curl https://pchess.net/api/stats/player \
  -H "Content-Type: application/json" \
  --data-raw '{
    "White": "Kasparov, Gary",
    "Result": "0-1"
  }'

Response

[
  {
    "ECO": "C54",
    "total": 6
  },
  {
    "ECO": "A29",
    "total": 4
  },
  ...
  {
    "ECO": "C01",
    "total": 1
  },
  {
    "ECO": "B50",
    "total": 1
  }
]

Chess Server for Web Apps

The ChesslaBlab Chess Server provides additional functionality to play chess online. It is based on WebSockets and can be hosted on a custom domain.

This is how to open a WebSocket connection in JavaScript.

const ws = new WebSocket('wss://pchess.net:8443');

That's it!

Now you're set up to start playing chess.

ws.send('/start classical analysis');

The /start command above starts a new classical chess game and retrieves a JSON response from the server.

{
  "\/start": {
    "variant":"classical",
    "mode":"analysis",
    "fen":"rnbqkbnr\/pppppppp\/8\/8\/8\/8\/PPPPPPPP\/RNBQKBNR w KQkq -"
  }
}

On successful server response a FEN string representing the starting position is returned as well as the variant and the mode required.

This is the classical starting position in FEN format.

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -

As you can see in the server's response, forward slashes are escaped with a backslash. From now on this will be assumed, and forward slashes won't be escaped for the sake of simplicity and for documentation purposes.

Now you're ready to make your first move.

What about 1.e4?

This is the so-called King's Pawn Game, one of the most popular chess openings, in Portable Game Notation (PGN) format. Humans can understand chess games in PGN easily but this format is not that great for computers as well as for graphic user interfaces (GUI) which may prefer the Long Algebraic Notation (LAN) format instead.

Let's play 1.e4 in LAN format.

ws.send('/play_lan w e2e4');

The /play_lan command makes the chess move retrieving the following JSON response.

{
  "/play_lan": {
    "turn": "w",
    "isLegal": true,
    "isCheck": false,
    "isMate": false,
    "movetext": "1.e4",
    "fen": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3",
    "pgn": "e4"
  }
}

A popular response to 1.e4 is 1...e5 which in LAN format is e7e5.

ws.send('/play_lan b e7e5');

Once again the /play_lan command makes this chess move retrieving the following JSON response.

{
  "/play_lan": {
    "turn": "b",
    "isLegal": true,
    "isCheck": false,
    "isMate": false,
    "movetext": "1.e4 e5",
    "fen": "rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq e6",
    "pgn": "e5"
  }
}

Let's recap.

Described below is the series of steps required to start a classical chess game with 1.e4 e5. Remember, computers and graphic user interfaces (GUIs) usually prefer the Long Algebraic Notation (LAN) format instead: e2e4 and e7e5.

const ws = new WebSocket('wss://pchess.net:8443');
ws.send('/start classical analysis');
ws.send('/play_lan w e2e4');
ws.send('/play_lan b e7e5');

The /start command accepts two mandatory params: A chess variant and a game mode. These two play an important role in shaping the way a chess game is started so here's a description of both.

Variant
Name Description
960 Chess960, also known as Fischer Random chess.
capablanca80 Capablanca chess played on a 10×8 board.
classical Classical chess.
Mode
Name Description
analysis Start a game from the start position for further analysis.
gm Start a game from a PGN movetext to play with a grandmaster.
fen Start a game from a FEN position for further analysis.
pgn Start a game from a PGN movetext for further analysis.
play Start a game to play online with an opponent.
stockfish Start a game to play with the Stockfish chess engine.

Now let's have a look at the WebSocket commands available!

The list of commands could have been sorted in alphabetical order but it is more convenient to begin with the /start command and continue in a way that's easier to understand.

/start

Starts a new chess game.

Parameters

Name Description Required
variant Accepts:
  • 960
  • capablanca80
  • classical
 Yes
mode Accepts:
  • analysis
  • gm
  • fen
  • pgn
  • play
  • stockfish
 Yes
add Additional, specific params:
  • color (gm and stockfish modes)
  • fen (fen mode)
  • movetext (pgn mode)
  • settings (play mode)
  • startPos (pgn mode)
 Maybe, depends on the mode selected.

Example

Starts a classical game for further analysis.

ws.send('/start classical analysis');

Response

{
  "/start": {
    "variant": "classical",
    "mode": "analysis",
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -"
  }
}

Example

Starts a classical game in grandmaster mode.

ws.send('/start classical gm w');

Response

{
  "/start": {
    "variant": "classical",
    "mode": "gm",
    "color": "w"
  }
}

Example

Starts a classical game in FEN mode for further analysis.

ws.send('/start classical fen "r1bqkbnr/pppppppp/2n5/8/3PP3/8/PPP2PPP/RNBQKBNR b KQkq d3"');

Response

{
  "/start": {
    "variant": "classical",
    "mode": "fen",
    "fen": "r1bqkbnr/pppppppp/2n5/8/3PP3/8/PPP2PPP/RNBQKBNR b KQkq d3"
  }
}

Example

Starts a classical game in PGN mode for further analysis.

ws.send('/start classical pgn "1.e4 Nc6 2.d4"');

Response

{
  "/start": {
    "variant": "classical",
    "mode": "pgn",
    "turn": "b",
    "movetext": "1.e4 Nc6 2.d4",
    "fen": "r1bqkbnr/pppppppp/2n5/8/3PP3/8/PPP2PPP/RNBQKBNR b KQkq d3",
    "history": [
      [
        [
          " r ",
          " n ",
          " b ",
          " q ",
          " k ",
          " b ",
          " n ",
          " r "
        ],
        ...
        [
          " R ",
          " N ",
          " B ",
          " Q ",
          " K ",
          " B ",
          " N ",
          " R "
        ]
      ]
    ]
  }
}

Example

Starts a Chess960 game in PGN mode for further analysis.

ws.send('/start 960 pgn "1.e4 Nc6 2.d4" BNRKQBRN');

Response

{
  "/start": {
    "variant": "960",
    "mode": "pgn",
    "turn": "b",
    "movetext": "1.e4 Nc6 2.d4",
    "fen": "b1rkqbrn/pppppppp/2n5/8/3PP3/8/PPP2PPP/BNRKQBRN b KQkq d3",
    "history": [
      [
        [
          " r ",
          " n ",
          " b ",
          " q ",
          " k ",
          " b ",
          " n ",
          " r "
        ],
        ...
        [
          " B ",
          " N ",
          " R ",
          " K ",
          " Q ",
          " B ",
          " R ",
          " N "
        ]
      ]
    ]
  }
}

Example

Creates an invite code (a hash) to play a classical game with a friend.

ws.send('/start classical play {"min":5,"increment":3,"color":"b","submode":"friend"}');

Response

{
  "/start": {
    "variant": "classical",
    "mode": "play",
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -",
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJwY2hlc3MubmV0IiwiaWF0IjoxNjc2NzYwNTgxLCJleHAiOjE2NzY3NjQxODEsInZhcmlhbnQiOiJjbGFzc2ljYWwiLCJzdWJtb2RlIjoiZnJpZW5kIiwiY29sb3IiOiJiIiwibWluIjo1LCJpbmNyZW1lbnQiOjMsImZlbiI6InJuYnFrYm5yXC9wcHBwcHBwcFwvOFwvOFwvOFwvOFwvUFBQUFBQUFBcL1JOQlFLQk5SIHcgS1FrcSAtIn0.jbVZGSaD9Q-QSrRkIdl-XXWMCuSV_4nrfJl28FObC24",
    "hash": "9eebcdf09342ef257407f341518b5d81"
  }
}

Example

Starts a classical game in Stockfish mode.

ws.send('/start classical stockfish b');

Response

{
  "/start": {
    "variant": "classical",
    "mode": "stockfish",
    "color": "b"
  }
}
/legal_sqs

Returns the legal squares of a piece.

Parameters

Name Description Required
position The location of the piece on the board. Yes

Example

Starts a classical game to find out the legal squares of the piece on e2.

ws.send('/start classical analysis');
ws.send('/legal_sqs e2');

Response

{
  "/legal_sqs": {
    "color": "w",
    "id": "P",
    "sqs": [
      "e3",
      "e4"
    ]
  }
}
/play_lan

Plays a chess move in long algebraic notation (LAN) format.

Parameters

Name Description Required
color The player's turn. Yes
lan The chess move in LAN format. Yes

Example

Starts a classical game to play 1.e4.

ws.send('/start classical analysis');
ws.send('/play_lan w e2e4');

Response

{
  "/play_lan": {
    "turn": "w",
    "isLegal": true,
    "isCheck": false,
    "isMate": false,
    "movetext": "1.e4",
    "fen": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3",
    "pgn": "e4"
  }
}
/undo

Undoes the last move.

Example

Starts a classical game to play 1.e4 e5 2.f4 undoing the last move.

ws.send('/start classical analysis');
ws.send('/play_lan w e2e4');
ws.send('/play_lan b e7e5');
ws.send('/play_lan w f2f4');
ws.send('/undo');

Response

{
  "/undo": {
    "turn": "w",
    "pgn": "e5",
    "castlingAbility": "KQkq",
    "movetext": "1.e4 e5",
    "fen": "rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq e6",
    "isCheck": false,
    "isMate": false,
    "isStalemate": false,
    "mode": "analysis"
  }
}
/heuristics

Takes a balanced heuristic picture of the given PGN movetext. A chess game can be plotted in terms of balance. +1 is the best possible evaluation for White and -1 the best possible evaluation for Black. Both forces being set to 0 means they're balanced.

Parameters

Name Description Required
movetext A portable game notation (PGN) movetext. Yes

Example

ws.send('/start classical analysis');
ws.send('/heuristics "1.d4 Nf6 2.c4 e6 3.Nf3 b6 4.Nc3"');

Response

{
  "/heuristics": {
    "dimensions": [
      "Material",
      "Center",
      "Connectivity",
      "Space",
      "Pressure",
      "King safety",
      "Tactics",
      "Attack",
      "Doubled pawn",
      "Passed pawn",
      "Isolated pawn",
      "Backward pawn",
      "Absolute pin",
      "Relative pin",
      "Absolute fork",
      "Relative fork",
      "Square outpost",
      "Knight outpost",
      "Bishop outpost",
      "Bishop pair",
      "Bad bishop",
      "Direct opposition"
    ],
    "balance": [
      [ 0, 0.38, -0.37, 0.5, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ],
      ...
      [ 0, 0.43, 0, 0.25, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
    ]
  }
}

The returned data can then be plotted on a chart as shown in the example below.

Chess heuristics
/heuristics_bar

Similar to the /heuristics command with the difference that /heuristics_bar takes a picture of the current position only rather than a picture of the entire game.

Parameters

Name Description Required
fen A FEN string. Yes
variant Accepts:
  • 960
  • capablanca80
  • classical
 Yes

Example

ws.send('/start classical analysis');
ws.send('/heuristics_bar "rnbqkb1r/p1pp1ppp/1p2pn2/8/2PP4/2N2N2/PP2PPPP/R1BQKB1R b KQkq -" classical');

Response

{
  "/heuristics_bar": {
    "dimensions": [
      "Material",
      "Center",
      "Connectivity",
      "Space",
      "Pressure",
      "King safety",
      "Tactics",
      "Attack",
      "Doubled pawn",
      "Passed pawn",
      "Isolated pawn",
      "Backward pawn",
      "Absolute pin",
      "Relative pin",
      "Absolute fork",
      "Relative fork",
      "Square outpost",
      "Knight outpost",
      "Bishop outpost",
      "Bishop pair",
      "Bad bishop",
      "Direct opposition"
    ],
    "balance": [
      0, 0.28, 0, 0.07, 0, 0, 0, 0, 0, 0, 0, 0.04, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
    ]
  }
}

The returned data can then be plotted on a chart as shown in the example below.

Chess heuristics

To be continued. The commands available are being documented in this section, please be patient.

Keep it up, and happy coding and learning!