Beginner concept question about OGS API

[jabgo25]

Hello,

A hobby project of mine is an extravagant SGF viewer. Then I see that the webpage does not require login. That gave me the idea to provide an input field for a gameid and then start to watch taht OGS game in my viewer.

I saw socketio is used and something about move for making a move and a callback for receiving a move.

Q1: Can I use the API (only watching games) without doing the authentication ?

Q2a: How is the logic, will I receive a chain of on move callbacks, that is both for black and white’s moves ?

Q2b: What is the general concept, because I saw that png download and sgf download is possible. Maybe it is that every move I get the full SGF ? Or that it is not possible to get a move alone every event it is played.

Cheers.

[_KoBa]

Oh that sounds like an interesting project! I’m not an expert with api, but can you just fetch the moves from https://online-go.com/api/v1/games/GAME-ID-GOES-HERE/sgf

[benjito]

OGS Scripting Tips (2025)

I’ve been doing some client coding lately, and wanted to share some tips for anyone who wants to try writing their own client code or script. Servers When interacting with OGS, you will mainly interact with the Django server (https://online-go.com/api/...) and the websocket (wss://online-go.com/ws). You may also come across the termination API (https://online-go.com/termination-api) and the AI server (https://ai.online-go.com, wss://ai.online-go.com/) Since there are many different servers, y…

[jabgo25]

Oh, thank you for the hint. So treat the game like downloading an finished SGF record. That is a possible solution

Somehow I feel it a bit waste of resources for a live game, because am I going to poll the SGF every 5 seconds from the server and also the client would need to rebuild the full Gametree each poll.

[benjito]

@jabgo25

Somehow I feel it a bit waste of resources for a live game, because am I going to poll the SGF every 5 seconds from the server and also the client would need to rebuild the full Gametree each poll.

You’re right, polling would be ineffiecient and unnecessary. You can watch for move messages.

@jabgo25

Q1: Can I use the API (only watching games) without doing the authentication ?

I believe auth isn’t necessary for watching games. I haven’t tried it, but it must work since you can watch fames without logging in.

@jabgo25

Q2a: How is the logic, will I receive a chain of on move callbacks, that is both for black and white’s moves ?

Yes, a move event is sent over websocket for each move.

[jabgo25]

I am at your minimal python example and try to alter it for just printing out the moves for a given game.

I removed the auth lines but got at

overview = session.get(f"{server_url}/api/v1/ui/overview").json()`

{‘error’: ‘You must be logged in to access this endpoint’}

I have no idea how to tell the server “this gameid I want to get updates”

Just printing out the messages that the client receives on the websocket makes the socket close after 30seconds and only send one kind of config/info message. Sending all game events to all connected clients also sound like not efficient.

sorry that I am still lost. I can say I am quite excited because the live viewer functionality seems to be very much into reach.

[jabgo25]

I can keep the connection alive by

ws.send(json.dumps(['net/ping','client':time.time(),'drift':0,'latency':0}]))`

But eventhough I send (game_id was an int number, or string):

ws.send(json.dumps(['game/connect', {'game_id': game_id}]))

there only comes the pong in the websocket when doing ws.recv()

Any comment ?

[Jon_Ko]

Did you check what your browser does when you watch a game on OGS (without being logged in)?

[jabgo25]

Having logged in with minimal python example it works. I get the game/xxx/move messages, latency, clock etc.

But even with being logged in with the browser, I don’t see these messages in the web developer tools. Or can understand how the web client does its magic.

On top now I have the question, whether I derive the player for the move simply by the odd and even move number.

[Jon_Ko]

In Firefox I open a game, then open the dev tools network tab and select WS, then I reload the tab showing the game. Then I click through the GET requests in the list and look at their response tab. There are all the messages:

Even though I wasn’t logged my browser sent some authentication message via the WS with a jwt. So it seems that even anonymous users have such to do that.

[jabgo25]

not sure. My guess would be, the browser remembered an old session.

But yes that view I have expected. Thank you for showing it.

[Jon_Ko]

Good point, I did the same in private/incognito mode and there the browser sends an empty jwt:

[jabgo25]

For completeness the https://online-go.com/termination-api/game/GAME_ID and also very much the https://online-go.com/termination-api/game/GAME_ID/state is sufficient for my needs. By polling every few seconds the live speed of fast games is not reflected, but for 90% of the games I watch it is sufficient.

Fun detail, my client and OGS webpage don’t agree on the board orientation/mirroring

[jabgo25]

Thank you Jon_Ko you solved the unauthenticated detail, now also the websocket works.