# Match Event Data (MLS) API

This endpoint returns an entire MLS Soccer match event data session in the form of sequential timestamped packets covering the MLS match. The endpoint can be filtered by the specific MLS fixtureId for that match and returns each phase of the match action along with the preceding connected match event (for example a pass assist leading to a shot on goal).

Key information within the response is as follows:

* Name of the competition
* Competition & Season Id
* Action type
* Clock time
* Direction of play
* Period (1st or 2nd Half)
* XY coordinate position of match event
* Target Player details including shirt number and Id (if applicable)
* XY coordinate of target player
* (Preceding) Passing/Shooting player details including shirt number and Id
* Team name and details
* Competition name and details

## Endpoint URLs

**`https://dde-api.data.imgarena.com/soccer/fixture/{fixture_id}/events`**

## Polling Frequency <a href="#undefined" id="undefined"></a>

We recommend the following frequency for your REST requests to ensure that you have the most up-to-date information at all times:<br>

<table><thead><tr><th width="155">Frequency</th></tr></thead><tbody><tr><td>Every 30 seconds for media usage</td></tr></tbody></table>

## 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 a **fixture\_id** in the url header to fetch the correct MLS fixture.

## Response Model

\
**Action Id object**

<table data-header-hidden><thead><tr><th width="261.66666666666663">Field Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Field Name</td><td>Type</td><td>Description</td></tr><tr><td>actionId</td><td>alpha numeric</td><td>actionId is a composite key of matchId , eventId and actionType</td></tr><tr><td>actionTypeId</td><td>int</td><td>The ID of the actionType (Pass, Shot..)</td></tr><tr><td>actionTypeMetadata</td><td>string</td><td>Type of metadata contained in packet (Pass, Shot, Save..)</td></tr><tr><td>clockTime</td><td>dateTime</td><td>The clock time within the match fixture (001:39:23) means 1 minute 39 seconds into the match</td></tr><tr><td>competitionId</td><td>alpha numeric</td><td>The ID of the competition (i.e. MLS or MLS Cup)</td></tr><tr><td>directionOfPlay</td><td>string</td><td><p>Determined at start of period of play (first half, second half, etc)</p><p>Specifies what direction the team is playing - whether rightToLeft or leftToRight</p></td></tr><tr><td>eventId</td><td>number</td><td>The ID of the event within the match</td></tr><tr><td>eventTime</td><td>UTC dateTime</td><td><p>The timestamp of the event which differs from clockTime, for example:</p><p>(2024-02-22T01:10:28.953Z)</p></td></tr><tr><td>fixtureId</td><td>alpha numeric</td><td>The MLS Fixture ID</td></tr><tr><td>isSuccessful</td><td>boolean</td><td>Setting isSuccessful conditionally if the action resulted in a successful completion (successful pass, successful shot on goal)</td></tr><tr><td>messageId</td><td>alpha numeric</td><td>messageId is a unique ID for each produced packet</td></tr><tr><td>metadata object { }</td><td>object array</td><td>This is an array consisting if detailed contextual meta data explaining the action, player and position of the event, wtih details such as type of event (pass, shot, save), distance of (pass, shot), current player position of event, player details, target the pass/shot was aimed for.</td></tr><tr><td>targetPosition</td><td>Key Value Pair Object Array</td><td>The XY position of the target of this action</td></tr></tbody></table>

\
**Parent action Id object**

<table data-header-hidden><thead><tr><th width="261.66666666666663">Field Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Field Name</td><td>Type</td><td>Description</td></tr><tr><td>parentActionId</td><td>string</td><td><p>One EventId may map to several packets, this field maps to the predecessor packet</p><p><br>The first packet will have no parentActionId</p><p><br>For example SuccessfulShot will create two SPS packets shot and goal</p><p>shot will have no parent</p><p><br>goal parent will map to shot actionId</p></td></tr><tr><td>period</td><td>string</td><td>(first half, second half)</td></tr><tr><td>player object { }</td><td>object array</td><td>This is an array consisting of high level data around the player who provided the preceding action, including name, id, shirt number</td></tr><tr><td>seasonId</td><td>alpha numeric</td><td>The ID of the MLS season</td></tr><tr><td>stageId</td><td>alpha numeric</td><td>The stage ID within the season/event (Semi final of cup), (last game of the regular season)</td></tr><tr><td>team object { }</td><td>object array</td><td>This is an array consisting of high level data around the team in possession</td></tr><tr><td>teamPossessionPhaseId</td><td>int</td><td><p>This describes the phase of play and is an incrementing value according ballPossessionPhase</p><p>Not necessarily inline with time the event occurred</p></td></tr></tbody></table>

## Actions List (Described in 'actionTypeMetadata' object)

All Event Action types that are returned from the endpoint

```
    pass
    launch
    shot
    duel
    offside
    cornerAwarded
    freeKickAwarded
    throwInAwarded
    throwInTaken
    goalKickAwarded
    offsideFor
    card
    dribble
    tackle
    interception
    clearance
    cross
    
    goalkeeperCollection
    goalkeeperPunch
    goalkeeperCatch
    goalkeeperDrop
    goalkeeperSave
    goalkeeperPenaltyFaced
    goalkeeperThrow
    
    varPending
    varDecision

    bigChance 
    
    playerOn 
    playerOff
    substitution
    playStopped
    playResumed
    penaltyAwarded
    penaltyTaken

    goal
    ownGoal
    
    aerial
    dispossessed
    ballTouch
    ballRecovery
    block
    badTouch
    
    lineup
    clock
    addedTime
    postMatchChecks
    startPeriod
    endPeriod
    startFixture     
    endFixture
```

##

## Sample Response Extracts

```
{
  "actionId": "ffd223fc-b185-3b16-9483-f6ec5655aa1f",
  "actionTypeId": "13",
  "actionTypeMetadata": "pass",
  "clockTime": "000:21:48",
  "competitionId": "be0b9007-03c3-463b-b22b-27cd871c9b6d",
  "directionOfPlay": "rightToLeft",
  "eventId": 610200000031,
  "eventTime": "2024-02-22T01:10:28.953Z",
  "fixtureId": "15f25cc4-6abb-4e31-bb60-d8bc27e8229f",
  "isSuccessful": true,
  "messageId": "cef80a50-efb7-47eb-8b99-3dffceabd2d0",
  "metadata": {
    "pass": {
      "actionContext": null,
      "direction": -2.16,
      "distance": 11.34,
      "isAssist": null,
      "period": "first",
      "position": { "X": 0.46, "Y": 0.91 },
      "targetPlayer": {
        "externalId": "MLS-OBJ-0000OR",
        "firstName": "Julian",
        "fullName": "Julian Gressel",
        "id": "7f0fd1f1-a97a-4a2b-8485-747922953850",
        "lastName": "Gressel",
        "shirtNumber": 24
      },
      "targetPosition": { "X": 0.44, "Y": 0.75 }
    }
  },
  "parentActionId": null,
  "period": "first",
  "player": {
    "externalId": "MLS-OBJ-0000A9",
    "firstName": "DeAndre",
    "fullName": "DeAndre Yedlin",
    "id": "636986b6-722f-4757-9efa-109aea914b89",
    "lastName": "Yedlin",
    "shirtNumber": 2
  },
  "seasonId": "d2f17733-371f-4d06-b207-07989ce96eee",
  "stageId": "7c574987-6ff0-4c0b-809c-1d66f20dc5a3",
  "team": {
    "externalId": "MLS-CLU-000008",
    "id": "734bfa38-5ed7-4dcd-90e4-b957e58a7db2",
    "name": "Inter Miami CF"
  },
  "teamPossessionPhaseId": 31
},
{
  "actionId": "80ab1098-a543-3658-b622-5bc8bc12d11d",
  "actionTypeId": "14",
  "actionTypeMetadata": "shot",
  "clockTime": "082:55:47",
  "competitionId": "be0b9007-03c3-463b-b22b-27cd871c9b6d",
  "directionOfPlay": "rightToLeft",
  "eventId": 610200001226,
  "eventTime": "2024-02-22T02:54:07.718Z",
  "fixtureId": "15f25cc4-6abb-4e31-bb60-d8bc27e8229f",
  "isSuccessful": true,
  "messageId": "d9d1c6c3-f0b4-4cf5-9dce-508be62bce8d",
  "metadata": {
    "shot": {
      "assistPlayer": {
        "externalId": "MLS-OBJ-000528",
        "firstName": "Luis",
        "fullName": "Luis Suarez",
        "id": "8e6bbe99-6ab3-409e-ace1-91877f54c5f8",
        "lastName": "Suarez",
        "shirtNumber": 9
      },
      "attemptType": "On target",
      "ballPosition": null,
      "blockersPosition": null,
      "bodyPart": "Right foot",
      "extras": ["Assist"],
      "patternOfPlay": "Regular play",
      "position": { "X": 0.1, "Y": 0.4 },
      "xG": 0.2093
    }
  },
  "parentActionId": null,
  "period": "second",
  "player": {
    "externalId": "MLS-OBJ-0003CX",
    "firstName": "Diego",
    "fullName": "Diego Gomez",
    "id": "7790e4c7-2c24-4f47-ab2e-8f0df9e81116",
    "lastName": "Gomez",
    "shirtNumber": 20
  },
  "seasonId": "d2f17733-371f-4d06-b207-07989ce96eee",
  "stageId": "7c574987-6ff0-4c0b-809c-1d66f20dc5a3",
  "team": {
    "externalId": "MLS-CLU-000008",
    "id": "734bfa38-5ed7-4dcd-90e4-b957e58a7db2",
    "name": "Inter Miami CF"
  },
  "teamPossessionPhaseId": 1226
},
{
  "actionId": "c6022b38-6791-3ec7-b642-a7ff5481e99e",
  "actionTypeId": "47",
  "actionTypeMetadata": "goal",
  "clockTime": "082:55:47",
  "competitionId": "be0b9007-03c3-463b-b22b-27cd871c9b6d",
  "directionOfPlay": "leftToRight",
  "eventId": 610200001226,
  "eventTime": "2024-02-22T02:54:07.718Z",
  "fixtureId": "15f25cc4-6abb-4e31-bb60-d8bc27e8229f",
  "isSuccessful": null,
  "messageId": "8be56b41-5257-4539-babb-1131cffe9c84",
  "metadata": {
    "goal": {
      "assistPlayer": {
        "externalId": "MLS-OBJ-000528",
        "firstName": "Luis",
        "fullName": "Luis Suarez",
        "id": "8e6bbe99-6ab3-409e-ace1-91877f54c5f8",
        "lastName": "Suarez",
        "shirtNumber": 9
      },
      "ballPosition": null,
      "blockersPosition": null,
      "bodyPart": "Right foot",
      "extras": ["Assist"],
      "patternOfPlay": "Regular play",
      "position": { "X": 0.1, "Y": 0.4 }
    }
  },
  "parentActionId": "80ab1098-a543-3658-b622-5bc8bc12d11d",
  "period": "second",
  "player": {
    "externalId": "MLS-OBJ-0003CX",
    "firstName": "Diego",
    "fullName": "Diego Gomez",
    "id": "7790e4c7-2c24-4f47-ab2e-8f0df9e81116",
    "lastName": "Gomez",
    "shirtNumber": 20
  },
  "seasonId": "d2f17733-371f-4d06-b207-07989ce96eee",
  "stageId": "7c574987-6ff0-4c0b-809c-1d66f20dc5a3",
  "team": {
    "externalId": "MLS-CLU-000008",
    "id": "734bfa38-5ed7-4dcd-90e4-b957e58a7db2",
    "name": "Inter Miami CF"
  },
  "teamPossessionPhaseId": 1226
},

```