Guide to simpleChessMove API

The simpleChessMove API is publicly available and can suggest a move for any game. Below is an example query:

fetch("https://airbackend.com/chessMove/api.php", {
    method: "POST",
    body: JSON.stringify({
        request: "nextMove",
        gameState: "rnbqkbnrpppppppp--------------------------------PPPPPPPPRNBQKBNRw1111",
        level: 4,
        move: [[0, 1], [2, 2]]
    })
}).then((result) => {
    result.json().then((jsonResult) => {
        console.log(jsonResult);
    });
});

The parameter "gameState" is a string that contains all the relevant information about the game:

The first 64 characters represent the spaces on the board. White pieces are indicated by lowercase letters, black pieces are indicated by uppdercase letters, and dashes indicate empty spaces. The ranks are listed in ascending order with spaces left to right from white's perspective, so the first 8 characters, "rnbqkbnr", represent white's major pieces.

The next character is either "w" or "b" and indicates who's turn it is. The API will return a move for that side.

The next four characters are either 1s or 0s and indicate which castle moves are still allowed in order of white kingside, white queenside, black kingside, and black queenside.

The state shown above is a new game, before white has taken its first move. Suppose white moves pawn to e4. Then the state would look like this:

        rnbqkbnrpppp-ppp------------p-------------------PPPPPPPPRNBQKBNRb111134

Note that in addition to the pawn moving, two additional characters, "34", are attached to the end of the string.

Those two optional characters indicate that the most recent move was a two-space pawn move, so the API can consider en passant moves in its response. The two characters represent the location of the pawn that just moved, in [row, column] order, both zero-indexed. So the pawn that just moved is now on row 3, in column 4. Space [0, 0] is the first rank, all the way to white's left.

The "request" parameter specifies what is requested of the API, and can be "nextMove" or "checkMove". "checkMove" sends a move and requests the API to determine if it is a legal move; see below for more about that.

The "level" parameter is an integer from 0 to 5 and specifies the level of analysis the API should use. The algorithm will look that number of moves ahead and choose a move that leads to checkmate, or, if that's impossible, maximizes the resulting advantage in points after the specified number of moves. Level 0 will not look ahead at all and simply returns a random move.

Important note: Level 5 is experimental. It may time out, return a result worse than level 4, or return an error. All other levels should suggest a move within 10 seconds.

The suggested move comes back in a similar form as the request, with the state of the game after the suggested move specified by a single string. For the query above, the unpacked json result "jsonResult" would look something like this:

{
    prev: "rnbqkbnrpppppppp--------------------------------PPPPPPPPRNBQKBNRb1111",
    score: 0,
    level: 3,
    move: [[6, 3], [4, 3]],
    next: "rnbqkbnrpppp-ppp------------p-------------------PPPPPPPPRNBQKBNRw1111"
}

"next" in this response is the state of the game after the recommended move is made.

The response also comes with additional data: "prev" is the game state was sent in the request. "score" is the total of all white's pieces' points minus the total of all black's piece's points(So white wants to increase this number and black wants to decrease it). "level" is the number of moves ahead the algorithm looked. And "move" is the suggested move in array form. It's an array containing two subarrays, which are the beginning and ending coordinates of the piece to be moved.

For special moves (castling, en passant, and pawn promotion) the "move" array will have a third element, a string, indicating the special move:
    "castle" indicates a castle move. The coordinates will be for moving the king.
    "enPassant" indicates an en passant move. The coordinates will be for moving the capturing pawn.
    Any other character indicates a pawn promotion, and the character represents the new piece that should replace the pawn.
    Ex: [[6, 3], [7, 3], "r"] is a pawn move from [6, 3] to [7, 3] and promoting it to a white rook.

Using the API to validate a move

The API can also be used to check if a move is legal. Here's an example query:

fetch("https://airbackend.com/chessMove/api.php", {
    method: "POST",
    body: JSON.stringify({
        request: "checkMove",
        gameState: "rnbqkbnrpppppppp--------------------------------PPPPPPPPRNBQKBNRw1111",
        move: [[0, 1], [2, 2]]
    })
}).then((result) => {
    result.json().then((jsonResult) => {
        console.log(jsonResult);
    });
});

Here's what the response to the above query would be:

{
   "prev": "rnbqkbnrpppppppp--------------------------------PPPPPPPPRNBQKBNRw1111",
   "move": [[0,1],[2,2]],
   "moveValid": true
}

Use this tool to experiment with the API

fetch("https://airbackend.com/chessMove/api.php", {
    method: "POST",
    body: JSON.stringify({
        request: "",
        gameState: "",
        level: ,
        move:
    })
}).then((result) => {
    result.json().then((jsonResult) => {
        console.log(jsonResult);
    });
});

Edit the above request by changing the values below, then hit Submit to see the response.


Submit jsonResponse:

{
   "prev": "rnbqkbnrpppppppp--------------------------------PPPPPPPPRNBQKBNRw1111",
   "score": 0,
   "level": 3,
   "move": [[0,1],[2,2]],
   "next": "r-bqkbnrpppppppp--n-----------------------------PPPPPPPPRNBQKBNRb1111"
}