# Golf AI Commentary
## **Endpoint URLs**
`https://dde-api.data.imgarena.com/golf/commentary_ui/{endpoint_type}`
**URL Sample:**
* **Fast**
Fast returns all comments of all tiers. It has zero delay so corrections are applied in-place meaning the comment you showed a user a second ago could be corrected to new distances and stats next time you query the endpoint
Use the following for commenting on a specific player or group as has more detailed opportunity comments during the hole:
`https://dde-api.data.imgarena.com/golf/commentary_ui/fast`
* **Leaderboard**
Leaderboard returns only Tier 1 comments of type PreHole, PreShot, PostHole and PostShot. Its build for use on a leaderboard UI. Without any additional filters other than tournament, it can be used to automatically filter the PreHole and PreShot comments to just the top 6 most interesting players to watch. PostHole and PostShot come through on every group based on excitement. Also the endpoint is artificially delayed by 30 seconds to prevent showing pre corrected data.
Use the following for commenting on the leaderboards top players:\
`https://dde-api.data.imgarena.com/golf/commentary_ui/leaderboard`
* **Group**
Group returns only Tier 1 and Tier 2 comments of type PreHole, PreShot, PostHole and PostShot. Its built for use on a groups UI. PreHole and PreShot comments are de-duped to only mention once per group. PostHole and PostShot come through on every group based on excitement. Also the endpoint is artificially delayed by 30 seconds to prevent showing pre corrected data.
\
Use the following for commenting on the most interesting groups overall:
`https://dde-api.data.imgarena.com/golf/commentary_ui/groups`
### Required Headers
| Key | Value |
| ------------- | ------------------------------------------------ |
| Accept | application/vnd.imggaming.dde.api+json;version=1 |
| Content-Type | application/json |
| Authorization | Bearer eyvhaoudfgpdfgo\* |
\*Authorization header includes a truncated Bearer token, contact IMG for your auth token if you do not have.
### Polling Frequency
Suggested rate is 1 call every 30 seconds. We’d push that out to 2 every 30 seconds if a user wanted replication on their end in case their primary system crashes or is offline for any reason.
### Rate Limits
3.6 req/sec measured over 5mins per calling service
### Request Parameters
This endpoint currently takes the following parameters:
For **'Leaderboard' endpoint\_type** only **'limit' and 'tour\_id'** are **required** request parameters\
For **'Fast' and 'Groups' endpoint\_type**, **all request parameters** detailed below are **required**
| Parameter | Type | Value |
| --------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| group\_no | int | The Group Number the current player is in, for the current Round of the Tournament |
| hole\_no | int | The current Hole Number the event took place on. Holes **1 - 18** |
| limit | int | The amount of commentary objects to return in the response. If we wanted to see only one commentary object inside the array containing one person's comment, 'limit' would be 1, if we wanted to see 4 separate comment objects within the object array, limit would be 4.
In terms of limit, it largely comes down to what a user wants to show on the leaderboard for example. If a user wants the last 25 comments in the queue, then a limit of 25 makes sense. Recommended for latency purposes not to go beyond 50-100.
|
| player\_id | int | The internal ID of the Player of the current event |
| shot\_no | int | The *n*th shot/stroke of the current event. |
| tour\_id | int | The unique Tournament ID of the current event |
| tier | int | The quality of the commentary either 1 or 2, with 1 being the best quality. This value will link up with excitement generally |
| comment\_type | string | PostHole, PostShot, PreHole, PreShot, Top3TournamentStats, PlayerRoundStatDeviation, LastEclipsedRoundStats |
| full\_payload | Boolean (true / false) | True will return all fields including betting relevant fields.
False will return a refined list of commentary fields and is recommended to be used for Media purposes.
|
| interval | int | Interval parameter is just the last 'x' number of days with 365 being the max |
| start\_datetime | date | The start date and time which can be added to the response to filter out comments based on search criteria. This is the start date.
YYYY-MM-DDhh:mm:ss
|
| end\_datetime | date | The end date and time which can be added to the response to filter out comments based on search criteria. This is the end date.
YYYY-MM-DDhh:mm:ss
|
**Example of tier 1 ( most exciting level of comment could be a highlight or a exceptional opportunity to score )**
**"***On hole 13, Tosti (T74) hit their drive 338 yards to the Green, 6 feet left. He out-drove the field average by 49 yards. That drive gained 1.38 SG and was the best drive at this course***"**
\
**Example of tier 2 ( 2nd most exciting level of comment )**
**"***Højgaard is -4 for the tournament, T5 and heading to Hole 5. Højgaard has dropped 1 places on the leaderboard today. Next hole is a par 4 playing to 4.24. It is one of the easiest holes to make par after missing the green on the course today***"**\
\
\&#xNAN;**"***Morikawa birdied Hole 3 because of their putting (+0.58 SG). Morikawa has now made 3 birdies in 3 holes. This moved Morikawa to -6 and T2 for the tournament***"**\
\
\
### Response Model
**Shot Commentary Object**
| Field Name | Type | | Description |
| --------------- | --------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| commentType | string | "PlayerRoundStatDeviation\_TODAY" | The variant and relative time of shot comment, pre, current or post hole
Possible values: PostHole, PostShot, PreHole, PreShot, Top3TournamentStats, PlayerRoundStatDeviation, LastEclipsedRoundStats
|
| excitement | double | 1 | An excitement rating, used to categorise comments, with near 1 being the best. |
| externalEventId | string | "PGA-R2024493" | The recognised tour federation event ID of for the tounament |
| groupNo | string | "12" | The group number of the player, shared with who they are playing their round with |
| holeNo | string | "18" | The current Hole Number the event took place on. Holes **1 - 18** |
| holePar | int | "4" | Par of that hole |
| id | string | "2825" | The unique Tournament ID of the current event |
| playerId | string | "5929" | The internal ID of the Player of the current event |
| playerName | string | "Maverick McNealy" | Player fullname |
| firstName | string | "Maverick" | Player Forename |
| lastName | string | "McNealy" | Player Lastname |
| roundNo | string | "4" | The current Round Number the event took place on. Usually would be 1 to 4 |
| shotTypeNext | string | "OTT" | The next type of the shot the player will face. Could be: OTT = Off the Tee, APP = Approach, ARG = Around the Green, PUT = Putting |
| strokeNo | string | "0" | The *n*th shot/stroke of the current event. |
| teamId | string | "141" | The player's Team Number for the current Tournament format |
| text | string | "McNealy lost -1.18 more SG from 125 to 175 yards today (-1.57 SG) than his yearly average" | Generated text commentary relative to the shot in question and the surrounding situation of the Player's shot |
| tier | int | 1 | The quality of the commentary either 1 or 2, with 1 being the best quality. This value will link up with excitement generally |
| timestamp | timestamp | "2024-11-24T21:00:27.000Z" | The computer recorded time of the event in long format |
| tournamentName | string | "The RSM Classic" | The textual name of the tournament |
| tournamentScore | string | "-15" | The overall tournament score for that player at that time |
### Sample Response
```
{
"commentType": "PostHole_TODAY",
"excitement": 1.35,
"externalEventId": "PGA-R2024493",
"firstName": "Maverick",
"groupId": "1095301",
"groupNo": "12",
"holeNo": "18",
"holePar": 4,
"id": "1086",
"lastName": "McNealy",
"playerCountry": "USA",
"playerId": "5929",
"playerName": "Maverick McNealy",
"roundNo": "4",
"shotTypeNext": "OTT",
"strokeNo": "3",
"teamId": "141",
"text": "McNealy birdied Hole 18 because of their approach play (+0.79 SG). This moved McNealy to -16 and leading the tournament. McNealy made birdie on the hardest hole on the course today",
"tier": 1,
"timestamp": "2024-11-24T21:01:07.000Z",
"tournamentName": "The RSM Classic",
"tournamentScore": "-16"
},
```