lichess-go-sdk

module
v0.0.0-...-9f2144d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 11, 2022 License: AGPL-3.0

README

Go API client for the lichess public API (https://lichess.org/api)

Introduction

Welcome to the reference for the Lichess API! Lichess is free/libre, open-source chess server powered by volunteers and donations.

Endpoint

All requests go to https://lichess.org (unless otherwise specified).

Clients

Rate limiting

All requests are rate limited using various strategies, to ensure the API remains responsive for everyone. Only make one request at a time. If you receive an HTTP response with a 429 status, please wait a full minute before resuming API usage.

Streaming with ND-JSON

Some API endpoints stream their responses as Newline Delimited JSON a.k.a. nd-json, with one JSON object per line.

Here's a JavaScript utility function to help reading NDJSON streamed responses.

Overview

This API client was generated by the OpenAPI Generator project. By using the OpenAPI-spec from a remote server, you can easily generate an API client.

  • API version: 2.0.0
  • Package version: 1.0.0
  • Build package: org.openapitools.codegen.languages.GoClientCodegen For more information, please visit https://lichess.org/api

Installation

Install the following dependencies:

go get github.com/stretchr/testify/assert
go get golang.org/x/oauth2
go get golang.org/x/net/context

Put the package under your project folder and add the following in import:

import lichess "github.com/mikeb26/lichess-go-sdk/openapi"

To use a proxy, set the environment variable HTTP_PROXY:

os.Setenv("HTTP_PROXY", "http://proxy_name:proxy_port")

Configuration of Server URL

Default configuration comes with Servers field that contains server objects as defined in the OpenAPI specification.

Select Server Configuration

For using other server than the one defined on index 0 set context value sw.ContextServerIndex of type int.

ctx := context.WithValue(context.Background(), openapi.ContextServerIndex, 1)
Templated Server URL

Templated server URL is formatted using default variables from configuration or from context value sw.ContextServerVariables of type map[string]string.

ctx := context.WithValue(context.Background(), openapi.ContextServerVariables, map[string]string{
	"basePath": "v2",
})

Note, enum values are always validated and all unused variables are silently ignored.

URLs Configuration per Operation

Each operation can use different server URL defined using OperationServers map in the Configuration. An operation is uniquely identified by "{classname}Service.{nickname}" string. Similar rules for overriding default operation server index and variables applies by using sw.ContextOperationServerIndices and sw.ContextOperationServerVariables context maps.

ctx := context.WithValue(context.Background(), openapi.ContextOperationServerIndices, map[string]int{
	"{classname}Service.{nickname}": 2,
})
ctx = context.WithValue(context.Background(), openapi.ContextOperationServerVariables, map[string]map[string]string{
	"{classname}Service.{nickname}": {
		"port": "8443",
	},
})

Documentation for API Endpoints

All URIs are relative to https://lichess.org

Class Method HTTP request Description
AccountApi Account Get /api/account/preferences Get my preferences
AccountApi AccountEmail Get /api/account/email Get my email address
AccountApi AccountKid Get /api/account/kid Get my kid mode status
AccountApi AccountKidPost Post /api/account/kid Set my kid mode status
AccountApi AccountMe Get /api/account Get my profile
AnalysisApi ApiCloudEval Get /api/cloud-eval Get cloud evaluation of a position.
ArenaTournamentsApi ApiTeamArena Get /api/team/{teamId}/arena Get team Arena tournaments
ArenaTournamentsApi ApiTournament Get /api/tournament Get current tournaments
ArenaTournamentsApi ApiTournamentJoin Post /api/tournament/{id}/join Join an Arena tournament
ArenaTournamentsApi ApiTournamentPost Post /api/tournament Create a new Arena tournament
ArenaTournamentsApi ApiTournamentTeamBattlePost Post /api/tournament/team-battle/{id} Update a team battle
ArenaTournamentsApi ApiTournamentTerminate Post /api/tournament/{id}/terminate Terminate an Arena tournament
ArenaTournamentsApi ApiTournamentUpdate Post /api/tournament/{id} Update an Arena tournament
ArenaTournamentsApi ApiTournamentWithdraw Post /api/tournament/{id}/withdraw Pause or leave an Arena tournament
ArenaTournamentsApi ApiUserNameTournamentCreated Get /api/user/{username}/tournament/created Get tournaments created by a user
ArenaTournamentsApi GamesByTournament Get /api/tournament/{id}/games Export games of an Arena tournament
ArenaTournamentsApi ResultsByTournament Get /api/tournament/{id}/results Get results of an Arena tournament
ArenaTournamentsApi TeamsByTournament Get /api/tournament/{id}/teams Get team standing of a team battle
ArenaTournamentsApi Tournament Get /api/tournament/{id} Get info about an Arena tournament
BoardApi ApiBoardSeek Post /api/board/seek Create a seek
BoardApi ApiStreamEvent Get /api/stream/event Stream incoming events
BoardApi BoardGameAbort Post /api/board/game/{gameId}/abort Abort a game
BoardApi BoardGameBerserk Post /api/board/game/{gameId}/berserk Berserk a tournament game
BoardApi BoardGameChatGet Get /api/board/game/{gameId}/chat Fetch the game chat
BoardApi BoardGameChatPost Post /api/board/game/{gameId}/chat Write in the chat
BoardApi BoardGameClaimVictory Post /api/board/game/{gameId}/claim-victory Claim victory of a game
BoardApi BoardGameDraw Post /api/board/game/{gameId}/draw/{accept} Handle draw offers
BoardApi BoardGameMove Post /api/board/game/{gameId}/move/{move} Make a Board move
BoardApi BoardGameResign Post /api/board/game/{gameId}/resign Resign a game
BoardApi BoardGameStream Get /api/board/game/stream/{gameId} Stream Board game state
BoardApi BoardGameTakeback Post /api/board/game/{gameId}/takeback/{accept} Handle takeback offers
BotApi ApiBotOnline Get /api/bot/online Get online bots
BotApi ApiStreamEvent Get /api/stream/event Stream incoming events
BotApi BotAccountUpgrade Post /api/bot/account/upgrade Upgrade to Bot account
BotApi BotGameAbort Post /api/bot/game/{gameId}/abort Abort a game
BotApi BotGameChat Post /api/bot/game/{gameId}/chat Write in the chat
BotApi BotGameChatGet Get /api/bot/game/{gameId}/chat Fetch the game chat
BotApi BotGameMove Post /api/bot/game/{gameId}/move/{move} Make a Bot move
BotApi BotGameResign Post /api/bot/game/{gameId}/resign Resign a game
BotApi BotGameStream Get /api/bot/game/stream/{gameId} Stream Bot game state
BroadcastsApi BroadcastAllRoundsPgn Get /api/broadcast/{broadcastTournamentId}.pgn Export all rounds as PGN
BroadcastsApi BroadcastIndex Get /api/broadcast Get official broadcasts
BroadcastsApi BroadcastPush Post /broadcast/round/{broadcastRoundId}/push Push PGN to your broadcast round
BroadcastsApi BroadcastRoundCreate Post /broadcast/{broadcastTournamentId}/new Create a broadcast round
BroadcastsApi BroadcastRoundGet Get /broadcast/{broadcastTournamentSlug}/{broadcastRoundSlug}/{broadcastRoundId} Get your broadcast round
BroadcastsApi BroadcastRoundPgn Get /api/broadcast/round/{broadcastRoundId}.pgn Export one round as PGN
BroadcastsApi BroadcastRoundUpdate Post /broadcast/round/{broadcastRoundId}/edit Update your broadcast round
BroadcastsApi BroadcastStreamRoundPgn Get /api/stream/broadcast/round/{broadcastRoundId}.pgn Stream an ongoing broadcast tournament as PGN
BroadcastsApi BroadcastTourCreate Post /broadcast/new Create a broadcast tournament
BroadcastsApi BroadcastTourGet Get /broadcast/{slug}/{broadcastTournamentId} Get your broadcast tournament
BroadcastsApi BroadcastTourUpdate Post /broadcast/{broadcastTournamentId}/edit Update your broadcast tournament
BulkPairingsApi BulkPairingCreate Post /api/bulk-pairing Create a bulk pairing
BulkPairingsApi BulkPairingDelete Delete /api/bulk-pairing/{id} Cancel a bulk pairing
BulkPairingsApi BulkPairingGet Get /api/bulk-pairing View upcoming bulk pairings
BulkPairingsApi BulkPairingStartClocks Post /api/bulk-pairing/{id}/start-clocks Manually start clocks
ChallengesApi AdminChallengeTokens Post /api/token/admin-challenge Admin challenge tokens
ChallengesApi ChallengeAccept Post /api/challenge/{challengeId}/accept Accept a challenge
ChallengesApi ChallengeAi Post /api/challenge/ai Challenge the AI
ChallengesApi ChallengeCancel Post /api/challenge/{challengeId}/cancel Cancel a challenge
ChallengesApi ChallengeCreate Post /api/challenge/{username} Create a challenge
ChallengesApi ChallengeDecline Post /api/challenge/{challengeId}/decline Decline a challenge
ChallengesApi ChallengeList Get /api/challenge List your challenges
ChallengesApi ChallengeOpen Post /api/challenge/open Open-ended challenge
ChallengesApi ChallengeStartClocks Post /api/challenge/{gameId}/start-clocks Start clocks of a game
ChallengesApi RoundAddTime Post /api/round/{gameId}/add-time/{seconds} Add time to the opponent clock
ExternalEngineApi ApiExternalEngineAcquire Post /api/external-engine/work Acquire analysis request
ExternalEngineApi ApiExternalEngineAnalyse Post /api/external-engine/{id}/analyse Analyse with external engine
ExternalEngineApi ApiExternalEngineCreate Post /api/external-engine Create external engine
ExternalEngineApi ApiExternalEngineDelete Delete /api/external-engine/{id} Delete external engine
ExternalEngineApi ApiExternalEngineGet Get /api/external-engine/{id} Get external engine
ExternalEngineApi ApiExternalEngineList Get /api/external-engine List external engines
ExternalEngineApi ApiExternalEnginePut Put /api/external-engine/{id} Update external engine
ExternalEngineApi ApiExternalEngineSubmit Post /api/external-engine/work/{id} Answer analysis request
GamesApi ApiAccountPlaying Get /api/account/playing Get my ongoing games
GamesApi ApiGamesUser Get /api/games/user/{username} Export games of a user
GamesApi ApiUserCurrentGame Get /api/user/{username}/current-game Export ongoing game of a user
GamesApi GameImport Post /api/import Import one game
GamesApi GamePgn Get /game/export/{gameId} Export one game
GamesApi GamesByIds Post /api/stream/games/{streamId} Stream games by IDs
GamesApi GamesByIdsAdd Post /api/stream/games/{streamId}/add Add game IDs to stream
GamesApi GamesByUsers Post /api/stream/games-by-users Stream games of users
GamesApi GamesExportIds Post /api/games/export/_ids Export games by IDs
GamesApi StreamGame Get /api/stream/game/{id} Stream moves of a game
MessagingApi InboxUsername Post /inbox/{username} Send a private message
OAuthApi ApiToken Post /api/token Obtain access token
OAuthApi ApiTokenDelete Delete /api/token Revoke access token
OAuthApi Oauth Get /oauth Request authorization code
OAuthApi TokenTest Post /api/token/test Test multiple OAuth tokens
OpeningExplorerApi OpeningExplorerLichess Get /lichess Lichess games
OpeningExplorerApi OpeningExplorerLichessHistory Get /lichess/history Lichess games history
OpeningExplorerApi OpeningExplorerMaster Get /masters Masters database
OpeningExplorerApi OpeningExplorerMasterGame Get /master/pgn/{gameId} OTB master game
OpeningExplorerApi OpeningExplorerPlayer Get /player Player games
PuzzlesApi ApiPuzzleActivity Get /api/puzzle/activity Get your puzzle activity
PuzzlesApi ApiPuzzleDaily Get /api/puzzle/daily Get the daily puzzle
PuzzlesApi ApiPuzzleDashboard Get /api/puzzle/dashboard/{days} Get your puzzle dashboard
PuzzlesApi ApiPuzzleId Get /api/puzzle/{id} Get a puzzle by its ID
PuzzlesApi ApiStormDashboard Get /api/storm/dashboard/{username} Get the storm dashboard of a player
PuzzlesApi RacerPost Post /api/racer Create and join a puzzle race
RelationsApi ApiUserFollowing Get /api/rel/following Get users followed by the logged in user
RelationsApi FollowUser Post /api/rel/follow/{username} Follow a player
RelationsApi UnfollowUser Post /api/rel/unfollow/{username} Unfollow a player
SimulsApi ApiSimul Get /api/simul Get current simuls
StudiesApi StudyAllChaptersPgn Get /api/study/{studyId}.pgn Export all chapters
StudiesApi StudyChapterPgn Get /study/{studyId}/{chapterId}.pgn Export one study chapter
StudiesApi StudyExportAllPgn Get /study/by/{username}/export.pgn Export all studies of a user
SwissTournamentsApi ApiSwissJoin Post /api/swiss/{id}/join Join a Swiss tournament
SwissTournamentsApi ApiSwissNew Post /api/swiss/new/{teamId} Create a new Swiss tournament
SwissTournamentsApi ApiSwissTerminate Post /api/swiss/{id}/terminate Terminate a Swiss tournament
SwissTournamentsApi ApiSwissUpdate Post /api/swiss/{id}/edit Update a Swiss tournament.
SwissTournamentsApi ApiSwissWithdraw Post /api/swiss/{id}/withdraw Pause or leave a swiss tournament
SwissTournamentsApi ApiTeamSwiss Get /api/team/{teamId}/swiss Get team swiss tournaments
SwissTournamentsApi GamesBySwiss Get /api/swiss/{id}/games Export games of a Swiss tournament
SwissTournamentsApi ResultsBySwiss Get /api/swiss/{id}/results Get results of a swiss tournament
SwissTournamentsApi Swiss Get /api/swiss/{id} Get info about a Swiss tournament
SwissTournamentsApi SwissTrf Get /swiss/{id}.trf Export TRF of a Swiss tournament
TVApi TvChannelGames Get /api/tv/{channel} Get best ongoing games of a TV channel
TVApi TvChannels Get /api/tv/channels Get current TV games
TVApi TvFeed Get /api/tv/feed Stream current TV game
TablebaseApi AntichessAtomic Get /antichess Tablebase lookup for Antichess
TablebaseApi TablebaseAtomic Get /atomic Tablebase lookup for Atomic chess
TablebaseApi TablebaseStandard Get /standard Tablebase lookup
TeamsApi ApiTeamArena Get /api/team/{teamId}/arena Get team Arena tournaments
TeamsApi ApiTeamSwiss Get /api/team/{teamId}/swiss Get team swiss tournaments
TeamsApi TeamAll Get /api/team/all Get popular teams
TeamsApi TeamIdJoin Post /team/{teamId}/join Join a team
TeamsApi TeamIdKickUserId Post /team/{teamId}/kick/{userId} Kick a user from your team
TeamsApi TeamIdPmAll Post /team/{teamId}/pm-all Message all members
TeamsApi TeamIdQuit Post /team/{teamId}/quit Leave a team
TeamsApi TeamIdUsers Get /api/team/{teamId}/users Get members of a team
TeamsApi TeamOfUsername Get /api/team/of/{username} Teams of a player
TeamsApi TeamRequestAccept Post /api/team/{teamId}/request/{userId}/accept Accept join request
TeamsApi TeamRequestDecline Post /api/team/{teamId}/request/{userId}/decline Decline join request
TeamsApi TeamRequests Get /api/team/{teamId}/requests Get join requests
TeamsApi TeamSearch Get /api/team/search Search teams
TeamsApi TeamShow Get /api/team/{teamId} Get a single team
UsersApi ApiCrosstable Get /api/crosstable/{user1}/{user2} Get crosstable
UsersApi ApiUser Get /api/user/{username} Get user public data
UsersApi ApiUserActivity Get /api/user/{username}/activity Get user activity
UsersApi ApiUserPerf Get /api/user/{username}/perf/{perf} Get performance statistics of a user
UsersApi ApiUserRatingHistory Get /api/user/{username}/rating-history Get rating history of a user
UsersApi ApiUsers Post /api/users Get users by ID
UsersApi ApiUsersStatus Get /api/users/status Get real-time users status
UsersApi Player Get /api/player Get all top 10
UsersApi PlayerTopNbPerfType Get /api/player/top/{nb}/{perfType} Get one leaderboard
UsersApi StreamerLive Get /api/streamer/live Get live streamers
UsersApi TeamIdUsers Get /api/team/{teamId}/users Get members of a team

Documentation For Models

Documentation For Authorization

OAuth2
  • Type: OAuth
  • Flow: accessCode
  • Authorization URL: https://lichess.org/oauth
  • Scopes:
  • preference:read: Read your preferences
  • preference:write: Write your preferences
  • email:read: Read your email address
  • challenge:read: Read incoming challenges
  • challenge:write: Create, accept, decline challenges
  • challenge:bulk: Create, delete, query bulk pairings
  • study:read: Read private studies and broadcasts
  • study:write: Create, update, delete studies and broadcasts
  • tournament:write: Create tournaments
  • racer:write: Create and join puzzle races
  • puzzle:read: Read puzzle activity
  • team:read: Read private team information
  • team:write: Join, leave teams
  • team:lead: Manage teams (kick members, send PMs)
  • follow:read: Read followed players
  • follow:write: Follow and unfollow other players
  • msg:write: Send private messages to other players
  • board:play: Play with the Board API
  • bot:play: Play with the Bot API. Only for Bot accounts
  • web:mod: Use moderator tools (within the bounds of your permissions)

Example

auth := context.WithValue(context.Background(), sw.ContextAccessToken, "ACCESSTOKENSTRING")
r, err := client.Service.Operation(auth, args)

Or via OAuth2 module to automatically refresh tokens and perform user authentication.

import "golang.org/x/oauth2"

/* Perform OAuth2 round trip request and obtain a token */

tokenSource := oauth2cfg.TokenSource(createContext(httpClient), &token)
auth := context.WithValue(oauth2.NoContext, sw.ContextOAuth2, tokenSource)
r, err := client.Service.Operation(auth, args)

Documentation for Utility Methods

Due to the fact that model structure members are all pointers, this package contains a number of utility functions to easily obtain pointers to values of basic types. Each of these functions takes a value of the given basic type and returns a pointer to it:

  • PtrBool
  • PtrInt
  • PtrInt32
  • PtrInt64
  • PtrFloat
  • PtrFloat32
  • PtrFloat64
  • PtrString
  • PtrTime

Author

contact@lichess.org

Directories

Path Synopsis
cmd
example

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.