Examples/help with using the Lichess API?

Hi all,

I'm working with a student at my home university to set up a chess research study and we could use a little help figuring out how to get started using the Lichess API. If any of you have some examples of stuff you've set up using it, or pointers to resources for helping two people with limited experience using any API get their feet under them, we'd be grateful! Direct messages or replies here would both be welcome.

Hopefully this all may culminate in some fun new "Science of Chess" essays, so stay tuned!

Yes, examples from which learning can happen from little perturbation experiements, from which to get some bearings in how it works. As the API doc itself, while input output schemes, are assuming some knowledge. There are github examples, I don't recall from which Lichess public text it was. Could be a Lichess blog (by lichess).

Here are 32 sets of examples github.com/search?q=lichess.org%2Fapi&type=repositories

There are also didactic-intended ones by Lichess itself. I think. Maybe like 4 of them. I might have dreamed.

32 is nice. But they might not be intended that way, not, all of them. Although it is nice to get a search string example about GitHub, being approachable that way.

About the few examples I am reminiscing of:

It is difficult to put oneself in another professional groove shoes, and revise own expert knowledge assumptions. So if the author of the examples at least had some teaching in mind in the choice of examples, there might be more clues for incoming non-expert. Sometimes expertise goes against communication abilities, if left unchecked.

Hiya!

The Lichess API is documented at lichess.org/api
The documentation project is open source and can be found at github.com/lichess-org/api
The repository contains example code using the API,
for instance this web application - lichess-org.github.io/api-demo/

In your post you say "to set up a chess research study" - is there something specific you have in mind?

I'd recommend reading through the API documentation to get a feeling for what operations are possible to perform with the API.
All of the actions are performed by sending HTTP requests to the Lichess servers.

So for a developer to write an application which uses the API,
they would choose some programming language and then write code which makes HTTP requests according to the Lichess API documentation.

To make things easier for users of the API,
there already exists some language specific libraries which developers can use.

One of the most common libraries is the Python library called "berserk".
Its documentation can be found at lichess-org.github.io/berserk/

So if you know the Python programming langauge,
you could use the existing "berserk" module and and call python methods to interact with the API.
This means that you don't need to study the HTTP API documentation in detail, but can rather study which Python methods are available in the "berserk" module.

(Or if you want to "do things from scratch", you could use a Python HTTP client such as the "requests" module,
and send HTTP requests with proper headers and request bodies and parse the response headers and body.)

One source of research-related projects that I can think of,
is the last section on the web page which hosts all of the rated games ever played on the Lichess web site - at database.lichess.org/#related-projects
They are not really "help" of _how_ to use the API, but rather examples of what can be achieved from using the API,
and some (all?) projects links to their source code.

If you have some specific question,
I'd be happy to try to help answering.
Open questions are tricky to answer. :)

If you are a Discord user, you could consider checking out the Lichess Discord server.
It has a programming seciton, and a channel for #lichess-api-support - discord.gg/lichess

Chess on!

Many thanks! I've got a few replies inserted below...

@tors42 said in #5:
> In your post you say "to set up a chess research study" - is there something specific you have in mind?

Yup - the tl;dr version is that we'd like to select some puzzles (we'll have specific lichess IDs for these) to present via a browser interface so solvers can work on them in sequence. We'd like to be able to record what moves they try and timestamps of attempted moves if possible.

> One of the most common libraries is the Python library called "berserk".
> Its documentation can be found at lichess-org.github.io/berserk/
>
> So if you know the Python programming langauge,
> you could use the existing "berserk" module and and call python methods to interact with the API.
> This means that you don't need to study the HTTP API documentation in detail, but can rather study which Python methods are available in the "berserk" module.
>

This sounds very helpful - I have some Python and will go check this out.

> If you have some specific question,
> I'd be happy to try to help answering.
> Open questions are tricky to answer. :)

Thank you again for taking the time to respond! I may follow up with you once we check out some of these resources and make a few attempts!

>
> If you are a Discord user, you could consider checking out the Lichess Discord server.
> It has a programming seciton, and a channel for #lichess-api-support - discord.gg/lichess
>
> Chess on!

@tors42 said in #5:
>
> If you have some specific question,
> I'd be happy to try to help answering.
> Open questions are tricky to answer. :)

This not being in the feedback category, it might not suffer from the helpdesk syndrome, that only the op question is being answered.
I find this a great offer, even if taken as you=op. That last bit, I agree wholeheartedly and in anything one can put "research" word attached. So, why I quote this. I am not going to ask soon. maybe ever. But it is good to hear.

@NDpatzer said in #6:
> We'd like to be able to record what moves they try and timestamps of attempted moves if possible.

Great. The foresight problem. Kudos. (eye trackers with that?).
I play correspondance so I can also self-observe back the thinking not recorded. Hindisght discovery (and in your case observer science) can go to that problem too. Not just the errors committed, but what went on in the foresight thinking (e.g. plan, or even good moves not chosen, ooops, that is not for puzzles, but same target question, what is the thinking before the decision, move not yet done. I would be curious about the experiemental design, even if still in mind bubbles stages.
Bullet points can do (I have imagination and they can be good basis to ask further questions, or just think on with own resources).

To lichess, just now, this:
Also, I wish lichess would let use do the same.. In puzzles, now I micromanage and same as html nameless filenames, so I also save the urls as file for the chronology of the filesystem. Have a way to personally pipe to private studies the full tactical puzzle experience.

Thanks op for raising this curiosity on the cognitive science side. I hope Lichess does care about that too. Inbox is fine for the research design reasoning, if need sound board of the possible active kind (and enthusiastic, you can moderate me, don,t worry).