Tournament(s) Endpoint

Full specification for the Tournaments endpoint.

This endpoint returns information on all golf tournaments, past and future. Per each tournament, this endpoint will return the following information:

  • Dates of the tournament

  • Name of the tournament

  • Tournament format

  • Round information

  • Detailed information of the golf course(s) for the tournament.

Endpoint URLs

All tournaments:

https://dde-api.data.imgarena.com/golf/tournaments

Live tournaments:

https://dde-api.data.imgarena.com/golf/tournaments/live

The above endpoint can be filtered by tournamentDataStatus

"Scheduled" is a real tournament with data coming from the course

"Test" is a pseudo tournament for the the purpose of testing, can be subset of an entire tournament aimed at specific use cases

"Simulation" is either an entire pseudo tournament or replay of old tournament for the purpose of testing

"Disabled" is soft deleted, actioned internally

"All" returns all tournaments

Examples:

https://dde-api.data.imgarena.com/golf/tournaments

returns all tournaments except "tournamentDataStatus":"Disabled"

https://dde-api.data.imgarena.com/golf/tournaments?tournamentDataStatus=All

returns all tournaments

https://dde-api.data.imgarena.com/golf/tournaments?tournamentDataStatus=Scheduled

returns only tournaments with "tournamentDataStatus":"Scheduled"

https://dde-api.data.imgarena.com/golf/tournaments/live?tournamentDataStatus=Scheduled

returns all live tournaments with tournamentDataStatus":"Scheduled"

Specific tournament:

If you require information for a particular tournament, please enter the tournament Id which is returned via the IMG Arena Golf tournaments endpoint. i.e:

https://dde-api.data.imgarena.com/golf/tournaments/{id}

Required Headers

Key

Value

Accept

application/vnd.imggaming.dde.api+json;version=1

Content-Type

application/json

Authorization

Bearer eyvhaoudfgpdfgo*

Request Parameters

If no parameters are used, this endpoint will return all tournaments that start within one month either side of the date of the request. i.e By passing “dateFrom = 2019-07-01” and “dateTo = 2019-07-31”, endpoint will return all tournaments FROM the 1st of July 2019 To the 31st of July 2019.

This endpoint currently takes the following parameters:

Parameter

Description

dateFrom

e.g. dateFrom=2019-04-15. To be used in conjunction with dateTo to return a list of tournaments within a certain date range.

dateTo

e.g. dateTo=2019-04-15. To be used in conjunction with dateFrom to return a list of tournaments within a certain date range.

Note that if the dateFrom parameter overlaps when a particular tournament is being played, then the startDate returned will be before the dateFrom parameter. i.e if you are passing dateFrom=2020-11-01 and dateTo=2020-11-30", as the 1st is a Sunday and round 4 of the Joburg Open, the startDate returned will be "2020-10-29".

Please note that If you do not pass any parameters, this endpoint will return all tournaments that start within one month either side of the date of the request. i.e if request was made on the 1st of July, tournaments from the 1st of June to 1st August.

Response Model

Tournament Object

Field Name

Type

Description

Optional

format

string

The format of the tournament. The current values are:

"STROKE_PLAY", "RYDER_CUP", "BELGIAN_KO", "GOLF_SIXES", "MATCH_PLAY_5_DAYS", "MATCH_PLAY_4_DAYS", "STROKE_PLAY_PRO_AM", "CUSTOM", "STROKE", "MATCH", "TEAM_MATCH", "STABLEFORD", "TEAM", "STROKE_PLAY_PRO_AM", "OTHER"

tour

string

The Tour on which the tournament is taking place. Can be "PGA tour", "LPGA Tour" or "European Tour"

name

string

The name of the tournament

id

integer

The id of the tournament

startDate

-

Returned as null. please pass the tournament Id to retrieve this information.

endDate

date

The end date of the tournament (In UTC timezone)

startTeeTime

date/time or null

The starting tee time of the 1st round. (Added 23rd Nov 2021)

countryCode

string

The country code of the country in which the tournament is taking place (3 uppercase letters, eg "USA" or "FRA")

utcOffset

integer

The UTC offset of the local time of the tournament, e.g. if “1” the local time of the tournament is UTC+1

year

integer

The year in which the tournament is taking place

rounds

object

See object details below

golfCourses

object

See object details below

venue

string

String containing name or address of the venue

YES

mainGolfCourseId

integer

The Golf Course Id of the main course, i.e. where the shot data happens or the Host Course

YES

mainGolfCourseName

string

The Golf Course name of the main course, i.e. where the shot data happens or the Host Course

YES

mainExternalGolfCourseId

string

The Golf Course Id of the main course, from the federation database. This is composed of the ID number concatenated with the federation abbreviation, either ET or PGA

YES

externalId

string

A unique Federation generated Tournament ID

tournamentDataStatus

string

mainGolfCourseAssetId

string

The main course asset Id- internal use

{
    "format": "Stroke",
    "name": "TOUR Championship",
    "externalId": "PGA-R2022060",
    "endDate": "2022-08-28",
    "startTeeTime": "2022-08-25T15:45:00Z",
    "golfCourses": [   ],
    "year": 2022,
    "rounds": [
        {
            "format": "Other",
            "isPlayOff": false,
            "scoring": "StrokeSingles",
            "roundNo": 1,
            "advancementRule": "Other",
            "roundType": "StrokePlay"
        },
        {
            "format": "Other",
            "isPlayOff": false,
            "scoring": "StrokeSingles",
            "roundNo": 2,
            "advancementRule": "Other",
            "roundType": "StrokePlay"
        },
        {
            "format": "Other",
            "isPlayOff": false,
            "scoring": "StrokeSingles",
            "roundNo": 3,
            "advancementRule": "Other",
            "roundType": "StrokePlay"
        },
        {
            "format": "Other",
            "isPlayOff": false,
            "scoring": "StrokeSingles",
            "roundNo": 4,
            "advancementRule": "Other",
            "roundType": "StrokePlay"
        }
    ],
    "mainGolfCourseId": "36",
    "id": 472,
    "mainGolfCourseName": "East Lake Golf Club",
    "countryCode": "USA",
    "tournamentDataStatus": "Scheduled",
    "historicalDetails": {
        "id": 60,
        "name": "TOUR Championship"
    },
    "utcOffset": -4,
    "mainExternalGolfCourseId": "PGA-688",
    "tour": "PGA Tour",
    "startDate": "2022-08-25",
    "venue": null,
    "mainGolfCourseAssetId": null
}

Rounds Object

Field Name

Type

Description

roundNo

int

The number of the round

roundType

string

Specifies the type of round. Possible values:

"StrokePlay", "MatchPlay", "RoundRobin"

format

string

Specifies play format for a round. Possible values: "BEST_BALL", "FOUR_BALL", "FOURSOMES", "GREENSOMES", "GRUESOMES", "REGULAR", "OTHER"

isPlayOff

boolean

“True” if that round is a Play Off

scoring

string

Defines how each hole is scored for that round. Possible values; AggregatedStrokes, HoleWonPoint_TieZero, HoleWonPoint_TieHalved, Stableford, Other

advancementRule

string

Defines how players will be qualified for the next round. Possible values:

"ALL_QUALIFY", "CUT_64", "CUT_60", "CUT_50", "CUT_36_HOLES_ET", "CUT_54_HOLES_ET", "CUT_36_HOLES_PGA", "CUT_54_HOLES_PGA", "CUT_TEN_STROKE", "FINAL", "KNOCK_OUT", "WON_1_POINTS_DRAW_HALF_POINT", "WON_3_POINTS_DRAW_1_POINT", "OTHER"

"rounds": [
        {
            "format": "Other",
            "isPlayOff": false,
            "scoring": "StrokeSingles",
            "roundNo": 1,
            "advancementRule": "Other",
            "roundType": "StrokePlay"
        },
        {
            "format": "Other",
            "isPlayOff": false,
            "scoring": "StrokeSingles",
            "roundNo": 2,
            "advancementRule": "Other",
            "roundType": "StrokePlay"
        },
        {
            "format": "Other",
            "isPlayOff": false,
            "scoring": "StrokeSingles",
            "roundNo": 3,
            "advancementRule": "Other",
            "roundType": "StrokePlay"
        },
        {
            "format": "Other",
            "isPlayOff": false,
            "scoring": "StrokeSingles",
            "roundNo": 4,
            "advancementRule": "Other",
            "roundType": "StrokePlay"
        }
    ],

Golf Courses Object

Field Name

Type

Description

courseName

string

The name of (one of) the golf course(s) at which the event is being played

courseId

integer

The unique ID of the course

isMain

boolean

True if the main course at the tournament, false if not

courseDetails

object

Please view the courseDetails Object table

externalCourseID

string

The Golf Course Id of the main course, from the federation database. This is composed of the ID number concatenated with the federation abbreviation, either ET or PGA

scoringLevel

Integer

This integer value is linked to scoringType value.

1 = Shot link with laser

2 = Scored with walking scorer

3 = Holes scores Only

null = not scored

scoringType

string

Type of scoring method being applied that week. See possible values below.

 "golfCourses": [
        {
            "courseId": "36",
            "courseDetails": [**see object below**],
            "scoringLevel": 1,
            "scoringType": "ShotlinkWithLaser",
            "courseName": "East Lake Golf Club",
            "isMain": true,
            "externalCourseId": "PGA-688"
        }
    ],

ScoringTypes

For each Golf Course within a Tournament a particular Scoring Method is employed per round, these are described below.

Type

Description

ShotlinkWithLaser

Full Shot by Shot coverage across the complete Course. Including distanceToPin, shotDistance, x, y, z values.

ScoredWithWalkingScorer

Only Shot Counts available during the in play Hole. This Course will not have distance values per Shot.

HoleScoresOnly

Only Scores at the end of each Hole. Only useful for keeping a Scorecard up to date.

NotScored

Scores on this Course will not be available. Note that, this value is unlikely to be used operationally.

Course Details Object

Field Name

Type

Description

roundNo

int

The round number for which the following course details information applies

holes

object

Please view the holes object

"golfCourses": [
        {
            "courseId": "36",
            "courseDetails": [
                {
                    "roundNo": 1,
                    "holes": [
                    ]
                },
                {
                    "roundNo": 2,
                    "holes": [
                    ]
                },
                {
                    "roundNo": 3,
                    "holes": [
                    ]
                },
                {
                    "roundNo": 4,
                    "holes": [
                    ]
                }
            ],

Note if round "401" is returned, when the tournament went into a playoff round.

Holes Object

Field Name

Type

Description

holeNo

int

The number of the hole

officialYardage

int

The official yardage of the hole

actualYardage

int

the actual yardage of the hole

par

int

The par score of the hole

isOfficialDrivingHole

string

Whether it is the official driving hole on the course (true/false)

displayName

string

Display name of the hole

isStreaming

boolean

Is video streaming available on this hole?

teeBoxes

object

See teeBoxes object

pinPlacement

object

See pinPlacement object

**snippet for one hole**

 "holes": [
                        {
                            "displayName": null,
                            "par": 4,
                            "actualMetres": 412.39,
                            "isOfficialDrivingHole": false,
                            "actualYardage": 451,
                            "officialYardage": 469,
                            "isStreaming": false,
                            "teeBoxes": [**see object below**
                            ],
                            "officialMetres": 428.85,
                            "pinPlacement": {
                            },
                            "holeNo": 1
                        },

Pin Placement Object

Field Name

Type

Description

x

decimal

x co-ordinate of pin (previously longitude of the pin)

y

decimal

y co-ordinate of pin (previously latitude of the tee pin)

z

decimal

z co-ordinate of pin

"pinPlacement": {
                                "x": 11600.303,
                                "y": 9894.845,
                                "z": 1012.342
                            },

Tee Boxes Object

Occasionally multiple tee boxes are used at a single tournament. This describes each Tee Box.

Field Name

Type

Description

x

decimal

x co-ordinate of tee box (previously longitude of the tee box)

y

decimal

y co-ordinate of tee box (previously latitude of the tee box)

z

decimal

z co-ordinate of tee box

colour

string

the colour of the tee box, an identifier

"teeBoxes": [
                                {
                                    "x": 10258.742,
                                    "y": 10041.341,
                                    "z": 973.116,
                                    "colour": "Black"
                                }
                
            ]
PreviousStatic dataNextSchedule Endpoint