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
We recommend the following frequency for your REST requests to ensure that you have the most up-to-date information at all times:
Every 30 seconds for media usage
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
Field Name
Type
Description
actionId
alpha numeric
actionId is a composite key of matchId , eventId and actionType
actionTypeId
int
The ID of the actionType (Pass, Shot..)
actionTypeMetadata
string
Type of metadata contained in packet (Pass, Shot, Save..)
clockTime
dateTime
The clock time within the match fixture (001:39:23) means 1 minute 39 seconds into the match
competitionId
alpha numeric
The ID of the competition (i.e. MLS or MLS Cup)
directionOfPlay
string
Determined at start of period of play (first half, second half, etc)
Specifies what direction the team is playing - whether rightToLeft or leftToRight
eventId
number
The ID of the event within the match
eventTime
UTC dateTime
The timestamp of the event which differs from clockTime, for example:
(2024-02-22T01:10:28.953Z)
fixtureId
alpha numeric
The MLS Fixture ID
isSuccessful
boolean
Setting isSuccessful conditionally if the action resulted in a successful completion (successful pass, successful shot on goal)
messageId
alpha numeric
messageId is a unique ID for each produced packet
metadata object { }
object array
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.
targetPosition
Key Value Pair Object Array
The XY position of the target of this action
Parent action Id object
Field Name
Type
Description
parentActionId
string
One EventId may map to several packets, this field maps to the predecessor packet
The first packet will have no parentActionId
For example SuccessfulShot will create two SPS packets shot and goal
shot will have no parent
goal parent will map to shot actionId
period
string
(first half, second half)
player object { }
object array
This is an array consisting of high level data around the player who provided the preceding action, including name, id, shirt number
seasonId
alpha numeric
The ID of the MLS season
stageId
alpha numeric
The stage ID within the season/event (Semi final of cup), (last game of the regular season)
team object { }
object array
This is an array consisting of high level data around the team in possession
teamPossessionPhaseId
int
This describes the phase of play and is an incrementing value according ballPossessionPhase
Not necessarily inline with time the event occurred
Actions List (Described in 'actionTypeMetadata' object)
All Event Action types that are returned from the endpoint
Sample Response Extracts
Last updated