https://github.com/ryanjamescaldwell/chess_api
chess_api is a Ruby gem that wraps the Chess.com API.
https://github.com/ryanjamescaldwell/chess_api
api-wrapper chess ruby
Last synced: 12 months ago
JSON representation
chess_api is a Ruby gem that wraps the Chess.com API.
- Host: GitHub
- URL: https://github.com/ryanjamescaldwell/chess_api
- Owner: RyanJamesCaldwell
- License: mit
- Created: 2021-08-30T02:04:44.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2023-07-04T14:22:04.000Z (almost 3 years ago)
- Last Synced: 2025-06-02T14:58:46.079Z (about 1 year ago)
- Topics: api-wrapper, chess, ruby
- Language: Ruby
- Homepage:
- Size: 64.5 KB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ChessApi
[](https://badge.fury.io/rb/chess_api)
[](https://github.com/testdouble/standard)
`chess_api` is a gem that wraps [Chess.com's Published-Data API](https://www.chess.com/news/view/published-data-api).
## Installation
### Codespaces
[](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=401188229)
### Add to an existing project
Add this line to your application's Gemfile:
```ruby
gem 'chess_api'
```
And then execute:
$ bundle install
Or install it yourself as:
$ gem install chess_api
## Usage
To interact with the `ChessApi`, you'll first need to create a client object. You have the option of specifying a [Faraday adapter](https://lostisland.github.io/faraday/adapters/).
```ruby
client = ChessApi::Client.new
# or
client = ChessApi::Client.new(adapter: your_adapter_here)
```
From there, you'll be able to perform several operations:
### Fetch a player on Chess.com by username
```ruby
irb(main):018:0> player = client.player.retrieve(username: "GothamChess")
=>
# player.username
=> "gothamchess"
irb(main):020:0> player.title
=> "IM"
irb(main):021:0> player.is_streamer
=> true
irb(main):022:0> player.twitch_url
=> "https://twitch.tv/GothamChess"
```
As you can see in the example above, you can access the fields returned by the Chess.com API through standard Ruby method syntax.
### Fetching a list of players with a particular title on Chess.com
```ruby
irb(main):001:0> client.titled_player.with_title(title_abbreviation: "WGM")
=>
#>,
#>,
#>,
#>,
...
]
```
### Fetching a player's online status on Chess.com
```ruby
irb(main):001:0> client.player.online_status(username: "hikaru")
=> "offline"
irb(main):002:0> client.player.online_status(username: "ryanjcaldwell")
=> "online"
```
### Fetching the clubs that a player belongs to on Chess.com
```ruby
irb(main):001:0> clubs = client.player.clubs(username: "GothamChess")
=>
# clubs.data.map { |club| [club.name, club.joined] }
=>
[["Chess.comTV", 1533262149],
["Hikaru Nakamura Fan Club", 1547248727],
["Chess.com Beta", 1572489771],
["PRO Chess League", 1547048660],
["Streamers", 1533671931],
["4 Player Chess", 1533746676],
["Gotham's Mob", 1528247350],
["Arena Kings Championship Season 5", 1575824630],
["Marshall Chess Club Official - Match Team", 1587681476],
["Fiona's Fight Club", 1616428995]]
```
### Fetching the monthly game archive links for a player on Chess.com
```ruby
irb(main):001:0> result = client.monthly_game_archive.list(username: "ryanjcaldwell")
=>
# result.data.first.url
=> "https://api.chess.com/pub/player/ryanjcaldwell/games/2019/03"
```
### Fetching the Daily Puzzle from Chess.com
```ruby
irb(main):001:0> daily_puzzle = client.daily_puzzle.retrieve
=>
# daily_puzzle.title
=> "Disconnecting Connection"
irb(main):003:0> daily_puzzle.pgn
=> "[Result \"*\"]\r\n[FEN \"3rb3/5pk1/2n1pn1p/rp3Pp1/6P1/1P2B2P/2R3BK/R3N3 w - - 0 1\"]\r\n\r\n1.Rxa5 Nxa5 2.Bb6 Rd1 3.Bxa5 *"
irb(main):004:0> daily_puzzle.image
=> "https://www.chess.com/dynboard?fen=3rb3/5pk1/2n1pn1p/rp3Pp1/6P1/1P2B2P/2R3BK/R3N3%20w%20-%20-%200%201&size=2"
```
### Fetching a random Daily Puzzle from Chess.com
```ruby
irb(main):001:0> random_daily_puzzle = client.daily_puzzle.random
=>
# random_daily_puzzle.publish_time
=> 1306047600
irb(main):003:0> random_daily_puzzle.pgn
=> "[Date \"????.??.??\"]\r\n[Result \"*\"]\r\n[FEN \"1B6/1p4Rp/p4kp1/8/8/8/Pr4PP/6K1 b - - 0 1\"]\r\n\r\n1...Rb1+ 2. Kf2 Kxg7\r\n*"
irb(main):004:0> random_daily_puzzle.url
=> "https://www.chess.com/forum/view/daily-puzzles/5222011---eluding-danger"
```
### Fetching streamers on Chess.com
```ruby
irb(main):001:0> streamers = client.streamer.list
=>
# streamers.data.first
=>
#>
irb(main):003:1* streamers.data.first(3).map do |streamer|
irb(main):004:1* [streamer.url, streamer.twitch_url, streamer.is_live]
irb(main):005:0> end
=>
[["https://www.chess.com/member/QTCinderella", "https://twitch.tv/QTCinderella", true],
["https://www.chess.com/member/GMKrikor", "https://twitch.tv/gmkrikor", true],
["https://www.chess.com/member/jppeixoto29", "https://twitch.tv/jppeixoto29", true]]
```
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/RyanJamesCaldwell/chess_api.
## License
The gem is available as open source under the terms of the MIT License.