[Feature Request] - getGameByID

[pi0neerpat]

Howdy maintainers. Great library you've created here!

I'm wondering how I can add a getGameByID(). For example take https://www.chess.com/live/game/6508402266, get the id 6508402266, and fetch the pgn.

After searching through the chess.com API docs, it doesn't seem there is an easy way to do this without parsing through the user's history, which is not ideal. Wondering if you have any tips on how to achieve this

I can help make a PR to implement if necessary.

The closest I've gotten is using the (undocumented) api https://www.chess.com/callback/live/game/6508402266, but this doesn't return the pgn, and instead some encrypted string moveList: "mC0Kgv5QfHQBvBKBHt7MegZRdv6Evw90nDMNtAYQiq!TltXHAiRJCKEmfeTZbl0Fw2Fe2?Z9?..."

Thank you!

[cupOJoseph]

Yeah this would be super helpful. I'm also happy to write it if repo owner would merge or provide a little more info on how that could work

[andyruwruw]

Simular Requests

After looking into it, it seems like this is definitely a feature / related to other features devs have been asking for.

APISTOTELHS summed it up the best in the comments of the API docs. Chess.com's API lacks a bit of query control.

Searching through a player's monthly archives could work, but would end up being a lot of requests and searching.

Unofficial Endpoint

I think working off the unofficial endpoint is a great idea, especially if you only need the FEN.

I'd assume PGN is generated upon request, and the way chess.com deals with moves is based on how their engine is implemented. So I'm not surprised the PGN isn't included in the unofficial endpoint.

Chess.com might have some reservations about using the unofficial endpoint, given that I'm not sure that the unofficial endpoint is blocked for parallel requests. Unsure really and probably best to check with them for this particular lib.

Parsing moveList

For getting the moves from a game, I'm not seeing any other relevant requests made when going through the moves of a game. I think we're going to have to cipher that out of the movelist string.

I'm looking into that now.

The number of characters in the string correlates to how many moves were made: 2 characters (2 bytes) per move.
Game with 14 moves: mCYIkA5QnDZRDL2UoE0SdmQBmt7F (28 bytes).

My first assumption is that the bytes encode the piece moved, starting and end positions.
1st Nibble: Starting Rank
2nd Nibble: Starting File
3rd Nibble: End Rank
4th Nibble: End File

Comparing some moves shows some promising results

Opening e4 encodes to
string: mC
hex: 6D 43
binary: 0110 1101 0100 0011
decimal: 6 13 4 3

Opening d4 encodes to
string: mC
hex: 6C 42
binary: 0110 1100 0100 0010
decimal: 6 12 4 2

As you'd hope, the two later nibbles of either byte vary by 1 from row e to d.

The weird thing is you'd only need 3 bits for the row or column (0 - 8) but some of the byte's second nibble goes above 8: 0110 1101. Some bitboards for chess use 128 bits instead of 64, the right-hand board being an illegal territory, but could be used in this case to show the previous position.

I think taking a closer look at the 0x88 board might hold some promise.

Things kind of break down fast when you try other moves, however.

f1 to b5 encodes to
string: fH
hex: 66 48
binary: 0110 0110 0100 1000
decimal: 6 6 4 8

That last move was from the perspective of black, whereas the two opening moves were from my perspective as white. I would hope that doesn't have an impact but I'm unsure.

Let me know if you have any thoughts, or if you want to start a few fake games to rig move to get different values for further testing.

I'll try to reach out to chess.com to see if they can help as well.

[cupOJoseph]

Hey @andyruwruw thanks a lot for taking a look at this issue, I appreciate the thoughtful response and your time as an open source dev.

re:

Unsure really and probably best to check with them for this particular lib.

Is this someone in particular, I could ask if you know who?

Opening e4 encodes to
string: mC

This is absolutely brilliant, i never would have considered this as a way to encode the moves. If chess.com is using that to encode, then there must be a lookup table they use to do that somewhere. Maybe they can share or I can write a helper library

[andyruwruw]

I finally figured out how moveList is encoded.

I played a fake game vs. myself and mapped out each square as they are encoded in ASCII. Things were a lot simpler than I thought.

Each move is 2 characters (2 bytes).

The first character encodes where the piece started.
The second character encodes where it was moved.

The tables below show the different values of each square.

ASCII:

	a	b	c	d	e	f	g	h
8	4	5	6	7	8	9	!	?
7	W	X	Y	Z	0	1	2	3
6	O	P	Q	R	S	T	U	V
5	G	H	I	J	K	L	M	N
4	y	z	A	B	C	D	E	F
3	q	r	s	t	u	v	w	x
2	i	j	k	l	m	n	o	p
1	a	b	c	d	e	f	g	h

Hex:

	a	b	c	d	e	f	g	h
8	34	35	36	37	38	39	21	3F
7	57	58	59	5A	30	31	32	33
6	4F	50	51	52	53	54	55	56
5	47	48	49	4A	4B	4C	4D	4E
4	79	7A	41	42	43	44	45	46
3	71	72	73	74	75	76	77	78
2	69	6A	6B	6C	6D	6E	6F	70
1	61	62	63	64	65	66	67	68

Decimal:

	a	b	c	d	e	f	g	h
8	52	53	54	55	56	57	33	63
7	87	88	89	90	48	49	50	51
6	79	80	81	82	83	84	85	86
5	71	72	73	74	75	76	77	78
4	121	122	65	66	67	68	69	70
3	113	114	115	116	117	118	119	120
2	105	106	107	108	109	110	111	112
1	97	98	99	100	101	102	103	104

Guess I should have just kept things in ASCII all along!

Using the string abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ123456789!?, you can take each character from the moveList and find its index in the string. From there you can get the file and rank of the exact position.

Not quite sure if we'd want to take the move results and convert them to PGN, or leave that up to whoever is using the package. 😄

@jschiarizzi I used to work over there so I send a slack message to my old boss! No reply yet.

If either you or @pi0neerpat are interested in writing this endpoint, I'd be happy to merge it in!

[pi0neerpat]

This is flippin sweet! I'll take a look at implementing it and/or funding on gitcoin

[bmacho]

Um. It is NOT an undocumented chess.com API, but an internal tool, also it clearly violates chess.com ToS:

You agree to not use the Service to: [...]

access, tamper with, or use non-public areas of the Service, Chess.com's computer systems, or the technical delivery systems of Chess.com’s providers;

https://www.chess.com/legal/user-agreement

Also the callback link gives different result depending whether you are logged in or not.
Also it should not be available from browser, due to CORS, I believe.

[andyruwruw]

Thanks for bringing that up, I'll get it removed

[pi0neerpat]

Disagree with @bmacho but 🤷

[andyruwruw]

I'll contact someone inside Chess.com again, try to get a solid answer whether we're okay to use this endpoint. Given that this library is semi-endorsed by Chess.com, I think it'd be best if we're 100% positive we can use this or remove it.

[andyruwruw]

Heard back from Chess.com. The callbacks we used aren't intended for general use but it looks like we're clear to keep it with a few disclaimers.

Chess.com could change the endpoint without notice making it very unstable, unlike the PubAPI. We knew this, but we'll have to periodically check to ensure our function still works as intended. Best to add documentation that this endpoint should NOT be used for anything important or official.

If anyone hammers the endpoint with requests, Chess.com will give them an IP ban, so we should place a warning to use it sparingly.

He mentioned they don't have a clear statement over fair use ("since we suppose they aren't being used"), so we should add a statement about fair usage.

I'll close this when the following action items are taken care of 👍:

• Add comments on instability to documentation
• Add warnings against overuse to documentation

[andyruwruw]

We're good to go! Thanks for bringing that up @bmacho. 🙂

Changes are live in v1.1.1

[pi0neerpat]

Yay! https://niftychess.com will live on :D