# Play By Play Shot Commentary
## **Endpoint URLs**
**Stroke Play:**
**URL Sample:**
`https://dde-api.data.imgarena.com/golf/pbp_commentary/{tournamentId}/{holeNo}`
**Match Play:**
`https://dde-api.data.imgarena.com/golf/pbp_commentary_mp/{tournamentId}/{holeNo}`
**URL Sample:**
`https://dde-api.data.imgarena.com/golf/pbp_commentary/690/1`
`https://dde-api.data.imgarena.com/golf/pbp_commentary_mp/698/1`
### 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.
### Request Parameters
This endpoint currently takes no additional parameters other than tournament Id and hole No, as stated above
### Recommended Polling Limits
* Our current polling request limit is: **1 request per 5 seconds per hole.**
* We therefore recommend and advise that polling is **kept under that limit where possible.**
* **The endpoints are per hole, so that's 18 endpoints to poll.**
* The other thing to consider is that **any other requests being made will contribute to the overall request count.**
### Response Model
**Shot Commentary Object**
| Field Name | Type | Description |
| ---------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| distanceToPinYards | float | Distance in yards from the player's current ball position to the pin of the hole |
| groupNo | string | The group number of the player, shared with who they are playing their round with |
| holeNo | string | The current Hole Number the event took place on. Holes **1 - 18** |
| latestStrokeNo | int | The *n*th shot/stroke on the current hole. |
| pbpCommentary | string | Generated text commentary relative to the shot in question and the surrounding situation of the player's shot |
| playerId | string | The internal ID of the Player of the current event |
| tournamentId | string | The unique Tournament ID of the current event |
| roundNumber | string | The current Round Number the event took place on. Usually would be 1 to 4 |
| playerName | string | The first name and surname of the player |
| prevDistanceToPinYards | float | Distance in yards from the player's previous ball position from their previous shot to the pin of the hole |
| teamNumber | string | The player's Team Number for the current Tournament format |
| shotFromLocation | string | The description of the location on the hole from where the player took their most recent shot, e.g. rough, fairway, bunker, tee |
| shotToLocation | string | The description of the location on the hole from where the player's ball has landed after their most recent shot, e.g. rough, fairway, bunker, green |
| externalPlayerId | string | Match Play Only Field
The recognised external (Golf tour) player ID
|
| rcTeam | string | Match Play Only Field
The Ryder Cup / Match Play Team. For Ryder Cup this will be either "U" or "E"
USA or Europe
|
| finishedGroup | Binary | 1 = This group has just finished their round/session.
0 = This group has not finished their round/session.
|
| latestPlayed | Binary | 1 = This group was the last to play.
0 = This group was not the last to play.
|
| nextToPlay | Binary | 1 = This group is the next to play.
0 = This group is not the next to play.
|
| timestamp | timestamp | The time stamp of this action. |
### Sample Response for Stroke Play
```
[
{
"distanceToPinYards": 1.75305683,
"groupNo": 3,
"holeNo": "9",
"latestStrokeNo": 2,
"pbpCommentary": "Shot 2: 202yds to Green, 5ft. 3in. to pin",
"playerId": "6088",
"playerName": "Sami Välimäki",
"prevDistanceToPinYards": 201.52473316181357,
"roundNumber": "2",
"shotFromLocation": "Fairway",
"shotToLocation": "Green",
"teamNumber": "102",
"tournamentId": "1654"
},
{
"distanceToPinYards": 143.0890825070431,
"groupNo": 3,
"holeNo": "9",
"latestStrokeNo": 2,
"pbpCommentary": "Shot 2: 71yds to Fairway, 143yds to pin",
"playerId": "24",
"playerName": "Jason Scrivener",
"prevDistanceToPinYards": 209.53538965875947,
"roundNumber": "2",
"shotFromLocation": "Rough",
"shotToLocation": "Fairway",
"teamNumber": "52",
"tournamentId": "1654"
}
]
```
### Sample Response 1 for Match Play (Ryder Cup)
```
[
{
"distanceToPinYards": 4.6609658199999995,
"externalPlayerId": "37579",
"groupNo": 18,
"holeNo": 1,
"latestStrokeNo": 4,
"pbpCommentary": "Shot 4: 24yds to Green, putting to halve the hole from 13ft. 12in.",
"playerId": "126",
"playerName": "Joakim Lagergren",
"prevDistanceToPinYards": 29.049025365988008,
"rcTeam": "E",
"roundNumber": 3,
"shotFromLocation": "Intermediate Rough",
"shotToLocation": "Green",
"teamNumber": 71,
"tournamentId": "1727",
"finishedGroup": 0,
"latestPlayed": 1,
"nextToPlay": 0,
"timestamp": "2023-09-18 11:00:00"
},
{
"distanceToPinYards": 202.6514971781812,
"externalPlayerId": "9486",
"groupNo": 19,
"holeNo": 1,
"latestStrokeNo": 1,
"pbpCommentary": "Shot 1: 256yds to Fairway Bunker, 202yds to pin",
"playerId": "27",
"playerName": "Lee Westwood",
"prevDistanceToPinYards": 473,
"rcTeam": "E",
"roundNumber": 3,
"shotFromLocation": "Tee Box",
"shotToLocation": "Fairway Bunker",
"teamNumber": 11,
"tournamentId": "1727",
"finishedGroup": 1,
"latestPlayed": 0,
"nextToPlay": 0,
"timestamp": "2023-09-18 11:05:00"
},
{
"distanceToPinYards": 171.20637243236047,
"externalPlayerId": "41227",
"groupNo": 19,
"holeNo": 1,
"latestStrokeNo": 1,
"pbpCommentary": "Shot 1: 286yds to Intermediate Rough, 171yds to pin",
"playerId": "209",
"playerName": "Scottie scheffler",
"prevDistanceToPinYards": 473,
"rcTeam": "U",
"roundNumber": 3,
"shotFromLocation": "Tee Box",
"shotToLocation": "Intermediate Rough",
"teamNumber": 47,
"tournamentId": "1727",
"finishedGroup": 1,
"latestPlayed": 0,
"nextToPlay": 1,
"timestamp": "2023-09-18 11:05:00"
}
]
```
### Sample Response 2 for Match Play (Ryder Cup)
```
[
{
"distanceToPinYards": 98.38675691243316,
"externalPlayerId": "37460",
"groupNo": 17,
"holeNo": 3,
"latestStrokeNo": 2,
"pbpCommentary": "Shot 2: 104yds to Fairway, 98yds to pin",
"playerId": "105",
"playerName": "Steven Brown",
"prevDistanceToPinYards": 201.10230987696153,
"rcTeam": "E",
"roundNumber": 3,
"shotFromLocation": "Fairway Bunker",
"shotToLocation": "Fairway",
"teamNumber": 17,
"tournamentId": "1727",
"finishedGroup": 0,
"latestPlayed": 1,
"nextToPlay": 0,
"timestamp": "2023-09-18 11:05:00"
},
{
"distanceToPinYards": 10.660510279999999,
"externalPlayerId": "39042",
"groupNo": 17,
"holeNo": 3,
"latestStrokeNo": 2,
"pbpCommentary": "Shot 2: 185yds to Green, putting for Birdie from 31ft. 12in.",
"playerId": "118",
"playerName": "Renato Paratore",
"prevDistanceToPinYards": 194.78257208218415,
"rcTeam": "E",
"roundNumber": 3,
"shotFromLocation": "Fairway",
"shotToLocation": "Green",
"teamNumber": 81,
"tournamentId": "1727",
"finishedGroup": 0,
"latestPlayed": 0,
"nextToPlay": 1,
"timestamp": "2023-09-18 11:05:00"
}
]
```