# Leaderboard
This endpoint is a live websocket endpoint that returns all leaderboard information at any one time. Currently the whole leaderboard is sent whenever there is an update – this will look to be optimised in the future. You should receive a new update any time a player completes a hole, and their total strokes and “to par” score for the day changes. Please note that due to different data providers the "totalScore" value will be updated after each hole for PGA however for DPWT and LPGA, this value will only be updated after the player has completed the round
The authentication token provided will be required to make a connection to this websocket endpoint.
Once you have the API token, any further data that you send over the connection will be ignored.
N.B – This endpoint sends heartbeats in-between data packets to let you know that it is still connected.
This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.
### Endpoint URL
`wss://dde-streams.data.imgarena.com/media/golf/tournaments/{tournamentId}/leaderboard`
N.B. – Please use tournament ID “99999” to return you the sample data. This sample data is 3 leaderboard updates for 3 players towards the end of a round. The authentication token provided will be required to make a connection to this websocket endpoint.
### Process for connecting to the web socket endpoints
* Connect to SSL websocket address
* Send JSON packet containing API token
* Receive response indicating that connection is authorised (or a response indicating why the connection cannot be made)
* Receive heartbeat packets every 10 seconds to verify the connection is live
* Receive data packets
Once you have the API token, any further data that you send over the connection will be ignored. This endpoint sends heartbeats in-between data packets to let you know that it is still connected.
### Request parameters
Request Parameters This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here. For this example we will be using the following endpoint URL for The American Express 2025: `wss://dde-streams.imggaming.com/media/golf/tournaments/1092/leaderboard`
### Leaderboard via RestAPI
Note that the leaderboard websocket is available via Rest - `https://dde-api.data.imgarena.com/media/golf/tournaments/{tournamentId}/leaderboard?rest=true`
### Response model
**Leaderboard Object**
| **Field Name** | Type | Description |
| ------------------------ | ------- | --------------------------------------------------------------------------------------- |
| standings | object | see object docs |
| tournamentId | integer | Identifier for the tournament |
| timestamp | time | Time the update is sent |
| seqNum | integer | Sequence number of the update packet |
| currentRound | object | See object docs |
| roundStatuses | array | See array docs; |
| tournamentStatus | string | Possible values:
NotStarted, InProgress, PlayComplete, Suspended, Official
|
| isPlaySuspendedOvernight | boolean | Flag will be set as true, if play is suspended over night. |
```
{
"currentRound": {** see object below **},
"isPlaySuspendedOvernight": false,
"roundStatuses": [
{
"number": 1,
"status": "Official"
},
{
"number": 2,
"status": "Official"
},
{
"number": 3,
"status": "Official"
},
{
"number": 4,
"status": "Official"
}
],
"seqNum": 10326,
"standings": [** see object below **],
"timestamp": "2025-01-20T00:44:38.319Z",
"tournamentId": 1092,
"tournamentStatus": "Official"
}
```
**Standings Array**
| **Field Name** | Type | Description |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| players | object | See object docs |
| holesThrough | object | See object docs |
| roundInfo | object | See object docs |
| roundInfo | object | See object docs |
| toParToday | object | See object docs |
| totalScore | object | See object docs |
| status | string | Possible values:
Cut, Uncut, Withdrawn, DidNotStart, Disqualified, MadeCutButDidNotFinish, Removed, Retired, Other
|
| currentRound | integer | Number of current round |
| teamNo | integer | What team the player is associated with (for individual tournaments players are in their own team of 1) |
| toPar | object | See object docs |
| position | object | See object docs |
```
"standings": [
{
"currentRound": 4,
"holesThrough": {** see object below **},
"players": [** see object below **],
"position": {** see object below **},
"roundInfo": {
"1": {** see object below **},
"2": {** see object below **},
"3": {** see object below **},
"4": {** see object below **}
},
"status": "Uncut",
"teamNo": 3,
"toPar": {** see object below **},
"toParToday": {** see object below **},
"totalScore": {** see object below **}
}
```
**Players Array**
| **Field Name** | Type | Description |
| -------------- | ------- | ---------------------------- |
| displayName | string | Player's display name |
| country | string | Country code of the player |
| isAmateur | boolean | True if player is an amateur |
| lastName | string | Last name |
| firstName | string | First name |
| id | integer | Player's identifier |
| gender | string | Gender of player |
```
"players": [
{
"country": "AUT",
"displayName": "Sepp Straka",
"firstName": "Sepp",
"gender": "male",
"id": 3361,
"isAmateur": false,
"lastName": "Straka"
}
]
```
**Holes Through Object**
| Field Name | Type | Description |
|---|
| Field Name | Type | Description |
| value | integer | The number of holes that a player has completed at this point |
| displayValue | string | The number of holes that a player has completed at |
```
"holesThrough": {
"displayValue": "18",
"value": 18
}
```
**roundInfo object**
| **Field Name** | Type | Description |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| Value (1) | object | Round 1 - see value object table |
| Value (2) | object | Round 2 - see value object table |
| Value (3) | object | Round 3 - see value object table |
| Value (4) | object | Round 4 - see value object table |
| Value (401) | object | Playoff round 1 after 4th round. The playoff numbering convention is "{round # after which the playoff is held}0{round # of playoff} " |
```
"roundInfo": {
"1": {** see object below **},
"2": {** see object below **},
"3": {** see object below **},
"4": {** see object below **}
}
```
**roundInfo value object (including round values 1, 2, 3, 4, 401+)**
| **Field Name** | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------- |
| score | object | See object docs |
| toPar | object | See object docs |
| teeTime | string | Time golfer scheduled to tee off |
| startHole | integer | Number of the hole the player begins the round on (typically only 1 or 10) |
| roundFinishedPosition | integer | Overall tournament standings at the end of a given round |
| roundFinishedIsTied | boolean | Tie indicator for `roundFinishedPosition` |
```
"1": {
"roundFinishIsTied": true,
"roundFinishPosition": 8,
"score": {** see object below **},
"startHole": 10,
"teeTime": "2025-01-16T16:41:00Z",
"toPar": {** see object below **}
}
```
**Round Info - Score Object**
| **Field Name** | Type | Description |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| value | integer | The overall number of strokes the player has taken in the selected round, updated a the end of the hole |
| displayValue | string | The overall number of strokes the player has taken in the selected round, updated a the end of the hole |
```
"score": {
"displayValue": "65",
"value": 65
}
```
**Round info - toPar object**
| Field Name | Type | Description |
|---|
| Field Name | Type | Description |
| value | integer | The overall "to par" score so far for the tournament for a given player. Updated after every hole finishes |
| displayValue | string | The overall "to par" score so far for the tournament for a given player. Updated after every hole finishes. |
"toPar": {
"displayValue": "-7",
"value": -7
}
**Round info - toParToday object**
| **Field Name** | Type | Description |
| -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| value | integer | The overall "to par" score so far for the day for that player for the selected round. Updated after every hole finishes |
| displayValue | string | The overall "to par" score so far for the day for that player for the selected round. Updated after every hole finishes |
"toParToday": {
"displayValue": "-2",
"value": -2
}
**Round info - totalScore object**
| Field Name | Type | Description |
|---|
| Field Name | Type | Description |
| value | integer | The overall number of strokes the player has taken in the tournament to date. For PGA events this value is updated after each hole is complete. updated at the end of the round. For DPWT and LPGA events, this value is updated at the end of the round. |
| displayValue | string | The overall number of strokes the player has taken in the tournament to date. For PGA events this value is updated after each hole is complete. updated at the end of the round. For DPWT and LPGA events, this value is updated at the end of the round. |
```
"totalScore": {
"displayValue": "263",
"value": 263
}
```
**Position object**
| Field Name | Type | Description |
|---|
| Field Name | Type | Description |
| order | integer | The unique order of that player in the leaderboard. To be used to order the players from top to bottom |
| value | integer | The player's position in the leaderboard. Players can have the same value |
| format | string | Either "absolute" if only player in that position, or "tied" is sharing the position with another player |
| displayValue | string | The player's position in the leaderboard - will include a "T" if tied |
```
"position": {
"displayValue": "1",
"format": "absolute",
"order": 1,
"value": 1
}
```
**Current round object**
| **Field Name** | Type | Description |
| -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| number | integer | Number of the current round |
| name | string | Name of the current round |
| cutline | object | Includes “required, a boolean field indicating if there is a cut on the current round or not, and “cut”, which is the current score that players need to be above to avoid the cut. |
```
"currentRound": {
"cutLine": {** see object below **},
"name": "Round 4",
"number": 4
}
```
**Cut line object**
| **Field Name** | Type | Description |
| -------------- | ------- | -------------------------------------------- |
| cut | integer | Cut line score |
| required | boolean | Is it required to show a cut line true/false |
```
"cutLine": {
"cut": -9,
"required": true
}
```
**roundStatus Array**
An array containing multiple objects, each object contains the following:
| **Field Name** | Type | Description |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| number | integer | Number of the current round |
| status | string | Status of the round. possible values:
GroupingsOfficial, InProgress, Maintenance, NotStarted, Official, PlayComplete, Suspended, Cancelled
|
```
"roundStatuses": [
{
"number": 1,
"status": "Official"
},
{
"number": 2,
"status": "Official"
},
{
"number": 3,
"status": "Official"
},
{
"number": 4,
"status": "Official"
},
{
"number": 401,
"status": "Official"
}
]
```
**Sample Response**
```
{
"currentRound": {
"cutLine": {
"cut": -9,
"required": true
},
"name": "Round 4",
"number": 4
},
"isPlaySuspendedOvernight": false,
"roundStatuses": [
{
"number": 1,
"status": "Official"
},
{
"number": 2,
"status": "Official"
},
{
"number": 3,
"status": "Official"
},
{
"number": 4,
"status": "Official"
}
],
"seqNum": 10326,
"standings": [ {
"currentRound": 4,
"holesThrough": {
"displayValue": "18",
"value": 18
},
"players": [
{
"country": "AUT",
"displayName": "Sepp Straka",
"firstName": "Sepp",
"gender": "male",
"id": 3361,
"isAmateur": false,
"lastName": "Straka"
}
],
"position": {
"displayValue": "1",
"format": "absolute",
"order": 1,
"value": 1
},
"roundInfo": {
"1": {
"roundFinishIsTied": true,
"roundFinishPosition": 8,
"score": {
"displayValue": "65",
"value": 65
},
"startHole": 10,
"teeTime": "2025-01-16T16:41:00Z",
"toPar": {
"displayValue": "-7",
"value": -7
}
},
"2": {
"roundFinishIsTied": true,
"roundFinishPosition": 3,
"score": {
"displayValue": "64",
"value": 64
},
"startHole": 1,
"teeTime": "2025-01-17T18:31:00Z",
"toPar": {
"displayValue": "-8",
"value": -8
}
},
"3": {
"roundFinishIsTied": false,
"roundFinishPosition": 1,
"score": {
"displayValue": "64",
"value": 64
},
"startHole": 10,
"teeTime": "2025-01-18T17:58:00Z",
"toPar": {
"displayValue": "-8",
"value": -8
}
},
"4": {
"roundFinishIsTied": false,
"roundFinishPosition": 1,
"score": {
"displayValue": "70",
"value": 70
},
"startHole": 1,
"teeTime": "2025-01-19T18:50:00Z",
"toPar": {
"displayValue": "-2",
"value": -2
}
}
},
"status": "Uncut",
"teamNo": 3,
"toPar": {
"displayValue": "-25",
"value": -25
},
"toParToday": {
"displayValue": "-2",
"value": -2
},
"totalScore": {
"displayValue": "263",
"value": 263
}
}....
..........],
"timestamp": "2025-01-20T00:44:38.319Z",
"tournamentId": 1092,
"tournamentStatus": "Official"
}
```