Match Micro-Events

The Match Event resource lets you access data about the micro-events in a football match, such as ball touches, non-touch events, positional data, and explanatory data related to touch events. Micro-events are modelled as a combination of three components: events, actions, and modifiers.

Events provide top-level data on the micro-event. These data are the following:

  • Match time of the event,
  • The (x,y)-position where the event is located, and
  • The type of action(s) that occurs during the event.

Match time is expressed in terms of the match period and the number of seconds elapsed in the period.

Match Period Description
1 First half
2 Second half
3 First extra time period
4 Second extra time period

The (x,y)-position is expressed in terms of normalized coordinates on a square pitch; i.e., length varies from 0.0 to 100.0 and width from 0.0 to 100.0.

../../_images/normalizedsoccerpitch.png

Actions occur within the micro-event, and there will be at least one action per micro-event. Most actions involve a player touching the ball, but some actions, such as ball out of play or start/end of periods, do not. Actions contain normalized (x,y,z)-positions of the ball at the end of the micro-event, which is only populated when a player touches the ball.

Modifiers provide contextual information to an action that occurs in a micro-event. They describe information such as field region, body part used, foul type, or shot outcome.

All Events

GET /v1/(match_type)/events/all/(ID)

Returns data for all micro events – touch and non-touch – in a football match.

If ID is passed, return data for the micro event that the ID corresponds to.

URL Parameters:

Field Type URL Description
match_type string Match Type.
ID uuid Unique ID of micro event.

Query and Response Parameters:

Field Type Description
id uuid The unique ID of the micro event.
match uuid The unique ID of the football match.
action uuid The unique ID of the match action that occurs within the micro event.
action_type integer The unique ID of the action type.
action_desc string The type of action that occurred in the micro event.
period integer The match period.
match_seconds float The number of seconds elapsed in the match period.
x float The normalized X coordinate on the playing surface where the micro event originated.
y float The normalized Y coordinate on the playing surface where the micro event originated.

Link Parameters:

Field URL Description
actions Event Actions resource representation.
match Match Information resource representation.

Example:

A specific micro-event from a match.

GET /v1/national/events/all/acacae6c26c346ffaed5a7afc56c1f90 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Mon, 21 Jul 2014 01:20:05 GMT
Connection: close
Content-Type: application/json
Content-Length: 1698

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {
      "html": "<a href=\"http://www.pressassociation.com\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/PressAssociation.png\"/></a>",
      "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/PressAssociation.png",
      "name": "Press Association",
      "url": "http://www.pressassociation.com"
    },
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {
    "first": "/v1/national/events/all/acacae6c26c346ffaed5a7afc56c1f90?sort=period%2Cmatch_seconds&records=30&page=1",
    "last": "/v1/national/events/all/acacae6c26c346ffaed5a7afc56c1f90?sort=period%2Cmatch_seconds&records=30&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 30,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "action": "b82dc40f3ecb4b3bb422d12200976bea",
      "actionDesc": "Clearance",
      "actionType": 119,
      "id": "acacae6c26c346ffaed5a7afc56c1f90",
      "link": {
        "actions": "/v1/national/events/actions/b82dc40f3ecb4b3bb422d12200976bea",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchSeconds": 82.0,
      "period": 1,
      "uri": "/v1/national/events/all/acacae6c26c346ffaed5a7afc56c1f90",
      "x": 90.0,
      "y": 64.2857142857143
    }
  ]
}
OPTIONS /v1/(match_type)/events/all

Returns documentation of the match micro-event resource.

Touch Events

GET /v1/(match_type)/events/touches/(ID)

Returns data for all touch events in a football match.

If ID is passed, return data for the micro event that the ID corresponds to.

URL Parameters:

Field Type URL Description
match_type string Match Type.
ID uuid Unique ID of micro event.

Query and Response Parameters:

Field Type Description
id uuid The unique ID of the micro event.
match uuid The unique ID of the football match.
action uuid The unique ID of the match action that occurs within the micro event.
action_type integer The unique ID of the action type.
action_desc string The type of action that occurred in the micro event.
team uuid The unique ID of the player’s team.
teamName string The name of the player’s team.
player uuid The unique ID of the player involved in the touch event.
player_name string The name of the player who was shown a disciplinary card.
period integer The match period.
match_seconds float The number of seconds elapsed in the match period.
x float The normalized X coordinate on the field of play where the micro event originated.
y float The normalized Y coordinate on the field of play where the micro event originated.
xEnd float The normalized X coordinate of the ball on the field of play at the end of micro event.
yEnd float The normalized Y coordinate of the ball on the field of play at the end of micro event.
zEnd float The normalized Z coordinate of the ball on the field of play at the end of micro event.

Link Parameters:

Field URL Description
actions Event Actions resource representation.
match Match Information resource representation.
player Players resource representation.

Example:

A specific touch event from a match.

GET /v1/national/events/touches/f03595de5cbe4556a3b940dc966d2dc8 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Mon, 21 Jul 2014 01:10:22 GMT
Connection: close
Content-Type: application/json
Content-Length: 1958

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {
      "html": "<a href=\"http://www.pressassociation.com\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/PressAssociation.png\"/></a>",
      "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/PressAssociation.png",
      "name": "Press Association",
      "url": "http://www.pressassociation.com"
    },
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {
    "first": "/v1/national/events/touches/f03595de5cbe4556a3b940dc966d2dc8?sort=period%2Cmatch_seconds&records=30&page=1",
    "last": "/v1/national/events/touches/f03595de5cbe4556a3b940dc966d2dc8?sort=period%2Cmatch_seconds&records=30&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 30,
    "totalPages": 1,
    "totalRecords": 4
  },
  "result": [
    {
      "action": "d5d2a6b384ad4ac8b00d2718c51681b4",
      "actionDesc": "Pass",
      "actionType": 102,
      "id": "f03595de5cbe4556a3b940dc966d2dc8",
      "link": {
        "actions": "/v1/national/events/actions/d5d2a6b384ad4ac8b00d2718c51681b4",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "player": "/v1/personnel/players/af0ab889c6c1461889ee092fc1167a9d"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchSeconds": 5.0,
      "outcome": 0,
      "period": 1,
      "player": "af0ab889c6c1461889ee092fc1167a9d",
      "playerName": "Stipe Pletikosa",
      "team": "8a472ca1fac94ee99e0fe28536637946",
      "teamName": "Croatia",
      "uri": "/v1/national/events/touches/f03595de5cbe4556a3b940dc966d2dc8",
      "x": 94.8484848484848,
      "y": 43.3333333333333,
      "xEnd": null,
      "yEnd": null,
      "zEnd": null
    }
  ]
}
OPTIONS /v1/(match_type)/events/touches

Returns documentation of the touch event resource.

Event Actions

GET /v1/(match_type)/events/actions/(ID)

Returns contextual data that describes a match action in a football match.

URL Parameters:

Field Type URL Description
match_type string Match Type.
ID uuid Unique ID of micro event.

Query and Response Parameters:

Field Type Description
id uuid The unique ID of the action modifier.
event uuid The unique ID of the micro-event.
action uuid The unique ID of the match action that occurs within the micro-event.
action_type integer The unique ID of the action type.
action_desc string The type of action that occurred in the micro event.
modifier_type integer The unique ID of the action modifier type.
modifier_category string Description of the action modifier category.
modifier_desc string Description of the action modifier.

Link Parameters:

Field URL Description
event All Events resource representation.

Example:

Contextual data for a specific micro-event from a match.

GET /v1/national/events/actions/cb03e43a520c4a5fafe68adbd938f44d HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Server: gunicorn/18.0
Date: Mon, 21 Jul 2014 04:54:53 GMT
Connection: close
Content-Type: application/json
Content-Length: 3670

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {
      "html": "<a href=\"http://www.pressassociation.com\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/PressAssociation.png\"/></a>",
      "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/PressAssociation.png",
      "name": "Press Association",
      "url": "http://www.pressassociation.com"
    },
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {
    "first": "/v1/national/events/actions?sort=period%2Cmatch_seconds&records=30&page=1&action=cb03e43a520c4a5fafe68adbd938f44d",
    "last": "/v1/national/events/actions?sort=period%2Cmatch_seconds&records=30&page=1&action=cb03e43a520c4a5fafe68adbd938f44d",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 30,
    "totalPages": 1,
    "totalRecords": 5
  },
  "result": [
    {
      "action": "cb03e43a520c4a5fafe68adbd938f44d",
      "actionDesc": "Shot",
      "actionType": 107,
      "event": "869822989cdf45ffae5b21b42243b203",
      "id": "2cf742a0633046ec81de02c5115b2c52",
      "link": {
        "event": "/v1/national/events/all/869822989cdf45ffae5b21b42243b203"
      },
      "modifierCategory": "Shot Result",
      "modifierDesc": "Blocked",
      "modifierType": 185,
      "uri": "/v1/national/events/actions/cb03e43a520c4a5fafe68adbd938f44d"
    },
    {
      "action": "cb03e43a520c4a5fafe68adbd938f44d",
      "actionDesc": "Shot",
      "actionType": 107,
      "event": "869822989cdf45ffae5b21b42243b203",
      "id": "9972cc86ab5b4692aaf9b37cf6518d15",
      "link": {
        "event": "/v1/national/events/all/869822989cdf45ffae5b21b42243b203"
      },
      "modifierCategory": "Shot Type",
      "modifierDesc": "Drilled",
      "modifierType": 156,
      "uri": "/v1/national/events/actions/cb03e43a520c4a5fafe68adbd938f44d"
    },
    {
      "action": "cb03e43a520c4a5fafe68adbd938f44d",
      "actionDesc": "Shot",
      "actionType": 107,
      "event": "869822989cdf45ffae5b21b42243b203",
      "id": "c4a1eab36f134f99811a77d5784276f3",
      "link": {
        "event": "/v1/national/events/all/869822989cdf45ffae5b21b42243b203"
      },
      "modifierCategory": "Shot Direction",
      "modifierDesc": "Wide Left",
      "modifierType": 125,
      "uri": "/v1/national/events/actions/cb03e43a520c4a5fafe68adbd938f44d"
    },
    {
      "action": "cb03e43a520c4a5fafe68adbd938f44d",
      "actionDesc": "Shot",
      "actionType": 107,
      "event": "869822989cdf45ffae5b21b42243b203",
      "id": "8a9c0fe95a4e45638303c71a30fbf250",
      "link": {
        "event": "/v1/national/events/all/869822989cdf45ffae5b21b42243b203"
      },
      "modifierCategory": "Body Part",
      "modifierDesc": "Right Foot",
      "modifierType": 112,
      "uri": "/v1/national/events/actions/cb03e43a520c4a5fafe68adbd938f44d"
    },
    {
      "action": "cb03e43a520c4a5fafe68adbd938f44d",
      "actionDesc": "Shot",
      "actionType": 107,
      "event": "869822989cdf45ffae5b21b42243b203",
      "id": "4e9e32b5a8f14f07af23fd7cf56d7c0b",
      "link": {
        "event": "/v1/national/events/all/869822989cdf45ffae5b21b42243b203"
      },
      "modifierCategory": "Field Sector",
      "modifierDesc": "Left Channel",
      "modifierType": 135,
      "uri": "/v1/national/events/actions/cb03e43a520c4a5fafe68adbd938f44d"
    }
  ]
}
OPTIONS /v1/(match_type)/events/actions

Returns documentation of the event actions resource.