Lichess FIDE API

openapi: 3.2.0
info:
  version: 2.0.144
  title: Lichess.org API reference FIDE API
  contact:
    name: Lichess.org API
    url: https://lichess.org/api
    email: contact@lichess.org
  x-logo:
    url: https://lichess1.org/assets/logo/lichess-pad12.svg
  license:
    name: AGPL-3.0-or-later
    url: https://www.gnu.org/licenses/agpl-3.0.txt
  description: '# Introduction

    Welcome to the reference for the Lichess API!'
servers:
- url: https://lichess.org
- url: https://lichess.dev
- url: http://localhost:{port}
  variables:
    port:
      default: '8080'
- url: http://l.org
tags:
- name: FIDE
  description: FIDE players and federations from their public download.
paths:
  /api/fide/player/{playerId}:
    get:
      operationId: fidePlayerGet
      summary: Get a FIDE player
      description: Get information about a FIDE player.
      tags:
      - FIDE
      security: []
      parameters:
      - in: path
        name: playerId
        description: The FIDE player ID.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The information about the FIDE player.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FIDEPlayer'
              examples:
                example player:
                  $ref: '#/components/examples/fide-getFidePlayer.json'
                example player without all values:
                  $ref: '#/components/examples/fide-getFidePlayer-nullYear.json'
  /api/fide/player/{playerId}/ratings:
    get:
      operationId: fidePlayerRatings
      summary: Get ratings history of a FIDE player
      description: Historical standard, rapid and blitz ratings of a FIDE player
      tags:
      - FIDE
      security: []
      parameters:
      - in: path
        name: playerId
        description: The FIDE player ID.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The rating histories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FIDEPlayerRatings'
              examples:
                example player:
                  $ref: '#/components/examples/fide-getFidePlayerRatings.json'
  /api/fide/player:
    get:
      operationId: fidePlayerSearch
      summary: Search FIDE players
      description: List of FIDE players search results for a query.
      tags:
      - FIDE
      security: []
      parameters:
      - in: query
        name: q
        description: The search query.
        required: true
        schema:
          type: string
          example: Erigaisi Arjun
      responses:
        '200':
          description: The list of FIDE players.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                default: '''*'''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FIDEPlayer'
              examples:
                default:
                  $ref: '#/components/examples/fide-searchFidePlayers.json'
components:
  examples:
    fide-getFidePlayer-nullYear.json:
      value:
        id: 8700761
        name: Hampus, Sorensen
        federation: ZAM
        year: null
    fide-getFidePlayer.json:
      value:
        id: 35009192
        name: Erigaisi Arjun
        federation: IND
        year: 2003
        title: GM
        standard: 2751
        rapid: 2741
        blitz: 2776
        gender: M
        photo:
          small: https://image.lichess1.org/display?fmt=webp&h=100&op=thumbnail&path=ZtNkAl1_0MHT.webp&w=100&sig=8a2122f91eab6c3f0528bce8ea5854fd561bbcde
          medium: https://image.lichess1.org/display?fmt=webp&h=500&op=thumbnail&path=ZtNkAl1_0MHT.webp&w=500&sig=f2faf575e19147ee8b1d2b573f1fd2e18fab88e7
          credit: Brigham Aldrich
    fide-getFidePlayerRatings.json:
      value:
        blitz: []
        rapid:
        - 2015081568
        - 2022091568
        - 2022101620
        - 2024021620
        - 2024031772
        - 2025121772
        standard:
        - 2015021577
        - 2015071577
        - 2015081679
        - 2015111679
        - 2015121616
        - 2016071616
        - 2016081618
        - 2016101618
        - 2016111685
        - 2017031685
        - 2017041692
        - 2017061692
        - 2017071698
        - 2017081698
        - 2017091720
        - 2024021720
        - 2024031832
        - 2025121832
    fide-searchFidePlayers.json:
      value:
      - id: 35009192
        name: Erigaisi Arjun
        federation: IND
        year: 2003
        title: GM
        standard: 2751
        rapid: 2741
        blitz: 2776
        gender: M
        photo:
          small: https://image.lichess1.org/display?fmt=webp&h=100&op=thumbnail&path=ZtNkAl1_0MHT.webp&w=100&sig=8a2122f91eab6c3f0528bce8ea5854fd561bbcde
          medium: https://image.lichess1.org/display?fmt=webp&h=500&op=thumbnail&path=ZtNkAl1_0MHT.webp&w=500&sig=f2faf575e19147ee8b1d2b573f1fd2e18fab88e7
          credit: Brigham Aldrich
      - id: 35009060
        name: Erigaisi Keerthana
        federation: IND
        year: 2002
        gender: F
  schemas:
    FIDEPlayer:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        title:
          $ref: '#/components/schemas/Title'
        federation:
          type: string
        year:
          type:
          - integer
          - 'null'
        inactive:
          type: integer
        standard:
          type: integer
        rapid:
          type: integer
        blitz:
          type: integer
        gender:
          type: string
          description: FIDE uses mandatory binary gender.
          enum:
          - M
          - F
        photo:
          $ref: '#/components/schemas/FIDEPlayerPhoto'
      required:
      - id
      - name
      - federation
    Title:
      type: string
      enum:
      - GM
      - WGM
      - IM
      - WIM
      - FM
      - WFM
      - NM
      - CM
      - WCM
      - WNM
      - LM
      - BOT
      description: only appears if the user is a titled player or a bot user
    FIDEPlayerPhoto:
      type: object
      properties:
        small:
          description: URL of a small (100x100) thumbnail of the photo
          type: string
        medium:
          description: URL of a medium (500x500) version of the photo
          type: string
        credit:
          description: If set, then you should make it appear next to the photo
          type: string
      required:
      - small
      - medium
    FIDEPlayerRatings:
      type: object
      description: "Data points are encoded. Each number contains a year, a month, and an ELO rating.\n\n`2015081568` -> `August 2015: 1568`\n\nHere's an example decoding implementation in JS:\n\n```js\n  const decodePoint = point => {\n    const elo = point % 10000;\n    const dateNum = Math.floor(point / 10000);\n    const year = Math.floor(dateNum / 100);\n    const month = dateNum % 100;\n    return [year, month, elo];\n  };\n```\n\nConsecutive months with same ELO are omitted. For a given ELO, only the first and last month are provided.\n"
      properties:
        standard:
          type: array
          items:
            type: number
        rapid:
          type: array
          items:
            type: number
        blitz:
          type: array
          items:
            type: number
      required:
      - standard
      - rapid
      - blitz
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'Read [the introduction for how to make authenticated requests](#description/authentication).

        '
      flows:
        authorizationCode:
          authorizationUrl: https://lichess.org/oauth
          tokenUrl: https://lichess.org/api/token
          scopes:
            preference:read: Read your preferences
            preference:write: Write your preferences
            email:read: Read your email address
            engine:read: Read your external engines
            engine:write: Create, update, delete your external engines
            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
            puzzle:write: Write 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](#tag/bot/POST/api/bot/account/upgrade)
            web:mod: Use moderator tools (within the bounds of your permissions)
x-provenance:
  method: harvested
  publisher: Lichess
  source: https://lichess.org/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)