It's a free online chess game focused on realtime and simplicity.
It haz a search engine, computer analysis, tournaments, forums, teams, puzzles, and a weird monitoring console. The UI is available in 72 languages thanks to the community.
Lichess is written in Scala 2.10, and relies on Play 2.2 for the routing, templating, and JSON. Pure chess logic is contained in scalachess submodule. The codebase is fully asynchronous, making heavy use of Scala Futures and Akka 2 actors. Lichess talks to Stockfish 4 using a FSM Actor to handle AI moves and analysis. It uses MongoDB 2.4 to store about 20 million games, which are indexed by elasticsearch 0.90. HTTP requests and websocket connections are proxied by nginx 1.4. New client-side features are written in ClojureScript.
Join us on #lichess IRC channel on freenode for more info. See the roadmap on https://etherpad.mozilla.org/ep/pad/view/ro.3bIwxJwTQYW/latest.
If you want to add a live chess section to your website, you are welcome to embed lichess. It's very easy.
This project source code is open for other developers to have an example of non-trivial scala/play2/mongodb application. You're welcome to reuse as much code as you want for your projects, and to get inspired by the solutions I propose to many common web development problems. But please don't just create a public lichess clone. Instead, just embed lichess using an <iframe>.
Also note that if I provide the source code, I do not offer support for your lichess instance. I will probably ignore any question about lichess installation and runtime issues.
Feel free to use lichess API in your applications and websites.
If the resource you need is not available yet, drop me an email at [email protected], and we'll discuss it.
> curl http:https://en.lichess.org/api/user/thibault
{
"username": "thibault",
"url": "http:https://lichess.org/@/thibault", // profile url
"rating": 1503, // global Glicko2 rating
"progress": 36, // rating change over the last ten games
"online": true, // is the player currently using lichess?
"playing": "http:https://lichess.org/abcdefgh", // game being played, if any
"engine": false // true if the user is known to use a chess engine
}Example usage with JSONP:
$.ajax({
url:'http:https://en.lichess.org/api/user/thibault',
dataType:'jsonp',
jsonp:'callback',
success: function(data) {
// data is a javascript object, do something with it!
console.debug(JSON.stringify(data));
}
});All parameters are optional.
| name | type | default | description |
|---|---|---|---|
| team | string | - | filter users by team |
| nb | int | 10 | maximum number of users to return |
> curl http:https://en.lichess.org/api/user?team=coders&nb=100
{
"list": [
{
"username": "thibault",
"url": "http:https://lichess.org/@/thibault", // profile url
"rating": 1503, // global Glicko2 rating
"progress": 36, // rating change over the last ten games
"online": true, // is the player currently using lichess?
"engine": false // true if the user is known to use a chess engine
},
... // other users
]
}Example usage with JSONP:
$.ajax({
url:'http:https://en.lichess.org/api/user',
data: {
team: 'coders',
nb: 100
},
dataType:'jsonp',
jsonp:'callback',
success: function(data) {
// data is a javascript object, do something with it!
console.debug(JSON.stringify(data.list));
}
});Games are returned by descendant chronological order. All parameters are optional.
| name | type | default | description |
|---|---|---|---|
| username | string | - | filter games by user |
| rated | 1 or 0 | - | filter rated or casual games |
| nb | int | 10 | maximum number of games to return |
| token | string | - | security token (unlocks secret game data) |
> curl http:https://en.lichess.org/api/game?username=thibault&rated=1&nb=10
{
"list": [
{
"id": "x2kpaixn",
"rated": false,
"status": "mate",
"clock":{ // all clock values are expressed in seconds
"limit": 300,
"increment": 8,
"totalTime": 540 // evaluation of the game duration = limit + 30 * increment
},
"timestamp": 1389100907239,
"turns": 44,
"url": "http:https://lichess.org/x2kpaixn",
"winner": "black",
"players": {
"white": {
"userId": "thibault"
"rating": 1642,
"analysis": {
"blunder": 1,
"inaccuracy": 0,
"mistake": 2
}
},
"black": ... // other player
}
},
{
... // other game
}
]
}(1) All game statuses: https://github.com/ornicar/scalachess/blob/master/src/main/scala/Status.scala#L16-L25
This API requires a secret token to work. Analysis are returned by descendant chronological order. All parameters are optional.
| name | type | default | description |
|---|---|---|---|
| token | string | - | security token |
| nb | int | 10 | maximum number of analysis to return |
> curl http:https://en.lichess.org/api/analysis?nb=10
{
"list": [
{
"analysis": [
{
"eval": -26, // board evaluation in centipawns
"move": "e4",
"ply": 1
},
{
"eval": -8,
"move": "b5",
"ply": 2
},
{
"comment": "(-0.08 → -0.66) Inaccuracy. The best move was c4.",
"eval": -66,
"move": "Nfe3",
"ply": 3,
"variation": "c4 bxc4 Nfe3 c5 Qf1 f6 Rxc4 Bb7 b4 Ba6"
},
// ... more moves
],
"game": {
// similar to the game API format, see above
},
"uci": "e2e4 e7e5 d2d4 e5d4 g1f3 g8f6" // UCI compatible game moves
}
]
}> curl http:https://en.lichess.org/api/puzzle/23045
{
"id": 16177,
"url": "http:https://lichess.org/training/16177", // URL of the puzzle
"color": "black", // color of the player
"position": "6NK/5k2/2r5/2n3PP/8/8/8/8 w - - 7 39", // FEN initial position
"solution": ["c6h6", "g5h6", "c5e6", "h8h7", "e6g5",
"h7h8", "f7f8", "h6h7", "g5f7"], // solution moves
"rating": 1799 // puzzle glicko2 rating
}> curl http:https://en.lichess.org/api/puzzle/daily
{
"id": 16177,
"url": "http:https://lichess.org/training/16177", // URL of the puzzle
"color": "black", // color of the player
"position": "6NK/5k2/2r5/2n3PP/8/8/8/8 w - - 7 39", // FEN initial position
"solution": ["c6h6", "g5h6", "c5e6", "h8h7", "e6g5",
"h7h8", "f7f8", "h6h7", "g5f7"], // solution moves
"rating": 1799 // puzzle glicko2 rating
}Lichess streams all played moves on http:https://en.lichess.org/stream using chunked HTTP response and the following format:
ChunkSize # size of the next chunk, in hexadecimal
GameId IpAddress # actual chunk of data> echo "GET /stream HTTP/1.1\nHost: en.lichess.org\n" | netcat en.lichess.org 80
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 16 Oct 2013 20:01:11 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
1a
4om0thb7 91.121.7.111
1b
o2eg9xu3 89.77.165.159
18
g3ag6xm6 83.149.8.9
1b
hl0zbh3g 109.237.157.8
1a
g3ag6xm6 91.121.7.111
1c
tj2u3hus 117.199.47.140By comparing game IDs, you can guess who plays against who.
See the lichess Thanks page