Chess historical game API to get game details of millions of chess games.

API End Points

The end point for connecting : If you subscribe directly from us use this endpoint.

https://chess.rest/

Get a random game

   GET /gameref/random

The above call will produce a result like below

{
  "success": {
    "total": 1
  },
  "contents": {
    "games": [
      {
        "id": "CiIAIiZ4JzNMTd_ACJ8NMgeF",
        "player_white": "Shahade, Michael",
        "player_black": "Erdal, Gary",
        "result": "1-0"
      }
    ]
  },
  "copyright": {
    "url": "chess.rest",
    "year": "2024"
  }
}

Get the game details for a single game

   GET /gameref/game
                ?id=<game_id>

The above call will produce a result like below

{
    "success": {
        "total": "1"
    },
    "contents": {
        "game": {
            "id": "__bxTnllmGC3Xo2nNsop5QeF",
            "event": "?",
            "site": "?",
            "game_date": "1999-00-00",
            "game_year": "1999",
            "round": null,
            "player_white": "Krahl, Wolfgang",
            "player_black": "Gerwert, Thomas",
            "result": "0-1",
            "player_whiteelo": null,
            "player_blackelo": null,
            "player_whiteuscf": null,
            "player_blackuscf": null,
            "player_whitena": null,
            "player_blackna": null,
            "player_whitetype": null,
            "player_blacktype": null,
            "event_date": "1999-00-00",
            "event_sponsor": null,
            "event_section": null,
            "event_stage": null,
            "event_board": null,
            "open_opening": null,
            "open_variation": null,
            "open_subvariation": null,
            "open_eco": "A20",
            "open_nic": null,
            "time_time": null,
            "time_utctime": null,
            "time_utcdate": null,
            "time_timecontrol": null,
            "startpos_setup": null,
            "startpos_fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
            "end_termination": null,
            "annotator": null,
            "mode": null,
            "plycount": "42"
        }
    }
}
    

Game Search

Search the chess.gallery database based on year played, game result, player names etc.

  GET /gameref/game/search?
                 result=<result> // 1-0 for white win, 0-1 for black win 1/2-1/2 for a draw
               &year=<year> // year game was played
               &player1_name=<name> // player name
               &player1_color=<color> // white/black side
               &player2_name=<name> // player name
               &player2_color=<color> // white/black side

The above call should produce something like the following

{
  "success": {
    "total": 1
  },
  "contents": {
    "games": [
      {
        "id": "KdDZyMnyQg5BEyjEsQQ1iQeF",
        "player_white": "Napoleon, Bonaparte",
        "player_black": "Remusat, Claire",
        "result": "1-0"
      },
      {
        "id": "V7EdNhoQQave_3DUNOdWuAeF",
        "player_white": "Heltay",
        "player_black": "Janniy",
        "result": "0-1"
      },
      {
        "id": "wdp8dNlgiAEOUtfLx_fszweF",
        "player_white": "Saint, Amant Pierre C",
        "player_black": "Walker, George",
        "result": "1-0"
      },
      {
        "id": "dC6aue5a9XIejwNnxQwgWAeF",
        "player_white": "Saint, Amant Pierre C",
        "player_black": "Fraser, W.",
        "result": "1-0"
      },
      {
        "id": "5l8nE3R8eu0vmN1a1Y8q_AeF",
        "player_white": "Walker, George",
        "player_black": "Saint, Amant Pierre C",
        "result": "1-0"
      },
      {
        "id": "t7dK2pUp74vIT5qyvqoEjQeF",
        "player_white": "Walker, George",
        "player_black": "Saint, Amant Pierre C",
        "result": "0-1"
      },
      {
        "id": "hJIyCAVFhIYNauhoKs1NuQeF",
        "player_white": "Jaenisch, Carl F A",
        "player_black": "Von der Lasa Tassilo",
        "result": "1/2-1/2"
      },
      {
        "id": "kbUGSusdMobBZKhM4DWwJAeF",
        "player_white": "Jaenisch, Carl F A",
        "player_black": "Von der Lasa Tassilo",
        "result": "1-0"
      },
      {
        "id": "sBapBIW7ldUBnXPH4JT4RgeF",
        "player_white": "Staunton, Howard",
        "player_black": "Saint, Amant Pierre C",
        "result": "1/2-1/2"
      },
      {
        "id": "ZaG2e42UV07UlfGuA9RG2QeF",
        "player_white": "Staunton, Howard",
        "player_black": "Saint, Amant Pierre C",
        "result": "1-0"
      },
      {
        "id": "6Hj8ePNDUuyL43Ffbb5xmQeF",
        "player_white": "Staunton, Howard",
        "player_black": "Saint, Amant Pierre C",
        "result": "1-0"
      },
      {
        "id": "5M60LRK1NQcE44mXMdVV9QeF",
        "player_white": "Staunton, Howard",
        "player_black": "Saint, Amant Pierre C",
        "result": "1-0"
      },
      {
        "id": "LN0Qh4tOL6kmGEb3xHntaweF",
        "player_white": "Staunton, Howard",
        "player_black": "Saint, Amant Pierre C",
        "result": "0-1"
      },
      {
        "id": "QdIYpjMwv_xNfH1IRlySVweF",
        "player_white": "Kieseritzky, Lionel",
        "player_black": "Saint, Amant Pierre C",
        "result": "1/2-1/2"
      },
      {
        "id": "G9vwQcGQyUWbzCHltEQMBweF",
        "player_white": "Staunton, Howard",
        "player_black": "Saint, Amant Pierre C",
        "result": "1-0"
      }
    ],
    "links": {
      "self": "https://chess.rest/gameref/game/search?year=1994&api_key=R3U_8h9b_zBd3ABwWZq0ZweF&page=1",
      "next": "https://chess.rest/gameref/game/search?year=1994&api_key=R3U_8h9b_zBd3ABwWZq0ZweF&page=2",
      "prev": null
    },
    "meta": {
      "totalPages": 365639,
      "totalItems": 5484572,
      "itemsOnThisPage": 15,
      "currentPage": 1
    }
  },
  "copyright": {
    "url": "chess.rest",
    "year": "2024"
  }
}

Get the PGN (Portable Game Notation) of the game

  GET /gameref/game/pgn
               ?id=<game_id>

The result will look like below

{
  "success": {
    "total": 1
  },
  "contents": {
    "pgn": "[Event \"?\"]\r\n[Site \"?\"]\r\n[Date \"1994.??.??\"]\r\n[Round \"?\"]\r\n[White \"Shahade, Michael\"]\r\n[Black \"Erdal, Gary\"]\r\n[Result \"1-0\"]\r\n[WhiteElo \"2285\"]\r\n[ECO \"A21\"]\r\n[EventDate \"1994.??.??\"]\r\n[PlyCount \"93\"]\r\n\r\n1.c4 e5 2.Nc3 f5 3.d4 d6 4.dxe5 dxe5 5.Qxd8+ Kxd8 6.Bg5+ Be7 7.O-O-O+ Bd7 \r\n8.Nf3 Nc6 9.Nd5 h6 10.Bxe7+ Ngxe7 11.e3 e4 12.Nd4 Ne5 13.Nf4 g5 14.Nfe6+ \r\nKc8 15.h4 g4 16.Be2 b6 17.c5 a5 18.Kb1 Kb7 19.Rc1 Nd5 20.Nf4 Nxf4 21.exf4 \r\nNc6 22.Rhd1 Rhd8 23.cxb6 cxb6 24.Nb5 Be6 25.Nd6+ Kc7 26.Bb5 Rxd6 27.Rxd6 \r\nKxd6 28.Rxc6+ Kd5 29.Rxb6 Rc8 30.b3 Bg8 31.Bd7 Rc5 32.Bxf5 h5 33.Rg6 Kd4 \r\n34.Rd6+ Rd5 35.Rxd5+ Kxd5 36.Bg6 Kd4 37.Bxh5 Bh7 38.Kc1 Bf5 39.Kd2 Bd7 40.\r\ng3 Bf5 41.Bf7 Bd7 42.h5 e3+ 43.fxe3+ Ke4 44.Ke2 Kf5 45.h6 Kf6 46.h7 Kg7 \r\n47.Bg6 1-0"
  },
  "copyright": {
    "url": "chess.rest",
    "year": "2024"
  }
}

Player Search

  GET /gameref/player/search
               ?name=<name>

The result will like below

{
  "success": {
    "total": 1
  },
  "contents": {
    "players": [
      {
        "id": "iUelKmZYhjOo5FuGLf9rwAeF",
        "name": " Kristian Dimitrov"
      },
      {
        "id": "w_IH_eeVousxBhAO_sMPRQeF",
        "name": " Kristian Djakov"
      },
      {
        "id": "eOk6zboKHirS1N9zgU_nCQeF",
        "name": " Kristian Erdmann"
      },
      {
        "id": "VPeK5LfgI8uPMsAN8M4dSQeF",
        "name": " Kristian Eriksson"
      },
      {
        "id": "5WtPb9zMeXdo_fMUDu0tPAeF",
        "name": " Kristian Espeland"
      },
      {
        "id": "YbgZtw_1qDC2EKIZMvjFmgeF",
        "name": " Kristian Evertsson"
      },
      {
        "id": "RRP2kwmE1dZYCQFhSt6_MQeF",
        "name": " Peter Kristian Finck"
      },
      {
        "id": "0XitlDWW3o6D9SFRIBd_XgeF",
        "name": " SAULO KRISTIAN PASC FRANCO"
      },
      {
        "id": "B0zaqcTTGFA8a6gr7nXRZgeF",
        "name": " Kristian Pade Frederiksen"
      },
      {
        "id": "aubter5T8DYTGfbKlGXX9AeF",
        "name": " Kristian Gogora"
      },
      {
        "id": "Brs_Jq_0G6fyPsh_nCRsEAeF",
        "name": " Kristian Graversgaard"
      },
      {
        "id": "PDWYH5E0si33jw76Y5z2aAeF",
        "name": " Jon Kristian Haarr"
      },
      {
        "id": "_BEOHyN7HNBc3SFtZ5QHJAeF",
        "name": " Kristian Haborak"
      },
      {
        "id": "XqI_Esq8bsnnzSl1V3iIJgeF",
        "name": " Olav Kristian Hageberg"
      },
      {
        "id": "0a7t1L65qDNETEDdgKA4JAeF",
        "name": " Kristian Hammervik"
      }
    ],
    "links": {
      "self": "https://chess.rest/gameref/player/search?name=Kristian&page=2",
      "next": "http://chess.rest/gameref/player/search?name=Kristian&page=3",
      "prev": "http://chess.rest/gameref/player/search?name=Kristian&page=1"
    },
    "meta": {
      "totalPages": 9,
      "totalItems": 123,
      "itemsOnThisPage": 15,
      "currentPage": 2
    }
  }
}

Ratelimiting

Some of our API calls may be public(requires free API key) , while others requires paid subscription. To maintain our serice levels both public and private API endpoints are ratelimited. Please consult your specific plan that you subscribed to for the rate limit details.

Authentication

Currently we support API Key based authentication. Please set your Autorization Bearer request header with value of your API key. Alternatively you can also pass api_key= as a request parameter, though we strongly discourage this mode of passing the key, since it will allow others to see your key.

In curl this would mean sending the Authorization header like below.

            
 curl -i <url> -H "Authorization: Bearer <api_key>"
            
            

If you are using PHP.

            
$authorization = "Authorization: Bearer <api_key>";
$ch = curl_init('<url>'); // Initialise cURL
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json' , $authorization ));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); // OR GET
$result = curl_exec($ch);
curl_close($ch);
            
            

In javascript you can use headers key to add the authorization header

            
$.ajax({
   url: '<url>'
   type: 'GET',
   contentType: 'application/json'
   headers: {
      'Authorization': 'Bearer <api_key>'
   },
   success: function (result) {
       // CallBack(result);
   },
   error: function (error) {

   }
});