diff --git a/doc/specs/lichess-api.yaml b/doc/specs/lichess-api.yaml
index 26f8676..8bde702 100644
--- a/doc/specs/lichess-api.yaml
+++ b/doc/specs/lichess-api.yaml
@@ -437,6 +437,9 @@ paths:
/api/broadcast:
$ref: './tags/broadcasts/api-broadcasts-official.yaml'
+ /api/broadcast/top:
+ $ref: './tags/broadcasts/api-broadcasts-top.yaml'
+
/api/broadcast/by/{username}:
$ref: './tags/broadcasts/api-broadcasts-by-user.yaml'
diff --git a/doc/specs/schemas/BroadcastTop.yaml b/doc/specs/schemas/BroadcastTop.yaml
new file mode 100644
index 0000000..7e1d8f2
--- /dev/null
+++ b/doc/specs/schemas/BroadcastTop.yaml
@@ -0,0 +1,36 @@
+type: object
+
+properties:
+ active:
+ type: array
+ items:
+ $ref: "./BroadcastWithLastRound.yaml"
+ upcoming:
+ type: array
+ items:
+ $ref: "./BroadcastWithLastRound.yaml"
+ past:
+ type: object
+ properties:
+ currentPage:
+ type: number
+ example: 4
+ maxPerPage:
+ type: number
+ example: 20
+ currentPageResults:
+ type: array
+ items:
+ $ref: "./BroadcastWithLastRound.yaml"
+ nbResults:
+ type: number
+ example: 205194
+ previousPage:
+ type: [number, "null"]
+ example: 3
+ nextPage:
+ type: [number, "null"]
+ example: 5
+ nbPages:
+ type: number
+ example: 13680
diff --git a/doc/specs/schemas/BroadcastWithLastRound.yaml b/doc/specs/schemas/BroadcastWithLastRound.yaml
new file mode 100644
index 0000000..fab6e51
--- /dev/null
+++ b/doc/specs/schemas/BroadcastWithLastRound.yaml
@@ -0,0 +1,9 @@
+type: object
+
+properties:
+ group:
+ type: string
+ tour:
+ $ref: "./BroadcastTour.yaml"
+ lastRound:
+ $ref: "./BroadcastRoundInfo.yaml"
diff --git a/doc/specs/tags/broadcasts/api-broadcasts-official.yaml b/doc/specs/tags/broadcasts/api-broadcasts-official.yaml
index 940ad5c..05a5bed 100644
--- a/doc/specs/tags/broadcasts/api-broadcasts-official.yaml
+++ b/doc/specs/tags/broadcasts/api-broadcasts-official.yaml
@@ -17,7 +17,7 @@ get:
default: 20
minimum: 1
responses:
- '200':
+ "200":
description: The list of official broadcasts.
headers:
Access-Control-Allow-Origin:
@@ -27,115 +27,115 @@ get:
content:
application/x-ndjson:
schema:
- $ref: '../../schemas/BroadcastWithRounds.yaml'
+ $ref: "../../schemas/BroadcastWithRounds.yaml"
example:
- {
- 'tour':
- {
- 'id': 'qkY2yAcs',
- 'name': 'Norway Chess 2024 | Open',
- 'slug': 'norway-chess-2024--open',
- 'description': 'May 27th - June 7th | 6-player double round-robin | Classical time control | Carlsen, Ding, Caruana, Nakamura',
- 'createdAt': 1716672627410,
- 'tier': 5,
- 'image': 'https://image.lichess1.org/display?h=400&op=thumbnail&path=aaarmstark:relay:qkY2yAcs:dCwnFf0q.jpg&w=800&sig=36d5da931b2f9631e3ad4ae67cdb6b6412c469bb',
- 'markup': "The Norway Chess 2024 is a 6-player double round-robin tournament, held from the 27th of May to the 7th of June in Stavanger, Norway, featuring the former and current World Champions Magnus Carlsen and Ding Liren, Fabiano Caruana, Hikaru Nakamura, R Praggnanandhaa and Alireza Firouzja.
\nTime control is 120 minutes for the entire game with a 10-second increment from move 41.
\nOfficial Website | Standings | Regulations
\n
\nMutually agreed draws are not allowed until both players have made at least 30 moves.
\nIn the event of a draw, an Armageddon game is played to determine the winner of the round. Players keep the colour from the classical game. Time control is 10 minutes for White and 7 minutes for Black with a 1-second increment from move 41.
\n
\nStandings after Round 5
\nPlayers are awarded:
\n\n- 3 points for winning a classical game (W)
\n- 1 point for drawing a classical game (D)
\n- 0.5 points for winning the Armageddon game (Aw)
\n- 0 points for losing a classical game (L)
\n
\n\n
\nPrevious editions: 2023 | 2022 | 2021
\n",
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/qkY2yAcs',
- },
- 'rounds':
- [
- {
- 'id': 'VFMWFVLX',
- 'name': 'Round 5',
- 'slug': 'round-5',
- 'createdAt': 1716681349783,
- 'finished': true,
- 'startsAt': 1717254000000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-5/VFMWFVLX',
- },
- {
- 'id': '4JSenCaJ',
- 'name': 'Round 4',
- 'slug': 'round-4',
- 'createdAt': 1716681322100,
- 'finished': true,
- 'startsAt': 1717081200000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-4/4JSenCaJ',
- },
- {
- 'id': 'xmZcMs9U',
- 'name': 'Round 3',
- 'slug': 'round-3',
- 'createdAt': 1716681206009,
- 'finished': true,
- 'startsAt': 1716994800000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-3/xmZcMs9U',
- },
- {
- 'id': 'sbOHYOVj',
- 'name': 'Round 2',
- 'slug': 'round-2',
- 'createdAt': 1716673477425,
- 'finished': true,
- 'startsAt': 1716908400000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-2/sbOHYOVj',
- },
- {
- 'id': 'I9TLGEOt',
- 'name': 'Round 1',
- 'slug': 'round-1',
- 'createdAt': 1716672669495,
- 'finished': true,
- 'startsAt': 1716822000000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-1/I9TLGEOt',
- },
- {
- 'id': 'E0YSbWDC',
- 'name': 'Tiebreaks',
- 'slug': 'tiebreaks',
- 'createdAt': 1716681627336,
- 'startsAt': 1717790400000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/tiebreaks/E0YSbWDC',
- },
- {
- 'id': 'C5Zzd9mM',
- 'name': 'Round 10',
- 'slug': 'round-10',
- 'createdAt': 1716681541792,
- 'startsAt': 1717772400000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-10/C5Zzd9mM',
- },
- {
- 'id': 'Qvlkp2yF',
- 'name': 'Round 9',
- 'slug': 'round-9',
- 'createdAt': 1716681503527,
- 'startsAt': 1717686000000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-9/Qvlkp2yF',
- },
- {
- 'id': '2xhPECG3',
- 'name': 'Round 8',
- 'slug': 'round-8',
- 'createdAt': 1716681472192,
- 'startsAt': 1717513200000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-8/2xhPECG3',
- },
- {
- 'id': '4FLBpAW3',
- 'name': 'Round 7',
- 'slug': 'round-7',
- 'createdAt': 1716681411436,
- 'startsAt': 1717426800000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-7/4FLBpAW3',
- },
- {
- 'id': 'Whq5YPU7',
- 'name': 'Round 6',
- 'slug': 'round-6',
- 'createdAt': 1716681379848,
- 'startsAt': 1717340400000,
- 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-6/Whq5YPU7',
- },
- ],
- }
+ {
+ "tour":
+ {
+ "id": "qkY2yAcs",
+ "name": "Norway Chess 2024 | Open",
+ "slug": "norway-chess-2024--open",
+ "description": "May 27th - June 7th | 6-player double round-robin | Classical time control | Carlsen, Ding, Caruana, Nakamura",
+ "createdAt": 1716672627410,
+ "tier": 5,
+ "image": "https://image.lichess1.org/display?h=400&op=thumbnail&path=aaarmstark:relay:qkY2yAcs:dCwnFf0q.jpg&w=800&sig=36d5da931b2f9631e3ad4ae67cdb6b6412c469bb",
+ "markup": "The Norway Chess 2024 is a 6-player double round-robin tournament, held from the 27th of May to the 7th of June in Stavanger, Norway, featuring the former and current World Champions Magnus Carlsen and Ding Liren, Fabiano Caruana, Hikaru Nakamura, R Praggnanandhaa and Alireza Firouzja.
\nTime control is 120 minutes for the entire game with a 10-second increment from move 41.
\nOfficial Website | Standings | Regulations
\n
\nMutually agreed draws are not allowed until both players have made at least 30 moves.
\nIn the event of a draw, an Armageddon game is played to determine the winner of the round. Players keep the colour from the classical game. Time control is 10 minutes for White and 7 minutes for Black with a 1-second increment from move 41.
\n
\nStandings after Round 5
\nPlayers are awarded:
\n\n- 3 points for winning a classical game (W)
\n- 1 point for drawing a classical game (D)
\n- 0.5 points for winning the Armageddon game (Aw)
\n- 0 points for losing a classical game (L)
\n
\n\n
\nPrevious editions: 2023 | 2022 | 2021
\n",
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/qkY2yAcs",
+ },
+ "rounds":
+ [
+ {
+ "id": "VFMWFVLX",
+ "name": "Round 5",
+ "slug": "round-5",
+ "createdAt": 1716681349783,
+ "finished": true,
+ "startsAt": 1717254000000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-5/VFMWFVLX",
+ },
+ {
+ "id": "4JSenCaJ",
+ "name": "Round 4",
+ "slug": "round-4",
+ "createdAt": 1716681322100,
+ "finished": true,
+ "startsAt": 1717081200000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-4/4JSenCaJ",
+ },
+ {
+ "id": "xmZcMs9U",
+ "name": "Round 3",
+ "slug": "round-3",
+ "createdAt": 1716681206009,
+ "finished": true,
+ "startsAt": 1716994800000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-3/xmZcMs9U",
+ },
+ {
+ "id": "sbOHYOVj",
+ "name": "Round 2",
+ "slug": "round-2",
+ "createdAt": 1716673477425,
+ "finished": true,
+ "startsAt": 1716908400000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-2/sbOHYOVj",
+ },
+ {
+ "id": "I9TLGEOt",
+ "name": "Round 1",
+ "slug": "round-1",
+ "createdAt": 1716672669495,
+ "finished": true,
+ "startsAt": 1716822000000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-1/I9TLGEOt",
+ },
+ {
+ "id": "E0YSbWDC",
+ "name": "Tiebreaks",
+ "slug": "tiebreaks",
+ "createdAt": 1716681627336,
+ "startsAt": 1717790400000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/tiebreaks/E0YSbWDC",
+ },
+ {
+ "id": "C5Zzd9mM",
+ "name": "Round 10",
+ "slug": "round-10",
+ "createdAt": 1716681541792,
+ "startsAt": 1717772400000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-10/C5Zzd9mM",
+ },
+ {
+ "id": "Qvlkp2yF",
+ "name": "Round 9",
+ "slug": "round-9",
+ "createdAt": 1716681503527,
+ "startsAt": 1717686000000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-9/Qvlkp2yF",
+ },
+ {
+ "id": "2xhPECG3",
+ "name": "Round 8",
+ "slug": "round-8",
+ "createdAt": 1716681472192,
+ "startsAt": 1717513200000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-8/2xhPECG3",
+ },
+ {
+ "id": "4FLBpAW3",
+ "name": "Round 7",
+ "slug": "round-7",
+ "createdAt": 1716681411436,
+ "startsAt": 1717426800000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-7/4FLBpAW3",
+ },
+ {
+ "id": "Whq5YPU7",
+ "name": "Round 6",
+ "slug": "round-6",
+ "createdAt": 1716681379848,
+ "startsAt": 1717340400000,
+ "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-6/Whq5YPU7",
+ },
+ ],
+ }
diff --git a/doc/specs/tags/broadcasts/api-broadcasts-top.yaml b/doc/specs/tags/broadcasts/api-broadcasts-top.yaml
new file mode 100644
index 0000000..13a1222
--- /dev/null
+++ b/doc/specs/tags/broadcasts/api-broadcasts-top.yaml
@@ -0,0 +1,29 @@
+get:
+ operationId: broadcastsTop
+ summary: Get paginated top broadcast previews
+ description: |
+ The same data, in the same order, as can be seen on [https://lichess.org/broadcast](/broadcast).
+ tags:
+ - Broadcasts
+ security: []
+ parameters:
+ - in: query
+ name: page
+ description: Which page to fetch. Only page 1 has "active" and "upcoming" broadcasts.
+ schema:
+ type: integer
+ default: 1
+ minimum: 1
+ maximum: 20
+ responses:
+ "200":
+ description: Paginated top broadcast previews.
+ headers:
+ Access-Control-Allow-Origin:
+ schema:
+ type: string
+ default: "'*'"
+ content:
+ application/x-ndjson:
+ schema:
+ $ref: "../../schemas/BroadcastTop.yaml"