Match Events¶

The Match Event resource lets you access data about the major historical events that occur in a football match – goals, penalties, bookable offenses, and substitutions. All of these events are linked to players who appear in the lineup of a match.

Goals¶

GET /v0/events/goals/(int: ID)¶

Returns data on goal events in football matches. If ID is passed, return data for the goal event the ID corresponds to.

Query and Response Parameters:

Field	Type	Description
matchday	integer	Matchday to which the league match corresponds.
home_team	integer	The unique ID of the home team.
home_team_name	string	The name of the home team.
away_team	integer	The unique ID of the away team.
away_team_name	string	The name of the away team.
scoring_team	integer	The unique ID of the team credited with the goal.
scoring_team_name	string	The name of the team credited with the goal.
player_team	integer	The unique ID of the team of the player who scored the goal.
player_team_name	string	The name of the team of the player who scored the goal.
player	integer	The unique ID of the player who scored the goal.
player_name	string	The name of the player who scored the goal.
shot_event	integer	The unique ID of the shot event that resulted in the goal.
shot_event_type	string	Description of the shot event that resulted in the goal.
bodypart	integer	The unique ID of the body part used to score the goal.
bodypart_name	string	The name of the body part used to score the goal.
time_mins	integer	Time of goal, in minutes of match time.
stoppage_mins	integer	Stoppage time of goal, if applicable, in minutes.

Link Parameters:

Field	URL Description
match	Match Information representation.
player	Players resource representation.
home_team	Home Teams resource representation.
away_team	Away Teams resource representation.

Example #1:

Who scored in the Arsenal vs Everton match?

GET /v0/events/goals?home_team_name=Arsenal&away_team_name=Everton HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Thu, 22 Aug 2013 21:38:36 GMT
Server: gunicorn/0.15.0
Content-Length: 1195
Connection: keep-alive

{
    "meta": {
      "total_pages": 1,
      "records": 10,
      "total_records": 1,
      "page": 1,
      "next": null,
      "first": "/v0/events/goals?away_team_name=Everton&records=10&page=1&home_team_name=Arsenal",
      "last": "/v0/events/goals?away_team_name=Everton&records=10&page=1&home_team_name=Arsenal",
      "prev": null
    },
    "attribution": {
        "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
        "source": {
          "html": "<a href=\"http://www.optasports.com\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png\"/></a>"
          "logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png",
          "url": "http://www.optasports.com",
          "name": "Opta Sports"
        },
        "text": "Powered by Soccermetrics Research",
        "url": "http://www.soccermetrics.net",
        "logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png"
    },
  "result": [
    {
      "scoring_team": 10000,
      "link": {
        "player": "/v0/personnel/players/1000537",
        "home_team": "/v0/teams/10000",
        "away_team": "/v0/teams/10005",
        "match": "/v0/matches/1000141/info"
      },
      "stoppage_mins": 0,
      "away_team_name": "Everton",
      "player": 1000537,
      "scoring_team_name": "Arsenal",
      "bodypart_name": "Left Foot",
      "bodypart": 3,
      "id": 100384,
      "match": 1000141,
      "home_team": 10000,
      "away_team": 10005,
      "player_name": "Robin van Persie",
      "home_team_name": "Arsenal",
      "player_team": 10000,
      "shot_event": 25,
      "player_team_name": "Arsenal",
      "matchday": 15,
      "time_mins": 70,
      "uri": "/v0/events/goals/100384",
      "shot_event_type": "Shot outside goal area"
    }
  ]
}

Example #2:

A rather famous final goal of the 2011-12 Premier League season.

GET /v0/events/goals/100974 HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Thu, 22 Aug 2013 22:21:54 GMT
Server: gunicorn/0.15.0
Content-Length: 1156
Connection: keep-alive

{
    "meta": {
      "total_pages": 1,
      "records": 10,
      "total_records": 1,
      "page": 1,
      "next": null,
      "first": "/v0/events/goals/100974?records=10&page=1",
      "last": "/v0/events/goals/100974?records=10&page=1",
      "prev": null
    },
    "attribution": {
        "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
        "source": {
          "html": "<a href=\"http://www.optasports.com\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png\"/></a>"
          "logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png",
          "url": "http://www.optasports.com",
          "name": "Opta Sports"
        },
        "text": "Powered by Soccermetrics Research",
        "url": "http://www.soccermetrics.net",
        "logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png"
    },
  "result": [
    {
      "scoring_team": 10008,
      "link": {
        "player": "/v0/personnel/players/1000008",
        "home_team": "/v0/teams/10008",
        "away_team": "/v0/teams/10012",
        "match": "/v0/matches/1000373/info"
      },
      "stoppage_mins": 4,
      "away_team_name": "Queens Park Rangers",
      "player": 1000008,
      "scoring_team_name": "Manchester City",
      "bodypart_name": "Right Foot",
      "bodypart": 4,
      "id": 100974,
      "match": 1000373,
      "home_team": 10008,
      "away_team": 10012,
      "player_name": "Sergio Ag\u00fcero",
      "home_team_name": "Manchester City",
      "player_team": 10008,
      "shot_event": 25,
      "player_team_name": "Manchester City",
      "matchday": 38,
      "time_mins": 90,
      "uri": "/v0/events/goals/100974",
      "shot_event_type": "Shot outside goal area"
    }
  ]
}

OPTIONS /v0/events/goals¶: Returns documentation of the goal event resource.

Penalties¶

GET /v0/events/penalties/(int: ID)¶

Returns data on penalty kick events in football matches. If ID is passed, return data for the penalty kick event the ID corresponds to.

Note

This resource does NOT apply to penalty kick shootouts.

Query and Response Parameters:

Field	Type	Description
matchday	integer	Matchday to which the league match corresponds.
home_team	integer	The unique ID of the home team.
home_team_name	string	The name of the home team.
away_team	integer	The unique ID of the away team.
away_team_name	string	The name of the away team.
player_team	integer	The unique ID of the team that was awarded the penalty kick.
player_team_name	string	The name of the team that was awarded the penalty kick.
player	integer	The unique ID of the player who took the penalty kick.
player_name	string	The name of the player who took the penalty kick.
foul	integer	The unique ID of the foul that resulted in the penalty kick.
foul_type	string	The description of the foul that resulted in the penalty kick.
outcome	integer	The unique ID of the penalty kick outcome.
outcome_type	string	The description of the penalty kick outcome.
time_mins	integer	Time of penalty, in minutes of match time.
stoppage_mins	integer	Stoppage time of penalty, if applicable, in minutes.

Link Parameters:

Field	URL Description
match	Match Information representation.
player	Players resource representation.
home_team	Home Teams resource representation.
away_team	Away Teams resource representation.

OPTIONS /v0/events/penalties¶: Returns documentation of the penalty kick event resource.

Offenses¶

GET /v0/events/offenses/(int: ID)¶

Returns data on on-field disciplinary events in football matches. If ID is passed, return data for the disciplinary event the ID corresponds to.

Only the actions of on-field players are captured by the database; cards shown to substitutes, managers, and other bench officials are not recorded.

Query and Response Parameters:

Field	Type	Description
matchday	integer	Matchday to which the league match corresponds.
home_team	integer	The unique ID of the home team.
home_team_name	string	The name of the home team.
away_team	integer	The unique ID of the away team.
away_team_name	string	The name of the away team.
player_team	integer	The unique ID of the team whose player was shown a disciplinary card.
player_team_name	string	The name of the team whose player was shown a disciplinary card.
player	integer	The unique ID of the player who was shown a disciplinary card.
player_name	string	The name of the player who was shown a disciplinary card.
foul	integer	The unique ID of the foul that resulted in a disciplinary card being shown.
foul_type	string	The description of the foul that resulted in a disciplinary card being shown.
card	integer	The unique ID of the disciplinary card.
card_type	string	The description of type of disciplinary card shown.
time_mins	integer	Time of offense, in minutes of match time.
stoppage_mins	integer	Stoppage time of offense, if applicable, in minutes.

Link Parameters:

Field	URL Description
match	Match Information representation.
player	Players resource representation.
home_team	Home Teams resource representation.
away_team	Away Teams resource representation.

Example:

Retrieve all of the bookable offenses in a specific match.

GET /v0/events/offenses?match=1000300 HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 23 Aug 2013 00:58:33 GMT
Server: gunicorn/0.15.0
Content-Length: 1810
Connection: keep-alive

{
  "meta": {
    "total_pages": 1,
    "records": 10,
    "total_records": 2,
    "page": 1,
    "next": null,
    "first": "/v0/events/offenses?records=10&page=1&match=1000300",
    "last": "/v0/events/offenses?records=10&page=1&match=1000300",
    "prev": null
  },
  "attribution": {
      "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
      "source": {
        "html": "<a href=\"http://www.optasports.com\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png\"/></a>"
        "logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png",
        "url": "http://www.optasports.com",
        "name": "Opta Sports"
      },
      "text": "Powered by Soccermetrics Research",
      "url": "http://www.soccermetrics.net",
      "logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png"
  },
  "result": [
    {
      "away_team_name": "Sunderland",
      "player": 1000182,
      "foul": 19,
      "time_mins": 40,
      "player_team_name": "Sunderland",
      "player_name": "Craig Gardner",
      "stoppage_mins": 0,
      "link": {
        "player": "/v0/personnel/players/1000182",
        "home_team": "/v0/teams/10008",
        "match": "/v0/matches/1000300/info",
        "away_team": "/v0/teams/10014"
      },
      "foul_type": "Dissent",
      "matchday": 31,
      "home_team": 10008,
      "away_team": 10014,
      "card_type": "Yellow",
      "home_team_name": "Manchester City",
      "match": 1000300,
      "card": 1,
      "id": 101011,
      "player_team": 10014,
      "uri": "/v0/events/offenses/101011"
    },
    {
      "away_team_name": "Sunderland",
      "player": 1000532,
      "foul": 16,
      "time_mins": 56,
      "player_team_name": "Manchester City",
      "player_name": "Nigel de Jong",
      "stoppage_mins": 0,
      "link": {
        "player": "/v0/personnel/players/1000532",
        "home_team": "/v0/teams/10008",
        "match": "/v0/matches/1000300/info",
        "away_team": "/v0/teams/10014"
      },
      "foul_type": "Reckless challenge",
      "matchday": 31,
      "home_team": 10008,
      "away_team": 10014,
      "card_type": "Yellow",
      "home_team_name": "Manchester City",
      "match": 1000300,
      "card": 1,
      "id": 101012,
      "player_team": 10008,
      "uri": "/v0/events/offenses/101012"
    }
  ]
}

OPTIONS /v0/events/offenses¶: Returns documentation of the disciplinary event resource.

Substitutions¶

GET /v0/events/substitutions/(int: ID)¶

Returns data on substitution events in football matches. If ID is passed, return data for the substitution event the ID corresponds to.

It is also possible for a player to be retired from the match with his team having used all their allotted substitutions. In that case the incoming player fields (name and ID) would be null.

Query and Response Parameters:

Field	Type	Description
matchday	integer	Matchday to which the league match corresponds.
home_team	integer	The unique ID of the home team.
home_team_name	string	The name of the home team.
away_team	integer	The unique ID of the away team.
away_team_name	string	The name of the away team.
team	integer	The unique ID of the team making a substitution.
team_name	string	The name of the team making a substitution.
in_player	integer	The unique ID of the player substituted into the match. Is null if no player was substituted into the match.
in_player_name	string	The name of the player substituted into the match. Is null if no player was substituted into the match.
out_player	integer	The unique ID of the player substituted out of the match.
out_player_name	string	The name of the player substituted out of the match.
time_mins	integer	Time of substitution, in minutes of match time.
stoppage_mins	integer	Stoppage time of substitution if applicable, in minutes.

Link Parameters:

Field	URL Description
match	Match Information resource representation.
home_team	Home Teams resource representation.
away_team	Away Teams resource representation.
in_player	Incoming Players resource representation.
out_player	Outgoing Players resource representation.

Example:

Retrieve all of the substitutions in a specific match.

GET /v0/events/substitutions?match=1000300 HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Fri, 23 Aug 2013 01:01:55 GMT
Server: gunicorn/0.15.0
Content-Length: 4235
Connection: keep-alive

{
  "meta": {
    "total_pages": 1,
    "records": 10,
    "total_records": 5,
    "page": 1,
    "next": null,
    "first": "/v0/events/substitutions?records=10&page=1&match=1000300",
    "last": "/v0/events/substitutions?records=10&page=1&match=1000300",
    "prev": null
  },
  "attribution": {
      "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
      "source": {
        "html": "<a href=\"http://www.optasports.com\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png\"/></a>"
        "logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png",
        "url": "http://www.optasports.com",
        "name": "Opta Sports"
      },
      "text": "Powered by Soccermetrics Research",
      "url": "http://www.soccermetrics.net",
      "logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png"
  },
  "result": [
    {
      "away_team_name": "Sunderland",
      "out_player": 1000447,
      "in_player": 1000490,
      "time_mins": 58,
      "stoppage_mins": 0,
      "in_player_name": "Carlos T\u00e9vez",
      "matchday": 31,
      "home_team": 10008,
      "away_team": 10014,
      "home_team_name": "Manchester City",
      "match": 1000300,
      "team_name": "Manchester City",
      "out_player_name": "David Silva",
      "team": 10008,
      "id": 101606,
      "link": {
        "home_team": "/v0/teams/10008",
        "match": "/v0/matches/1000300/info",
        "away_team": "/v0/teams/10014",
        "in_player": "/v0/personnel/players/1000490",
        "out_player": "/v0/personnel/players/1000447"
      },
      "uri": "/v0/events/substitutions/101606"
    },
    {
      "away_team_name": "Sunderland",
      "out_player": 1000339,
      "in_player": 1000388,
      "time_mins": 81,
      "stoppage_mins": 0,
      "in_player_name": "David Pizarro",
      "matchday": 31,
      "home_team": 10008,
      "away_team": 10014,
      "home_team_name": "Manchester City",
      "match": 1000300,
      "team_name": "Manchester City",
      "out_player_name": "James Milner",
      "team": 10008,
      "id": 101607,
      "link": {
        "home_team": "/v0/teams/10008",
        "match": "/v0/matches/1000300/info",
        "away_team": "/v0/teams/10014",
        "in_player": "/v0/personnel/players/1000388",
        "out_player": "/v0/personnel/players/1000339"
      },
      "uri": "/v0/events/substitutions/101607"
    },
    {
      "away_team_name": "Sunderland",
      "out_player": 1000403,
      "in_player": 1000002,
      "time_mins": 46,
      "stoppage_mins": 0,
      "in_player_name": "Adam Johnson",
      "matchday": 31,
      "home_team": 10008,
      "away_team": 10014,
      "home_team_name": "Manchester City",
      "match": 1000300,
      "team_name": "Manchester City",
      "out_player_name": "Micah Richards",
      "team": 10008,
      "id": 101605,
      "link": {
        "home_team": "/v0/teams/10008",
        "match": "/v0/matches/1000300/info",
        "away_team": "/v0/teams/10014",
        "in_player": "/v0/personnel/players/1000002",
        "out_player": "/v0/personnel/players/1000403"
      },
      "uri": "/v0/events/substitutions/101605"
    },
    {
      "away_team_name": "Sunderland",
      "out_player": 1000081,
      "in_player": 1000492,
      "time_mins": 90,
      "stoppage_mins": 3,
      "in_player_name": "David Vaughan",
      "matchday": 31,
      "home_team": 10008,
      "away_team": 10014,
      "home_team_name": "Manchester City",
      "match": 1000300,
      "team_name": "Sunderland",
      "out_player_name": "Lee Cattermole",
      "team": 10014,
      "id": 101609,
      "link": {
        "home_team": "/v0/teams/10008",
        "match": "/v0/matches/1000300/info",
        "away_team": "/v0/teams/10014",
        "in_player": "/v0/personnel/players/1000492",
        "out_player": "/v0/personnel/players/1000081"
      },
      "uri": "/v0/events/substitutions/101609"
    },
    {
      "away_team_name": "Sunderland",
      "out_player": 1000283,
      "in_player": 1000294,
      "time_mins": 81,
      "stoppage_mins": 0,
      "in_player_name": "Sotirios Kyrgiakos",
      "matchday": 31,
      "home_team": 10008,
      "away_team": 10014,
      "home_team_name": "Manchester City",
      "match": 1000300,
      "team_name": "Sunderland",
      "out_player_name": "Matthew Kilgallon",
      "team": 10014,
      "id": 101608,
      "link": {
        "home_team": "/v0/teams/10008",
        "match": "/v0/matches/1000300/info",
        "away_team": "/v0/teams/10014",
        "in_player": "/v0/personnel/players/1000294",
        "out_player": "/v0/personnel/players/1000283"
      },
      "uri": "/v0/events/substitutions/101608"
    }
  ]
}

OPTIONS /v0/events/substitutions¶: Returns documentation of the substitution event resource.