Match Macro-Events

The Match Macro-Events resources let you access data about high-level match information, environmental conditions, and match lineups, as well as high-level events that occur in a football match such as goals, penalties, bookable offenses, and substitutions. All of these macro-events are linked to players who appear in the lineup of a match.

We organize match data by the phase of the competition in which they occur. Here are the phases that we use along with their descriptions and a couple of examples:

Competition Phase Description Parameters Examples
League A long-term competition in which teams play each other (typically home and away) over multiple matchdays. matchday Football League, Major League Soccer regular season, Brasileirão
Group A short-term competition similar to a league format, but with a reduced number of teams and matchdays. round_name, group, matchday UEFA Champions League group stage, FIFA World Cup group stage
Knockout A competition played over successive rounds, in which each fixture is over played over single or multiple matches. round_name, matchday FA Cup, League Cup, MLS Cup Playoffs, FIFA World Cup knockout stage

To search for matches within a competition, you must include phase details to the query parameters in the URL. There is a minimum set of parameters that must be passed in order to query certain phases of a football competition.

Query Parameters Passed Filter Applied
matchday League Matches
round name, group Group Matches
round name Knockout Matches

Information

GET /v1/(match_type)/matches/(matchID)/info

Returns high-level data related to a football match.

If matchID is passed, return data for the match that the ID corresponds to.

If query parameters are passed, return match data that match the specified filters.

Inject phase-specific data into every record of the response.

The match information resource is a central resource in the Connect API, as it contains hyperlinks to events (micro and macro) and analytics, as well as personnel, venues, and teams involved.

URL Parameters:

Field Type URL Description
match_type string Match Type.
matchID uuid Unique ID of football match.

Query and Response Parameters:

Field Type Description
competition uuid The unique ID of competition to which the match corresponds.
competition_name string Name of competition.
season integer The unique ID of season to which the match corresponds.
season_name string Season year(s).
phase integer The unique ID of competition phase to which the match corresponds.
phase_name string Competition phase.
home_team uuid The unique ID of the home team.
home_team_name string The name of the home team.
away_team uuid The unique ID of the away team.
away_team_name string The name of the away team.
home_manager uuid The unique ID of the manager of the home team.
home_manager_name string The name of the manager of the home team.
away_manager uuid The unique ID of the manager of the away team.
away_manager_name string The name of the manager of the away team.
referee uuid The unique ID of the referee who began officiating the match.
referee_name string Full name of the referee.
venue uuid The unique ID of the venue where the match was played.
venue_name string The name of the match venue.
match_date date The date of the match, in ISO format (YYYY-MM-DD).
kickoff_time time The time of the match kick-off, in 24-hr format (HH:MM).
firsthalf_length integer Length of the first half in minutes.
secondhalf_length integer Length of the second half in minutes.
firstextra_length integer Length of the first extra period in minutes.
secondextra_length integer Length of the second extra period in minutes.
attendance integer The estimated attendance at the match.

League Match Query and Response Parameters:

Field Type Description
matchday integer Matchday to which the league match corresponds.

Group Match Query and Response Parameters:

Field Type Description
round integer Unique ID of the group stage round.
round_name string Name of the group stage round.
group string Name of group to which the group match corresponds.
matchday integer Matchday to which the group match corresponds.

Knockout Match Query and Response Parameters:

Field Type Description
round integer Unique ID of the knockout stage round.
round_name string Name of the knockout stage round.
matchday integer Matchday to which the knockout match corresponds.

Link Parameters:

Field URL Description
venue Match Venues resource representation.
conditions Match Conditions resource representation.
homeTeam Home Team resource representation, club or national team.
awayTeam Away Team resource representation, club or national team.
homeManager Home Managers resource representation.
awayManager Away Managers resource representation.
lineups Match lineups resource representation.
goals Match goals resource representation.
offenses Match bookable offenses resource representation.
penalties Match penalties resource representation.
substitutions Match substitutions resource representation.
referee Match Referees resource representation.
events Match Micro-Events resource representations.
stats Match Statistics resource representations.
analytics Match Analytics resource representations.

Example:

Retrieve high-level information on a specific match.

GET /v1/matches/9649f4994bf2440b8870d6031815fe65/info HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Server: gunicorn/18.0
Date: Sat, 19 Jul 2014 19:49:52 GMT
Connection: close
Content-Type: application/json
Content-Length: 7475
Access-Control-Allow-Origin: *

{
  "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/matches/9649f4994bf2440b8870d6031815fe65/info?records=10&page=1",
    "last": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "attendance": 62103,
      "awayManager": "db04263a62e9468aa3db0d8693d91d1c",
      "awayManagerName": "Niko Kova\u010d",
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "competition": "3f062dd43b8c4f4895bdffc3f5c00467",
      "competitionName": "FIFA World Cup",
      "firstextraLength": null,
      "firsthalfLength": 0,
      "group": "A",
      "homeManager": "7e9dc4c848ba442c8b05f30601e2d0b8",
      "homeManagerName": "Luiz Scolari",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "9649f4994bf2440b8870d6031815fe65",
      "kickoffTime": "17:00:00",
      "link": {
        "analytics": {
          "match": {
            "segments": "/v1/analytics/match/9649f4994bf2440b8870d6031815fe65/segments",
            "state": "/v1/analytics/match/9649f4994bf2440b8870d6031815fe65/state",
            "tsr": "/v1/analytics/match/9649f4994bf2440b8870d6031815fe65/tsr"
          }
        },
        "awayManager": "/v1/personnel/managers/db04263a62e9468aa3db0d8693d91d1c",
        "awayTeam": "/v1/countries/8a472ca1fac94ee99e0fe28536637946",
        "conditions": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/conditions",
        "events": {
          "actions": "/v1/national/events/actions?match=9649f4994bf2440b8870d6031815fe65",
          "all": "/v1/national/events/all?match=9649f4994bf2440b8870d6031815fe65",
          "touches": "/v1/national/events/touches?match=9649f4994bf2440b8870d6031815fe65"
        },
        "goals": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/goals",
        "homeManager": "/v1/personnel/managers/7e9dc4c848ba442c8b05f30601e2d0b8",
        "homeTeam": "/v1/countries/70ce7b6218a24e1d94c21ed8b5cd070c",
        "lineups": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/lineups",
        "offenses": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/offenses",
        "penalties": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/penalties",
        "referee": "/v1/personnel/referees/01928f7214a74408b382ecabcc95c922",
        "stats": {
          "crosses": {
            "corners": "/v1/national/stats/crosses/corners?match=9649f4994bf2440b8870d6031815fe65",
            "totals": "/v1/national/stats/crosses/totals?match=9649f4994bf2440b8870d6031815fe65"
          },
          "defense": {
            "actions": "/v1/national/stats/defense/actions?match=9649f4994bf2440b8870d6031815fe65",
            "blocks": "/v1/national/stats/defense/blocks?match=9649f4994bf2440b8870d6031815fe65",
            "clearances": "/v1/national/stats/defense/clearances?match=9649f4994bf2440b8870d6031815fe65",
            "goalline": "/v1/national/stats/defense/goalline?match=9649f4994bf2440b8870d6031815fe65",
            "tackles": "/v1/national/stats/defense/tackles?match=9649f4994bf2440b8870d6031815fe65"
          },
          "fouls": {
            "cards": "/v1/national/stats/fouls/cards?match=9649f4994bf2440b8870d6031815fe65",
            "wins": "/v1/national/stats/fouls/wins?match=9649f4994bf2440b8870d6031815fe65"
          },
          "goalkeeper": {
            "actions": "/v1/national/stats/goalkeeper/actions?match=9649f4994bf2440b8870d6031815fe65",
            "goals": "/v1/national/stats/goalkeeper/goals?match=9649f4994bf2440b8870d6031815fe65",
            "saves": "/v1/national/stats/goalkeeper/saves?match=9649f4994bf2440b8870d6031815fe65",
            "shots": "/v1/national/stats/goalkeeper/shots?match=9649f4994bf2440b8870d6031815fe65"
          },
          "goals": {
            "assists": "/v1/national/stats/goals/assists?match=9649f4994bf2440b8870d6031815fe65",
            "bodyparts": "/v1/national/stats/goals/bodyparts?match=9649f4994bf2440b8870d6031815fe65",
            "locations": "/v1/national/stats/goals/locations?match=9649f4994bf2440b8870d6031815fe65",
            "penalties": "/v1/national/stats/goals/penalties?match=9649f4994bf2440b8870d6031815fe65",
            "totals": "/v1/national/stats/goals/totals?match=9649f4994bf2440b8870d6031815fe65"
          },
          "passes": {
            "directions": "/v1/national/stats/passes/directions?match=9649f4994bf2440b8870d6031815fe65",
            "lengths": "/v1/national/stats/passes/lengths?match=9649f4994bf2440b8870d6031815fe65",
            "locations": "/v1/national/stats/passes/locations?match=9649f4994bf2440b8870d6031815fe65",
            "totals": "/v1/national/stats/passes/totals?match=9649f4994bf2440b8870d6031815fe65"
          },
          "setpieces": {
            "corners": "/v1/national/stats/setpieces/corners?match=9649f4994bf2440b8870d6031815fe65",
            "freekicks": "/v1/national/stats/setpieces/freekicks?match=9649f4994bf2440b8870d6031815fe65",
            "throwins": "/v1/national/stats/setpieces/throwins?match=9649f4994bf2440b8870d6031815fe65"
          },
          "shots": {
            "bodyparts": "/v1/national/stats/shots/bodyparts?match=9649f4994bf2440b8870d6031815fe65",
            "locations": "/v1/national/stats/shots/locations?match=9649f4994bf2440b8870d6031815fe65",
            "plays": "/v1/national/stats/shots/plays?match=9649f4994bf2440b8870d6031815fe65",
            "totals": "/v1/national/stats/shots/totals?match=9649f4994bf2440b8870d6031815fe65"
          },
          "touches": {
            "duels": "/v1/national/stats/touches/duels?match=9649f4994bf2440b8870d6031815fe65",
            "locations": "/v1/national/stats/touches/locations?match=9649f4994bf2440b8870d6031815fe65",
            "totals": "/v1/national/stats/touches/totals?match=9649f4994bf2440b8870d6031815fe65"
          }
        },
        "substitutions": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/substitutions",
        "venue": "/v1/venues/8a7f4c27f12045638bcba2552747fb8b"
      },
      "matchDate": "2014-06-12",
      "matchday": 1,
      "phase": 2,
      "phaseName": "Group",
      "referee": "01928f7214a74408b382ecabcc95c922",
      "refereeName": "Yuichi Nishimura",
      "round": 1,
      "roundName": "Group Stage",
      "season": 101,
      "seasonName": "2014",
      "secondextraLength": null,
      "secondhalfLength": 0,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
      "venue": "8a7f4c27f12045638bcba2552747fb8b",
      "venueName": "Arena Corinthians"
    }
  ]
}
OPTIONS /v1/(match_type)/matches/info

Returns documentation of the match information resource.

Conditions

GET /v1/(match_type)/matches/(matchID)/conditions

Returns data on climatic conditions present during a football match. If matchID is passed, return data for the match the ID corresponds to.

If query parameters are passed, it returns the matches that match the specified filters.

Warning

At this time the Conditions resource cannot be filtered by competition phase details.

URL Parameters:

Field Type URL Description
match_type string Match Type.
matchID uuid Unique ID of football match.

Query and Response Parameters:

Field Type Description
id uuid The unique ID of the match condition record.
match uuid The unique ID of the football match.
kickoff_temp float The temperature at kickoff in degrees Celsius.
kickoff_humidity float The relative humidity at kickoff.
kickoff_weather integer The unique ID of the predominate weather condition at kickoff.
kickoff_weather_conditions string US NOAA/NWS description of predominate weather condition at kickoff.
halftime_weather integer The unique ID of the predominate weather condition at halftime.
halftime_weather_conditions string US NOAA/NWS description of predominate weather condition at halftime.
fulltime_weather integer The unique ID of the predominate weather condition at fulltime.
fulltime_weather_conditions string US NOAA/NWS description of predominate weather condition at fulltime.

Link Parameters:

Field URL Description
match Match Information resource representation.

Example:

Retrieve the weather conditions that a match was played in.

GET /v1/match/9649f4994bf2440b8870d6031815fe65/conditions 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: Sat, 19 Jul 2014 20:11:42 GMT
Connection: close
Content-Type: application/json
Content-Length: 1620

{
  "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/matches/9649f4994bf2440b8870d6031815fe65/conditions?records=10&page=1",
    "last": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/conditions?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "fulltimeWeather": 10,
      "fulltimeWeatherCondition": "Clear",
      "halftimeWeather": 10,
      "halftimeWeatherCondition": "Clear",
      "id": "7552d6aab8bf4dfb9d3e0f06c440e1d6",
      "kickoffHumidity": 65.0,
      "kickoffTemp": 20.0,
      "kickoffWeather": 10,
      "kickoffWeatherCondition": "Clear",
      "link": {
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/conditions"
    }
  ]
}
OPTIONS /v1/(match_type)/matches/conditions

Returns documentation of the match conditions resource.

Lineups

GET /v1/(match_type)/matches/(matchID)/lineups/(ID)

Returns data on players in the lineup of a football match. They are designated as either starting or substitute, with a further designation for team captain.

If matchID is passed, return lineup data for the match the ID corresponds to.

To retrieve lineup data for a specific player in a match, both matchID and ID must be passed.

If query parameters are passed, return lineup data that satisfy the specified filters.

Inject phase-specific data into every record of the response.

Note

In general, unused substitutes are not included in the match lineup.

URL Parameters:

Field Type URL Description
match_type string Match Type.
matchID uuid Unique ID of football match.
ID uuid Unique ID of lineup record.

Query and Response Parameters:

Field Type Description
phase integer The unique ID of competition phase to which the match corresponds.
phase_name string Competition phase.
match uuid The unique ID of the football match.
home_team uuid The unique ID of the home team.
home_team_name string The name of the home team.
away_team uuid The unique ID of the away team.
away_team_name string The name of the away team.
player_team uuid The unique ID of the player’s team.
player_team_name string The name of the player’s team.
player uuid The unique ID of the player in the match lineup.
player_name string The name of the player in the match lineup.
position integer The unique ID of the player’s default position.
position_name string The name of the generic field position.
is_starting bool Flag to indicate whether the player started.
is_captain bool Flag to indicate whether the player was named captain.

League Match Query and Response Parameters:

See link in Match Information resource.

Group Match Query and Response Parameters:

See link in Match Information resource.

Knockout Match Query and Response Parameters:

See link in Match Information resource.

Link Parameters:

Field URL Description
match Match Information resource representation.
player Players resource representation.
homeTeam Home Team resource representation, club or national team.
awayTeam Away Team resource representation, club or national team.
stats Match Statistics resource representations.

Example:

Retrieve the starting strikers for one of the sides of a football match.

GET /v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/lineups?is_starting=true&player_team_name=Ecuador&position_name=Striker HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Server: gunicorn/18.0
Date: Sun, 20 Jul 2014 04:45:03 GMT
Connection: close
Content-Type: application/json
Content-Length: 10255
Access-Control-Allow-Origin: *

{
  "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/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/lineups?records=10&is_starting=true&player_team_name=Ecuador&position_name=Striker&page=1",
    "last": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/lineups?records=10&is_starting=true&player_team_name=Ecuador&position_name=Striker&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 2
  },
  "result": [
    {
      "awayTeam": "3ba4718255c54a96802814a827374dc1",
      "awayTeamName": "Ecuador",
      "group": "E",
      "homeTeam": "67b2c02d283e4bd78a23554ee0a331ae",
      "homeTeamName": "Honduras",
      "id": "4da65afde55545c2abca45c7f14d3091",
      "isCaptain": null,
      "isStarting": true,
      "link": {
        "awayTeam": "/v1/teams/3ba4718255c54a96802814a827374dc1",
        "homeTeam": "/v1/teams/67b2c02d283e4bd78a23554ee0a331ae",
        "match": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/info",
        "player": "/v1/personnel/players/7de4183c5df4409cab20ad569c151709",
        "stats": {
          "crosses": {
            "corners": "/v1/national/stats/crosses/corners/4da65afde55545c2abca45c7f14d3091",
            "totals": "/v1/national/stats/crosses/totals/4da65afde55545c2abca45c7f14d3091"
          },
          "defense": {
            "actions": "/v1/national/stats/defense/actions/4da65afde55545c2abca45c7f14d3091",
            "blocks": "/v1/national/stats/defense/blocks/4da65afde55545c2abca45c7f14d3091",
            "clearances": "/v1/national/stats/defense/clearances/4da65afde55545c2abca45c7f14d3091",
            "goalline": "/v1/national/stats/defense/goalline/4da65afde55545c2abca45c7f14d3091",
            "tackles": "/v1/national/stats/defense/tackles/4da65afde55545c2abca45c7f14d3091"
          },
          "fouls": {
            "cards": "/v1/national/stats/fouls/cards/4da65afde55545c2abca45c7f14d3091",
            "wins": "/v1/national/stats/fouls/wins/4da65afde55545c2abca45c7f14d3091"
          },
          "goalkeeper": {
            "actions": "/v1/national/stats/goalkeeper/actions/4da65afde55545c2abca45c7f14d3091",
            "goals": "/v1/national/stats/goalkeeper/goals/4da65afde55545c2abca45c7f14d3091",
            "saves": "/v1/national/stats/goalkeeper/saves/4da65afde55545c2abca45c7f14d3091",
            "shots": "/v1/national/stats/goalkeeper/shots/4da65afde55545c2abca45c7f14d3091"
          },
          "goals": {
            "assists": "/v1/national/stats/goals/assists/4da65afde55545c2abca45c7f14d3091",
            "bodyparts": "/v1/national/stats/goals/bodyparts/4da65afde55545c2abca45c7f14d3091",
            "locations": "/v1/national/stats/goals/locations/4da65afde55545c2abca45c7f14d3091",
            "penalties": "/v1/national/stats/goals/penalties/4da65afde55545c2abca45c7f14d3091",
            "totals": "/v1/national/stats/goals/totals/4da65afde55545c2abca45c7f14d3091"
          },
          "passes": {
            "directions": "/v1/national/stats/passes/directions/4da65afde55545c2abca45c7f14d3091",
            "lengths": "/v1/national/stats/passes/lengths/4da65afde55545c2abca45c7f14d3091",
            "locations": "/v1/national/stats/passes/locations/4da65afde55545c2abca45c7f14d3091",
            "totals": "/v1/national/stats/passes/totals/4da65afde55545c2abca45c7f14d3091"
          },
          "setpieces": {
            "corners": "/v1/national/stats/setpieces/corners/4da65afde55545c2abca45c7f14d3091",
            "freekicks": "/v1/national/stats/setpieces/freekicks/4da65afde55545c2abca45c7f14d3091",
            "throwins": "/v1/national/stats/setpieces/throwins/4da65afde55545c2abca45c7f14d3091"
          },
          "shots": {
            "bodyparts": "/v1/national/stats/shots/bodyparts/4da65afde55545c2abca45c7f14d3091",
            "locations": "/v1/national/stats/shots/locations/4da65afde55545c2abca45c7f14d3091",
            "plays": "/v1/national/stats/shots/plays/4da65afde55545c2abca45c7f14d3091",
            "totals": "/v1/national/stats/shots/totals/4da65afde55545c2abca45c7f14d3091"
          },
          "touches": {
            "duels": "/v1/national/stats/touches/duels/4da65afde55545c2abca45c7f14d3091",
            "locations": "/v1/national/stats/touches/locations/4da65afde55545c2abca45c7f14d3091",
            "totals": "/v1/national/stats/touches/totals/4da65afde55545c2abca45c7f14d3091"
          }
        }
      },
      "match": "e2e9eb3dc9984dcd8e4328e138a7fd5d",
      "matchday": 2,
      "number": 11,
      "phase": 2,
      "phaseName": "Group",
      "player": "7de4183c5df4409cab20ad569c151709",
      "playerName": "Felipe Caicedo",
      "playerTeam": "3ba4718255c54a96802814a827374dc1",
      "playerTeamName": "Ecuador",
      "position": 27,
      "positionName": "Striker",
      "round": 1,
      "roundName": "Group Stage",
      "uri": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/lineups/4da65afde55545c2abca45c7f14d3091"
    },
    {
      "awayTeam": "3ba4718255c54a96802814a827374dc1",
      "awayTeamName": "Ecuador",
      "group": "E",
      "homeTeam": "67b2c02d283e4bd78a23554ee0a331ae",
      "homeTeamName": "Honduras",
      "id": "bfad6825d1794f7aba32d9adaad1c751",
      "isCaptain": null,
      "isStarting": true,
      "link": {
        "awayTeam": "/v1/teams/3ba4718255c54a96802814a827374dc1",
        "homeTeam": "/v1/teams/67b2c02d283e4bd78a23554ee0a331ae",
        "match": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/info",
        "player": "/v1/personnel/players/5e4b49d4cfb14b9da7f1411db6d6a420",
        "stats": {
          "crosses": {
            "corners": "/v1/national/stats/crosses/corners/bfad6825d1794f7aba32d9adaad1c751",
            "totals": "/v1/national/stats/crosses/totals/bfad6825d1794f7aba32d9adaad1c751"
          },
          "defense": {
            "actions": "/v1/national/stats/defense/actions/bfad6825d1794f7aba32d9adaad1c751",
            "blocks": "/v1/national/stats/defense/blocks/bfad6825d1794f7aba32d9adaad1c751",
            "clearances": "/v1/national/stats/defense/clearances/bfad6825d1794f7aba32d9adaad1c751",
            "goalline": "/v1/national/stats/defense/goalline/bfad6825d1794f7aba32d9adaad1c751",
            "tackles": "/v1/national/stats/defense/tackles/bfad6825d1794f7aba32d9adaad1c751"
          },
          "fouls": {
            "cards": "/v1/national/stats/fouls/cards/bfad6825d1794f7aba32d9adaad1c751",
            "wins": "/v1/national/stats/fouls/wins/bfad6825d1794f7aba32d9adaad1c751"
          },
          "goalkeeper": {
            "actions": "/v1/national/stats/goalkeeper/actions/bfad6825d1794f7aba32d9adaad1c751",
            "goals": "/v1/national/stats/goalkeeper/goals/bfad6825d1794f7aba32d9adaad1c751",
            "saves": "/v1/national/stats/goalkeeper/saves/bfad6825d1794f7aba32d9adaad1c751",
            "shots": "/v1/national/stats/goalkeeper/shots/bfad6825d1794f7aba32d9adaad1c751"
          },
          "goals": {
            "assists": "/v1/national/stats/goals/assists/bfad6825d1794f7aba32d9adaad1c751",
            "bodyparts": "/v1/national/stats/goals/bodyparts/bfad6825d1794f7aba32d9adaad1c751",
            "locations": "/v1/national/stats/goals/locations/bfad6825d1794f7aba32d9adaad1c751",
            "penalties": "/v1/national/stats/goals/penalties/bfad6825d1794f7aba32d9adaad1c751",
            "totals": "/v1/national/stats/goals/totals/bfad6825d1794f7aba32d9adaad1c751"
          },
          "passes": {
            "directions": "/v1/national/stats/passes/directions/bfad6825d1794f7aba32d9adaad1c751",
            "lengths": "/v1/national/stats/passes/lengths/bfad6825d1794f7aba32d9adaad1c751",
            "locations": "/v1/national/stats/passes/locations/bfad6825d1794f7aba32d9adaad1c751",
            "totals": "/v1/national/stats/passes/totals/bfad6825d1794f7aba32d9adaad1c751"
          },
          "setpieces": {
            "corners": "/v1/national/stats/setpieces/corners/bfad6825d1794f7aba32d9adaad1c751",
            "freekicks": "/v1/national/stats/setpieces/freekicks/bfad6825d1794f7aba32d9adaad1c751",
            "throwins": "/v1/national/stats/setpieces/throwins/bfad6825d1794f7aba32d9adaad1c751"
          },
          "shots": {
            "bodyparts": "/v1/national/stats/shots/bodyparts/bfad6825d1794f7aba32d9adaad1c751",
            "locations": "/v1/national/stats/shots/locations/bfad6825d1794f7aba32d9adaad1c751",
            "plays": "/v1/national/stats/shots/plays/bfad6825d1794f7aba32d9adaad1c751",
            "totals": "/v1/national/stats/shots/totals/bfad6825d1794f7aba32d9adaad1c751"
          },
          "touches": {
            "duels": "/v1/national/stats/touches/duels/bfad6825d1794f7aba32d9adaad1c751",
            "locations": "/v1/national/stats/touches/locations/bfad6825d1794f7aba32d9adaad1c751",
            "totals": "/v1/national/stats/touches/totals/bfad6825d1794f7aba32d9adaad1c751"
          }
        }
      },
      "match": "e2e9eb3dc9984dcd8e4328e138a7fd5d",
      "matchday": 2,
      "number": 13,
      "phase": 2,
      "phaseName": "Group",
      "player": "5e4b49d4cfb14b9da7f1411db6d6a420",
      "playerName": "Enner Valencia",
      "playerTeam": "3ba4718255c54a96802814a827374dc1",
      "playerTeamName": "Ecuador",
      "position": 27,
      "positionName": "Striker",
      "round": 1,
      "roundName": "Group Stage",
      "uri": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/lineups/bfad6825d1794f7aba32d9adaad1c751"
    }
  ]
}
OPTIONS /v1/(match_type)/matches/lineups

Returns documentation of the match lineups resource.

Goals

GET /v1/(match_type)/matches/(matchID)/goals/(ID)

Returns data on goal (non-penalty kick) events in football matches.

If matchID is passed, return goal data for the match that the ID corresponds to.

To retrieve data for a specific goal in a match, both matchID and ID must be passed.

If query parameters are passed, return match data that match the specified filters.

Inject phase-specific data into every record of the response.

URL Parameters:

Field Type URL Description
match_type string Match Type.
matchID uuid Unique ID of football match.
ID uuid Unique ID of goal record.

Query and Response Parameters:

Field Type Description
phase integer The unique ID of competition phase to which the match corresponds.
phase_name string Competition phase.
home_team uuid The unique ID of the home team.
home_team_name string The name of the home team.
away_team uuid The unique ID of the away team.
away_team_name string The name of the away team.
scoring_team uuid 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 uuid 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 uuid 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.

League Match Query and Response Parameters:

See link in Match Information resource.

Group Match Query and Response Parameters:

See link in Match Information resource.

Knockout Match Query and Response Parameters:

See link in Match Information resource.

Link Parameters:

Field URL Description
match Match Information representation.
player Players resource representation.
homeTeam Home Team resource representation, club or national team.
awayTeam Away Team resource representation, club or national team.

Example #1:

Who scored in the Honduras vs Ecuador match?

GET /v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/goals 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: Sun, 20 Jul 2014 05:51:01 GMT
Connection: close
Content-Type: application/json
Content-Length: 4926

{
  "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/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/goals?records=10&page=1",
    "last": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/goals?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 3
  },
  "result": [
    {
      "awayTeam": "3ba4718255c54a96802814a827374dc1",
      "awayTeamName": "Ecuador",
      "bodypart": 3,
      "bodypartName": "Left Foot",
      "group": "E",
      "homeTeam": "67b2c02d283e4bd78a23554ee0a331ae",
      "homeTeamName": "Honduras",
      "id": "7af8d967bdd04b70addff7bb3ac4cf5f",
      "link": {
        "awayTeam": "/v1/teams/3ba4718255c54a96802814a827374dc1",
        "homeTeam": "/v1/teams/67b2c02d283e4bd78a23554ee0a331ae",
        "match": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/info",
        "player": "/v1/personnel/players/25c60aebd54d4cc1bbfc23903b73e6aa"
      },
      "match": "e2e9eb3dc9984dcd8e4328e138a7fd5d",
      "matchday": 2,
      "phase": 2,
      "phaseName": "Group",
      "player": "25c60aebd54d4cc1bbfc23903b73e6aa",
      "playerName": "Carlo Costly",
      "playerTeam": "67b2c02d283e4bd78a23554ee0a331ae",
      "playerTeamName": "Honduras",
      "round": 1,
      "roundName": "Group Stage",
      "scoringTeam": "67b2c02d283e4bd78a23554ee0a331ae",
      "scoringTeamName": "Honduras",
      "shotEvent": 25,
      "shotEventType": "Shot outside goal area",
      "stoppageMins": 0,
      "timeMins": 31,
      "uri": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/goals/7af8d967bdd04b70addff7bb3ac4cf5f"
    },
    {
      "awayTeam": "3ba4718255c54a96802814a827374dc1",
      "awayTeamName": "Ecuador",
      "bodypart": 3,
      "bodypartName": "Left Foot",
      "group": "E",
      "homeTeam": "67b2c02d283e4bd78a23554ee0a331ae",
      "homeTeamName": "Honduras",
      "id": "8c0f7ec104454881b09dd13602c861a9",
      "link": {
        "awayTeam": "/v1/teams/3ba4718255c54a96802814a827374dc1",
        "homeTeam": "/v1/teams/67b2c02d283e4bd78a23554ee0a331ae",
        "match": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/info",
        "player": "/v1/personnel/players/5e4b49d4cfb14b9da7f1411db6d6a420"
      },
      "match": "e2e9eb3dc9984dcd8e4328e138a7fd5d",
      "matchday": 2,
      "phase": 2,
      "phaseName": "Group",
      "player": "5e4b49d4cfb14b9da7f1411db6d6a420",
      "playerName": "Enner Valencia",
      "playerTeam": "3ba4718255c54a96802814a827374dc1",
      "playerTeamName": "Ecuador",
      "round": 1,
      "roundName": "Group Stage",
      "scoringTeam": "3ba4718255c54a96802814a827374dc1",
      "scoringTeamName": "Ecuador",
      "shotEvent": 24,
      "shotEventType": "Shot inside goal area",
      "stoppageMins": 0,
      "timeMins": 34,
      "uri": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/goals/8c0f7ec104454881b09dd13602c861a9"
    },
    {
      "awayTeam": "3ba4718255c54a96802814a827374dc1",
      "awayTeamName": "Ecuador",
      "bodypart": 5,
      "bodypartName": "Head",
      "group": "E",
      "homeTeam": "67b2c02d283e4bd78a23554ee0a331ae",
      "homeTeamName": "Honduras",
      "id": "1ecc74c0b4a342889ba88db7720f9869",
      "link": {
        "awayTeam": "/v1/teams/3ba4718255c54a96802814a827374dc1",
        "homeTeam": "/v1/teams/67b2c02d283e4bd78a23554ee0a331ae",
        "match": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/info",
        "player": "/v1/personnel/players/5e4b49d4cfb14b9da7f1411db6d6a420"
      },
      "match": "e2e9eb3dc9984dcd8e4328e138a7fd5d",
      "matchday": 2,
      "phase": 2,
      "phaseName": "Group",
      "player": "5e4b49d4cfb14b9da7f1411db6d6a420",
      "playerName": "Enner Valencia",
      "playerTeam": "3ba4718255c54a96802814a827374dc1",
      "playerTeamName": "Ecuador",
      "round": 1,
      "roundName": "Group Stage",
      "scoringTeam": "3ba4718255c54a96802814a827374dc1",
      "scoringTeamName": "Ecuador",
      "shotEvent": 24,
      "shotEventType": "Shot inside goal area",
      "stoppageMins": 0,
      "timeMins": 65,
      "uri": "/v1/national/matches/e2e9eb3dc9984dcd8e4328e138a7fd5d/goals/1ecc74c0b4a342889ba88db7720f9869"
    }
  ]
}
OPTIONS /v1/(match_type)/matches/goals

Returns documentation of the goal event resource.

Penalties

GET /v1/(match_type)/matches/(matchID)/penalties/(ID)

Returns data on penalty kick events in football matches.

If matchID is passed, return penalty data for the match that the ID corresponds to.

To retrieve data for a specific penalty kick event in a match, both matchID and ID must be passed.

If query parameters are passed, return the match data that match the specified filters.

Inject phase-specific data into every record of the response.

Note

This resource does NOT apply to penalty kick shootouts.

URL Parameters:

Field Type URL Description
match_type string Match Type.
matchID uuid Unique ID of football match.
ID uuid Unique ID of penalty record.

Query and Response Parameters:

Field Type Description
phase integer The unique ID of competition phase to which the match corresponds.
phase_name string Competition phase.
home_team uuid The unique ID of the home team.
home_team_name string The name of the home team.
away_team uuid The unique ID of the away team.
away_team_name string The name of the away team.
player_team uuid 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 uuid 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.

League Match Query and Response Parameters:

See link in Match Information resource.

Group Match Query and Response Parameters:

See link in Match Information resource.

Knockout Match Query and Response Parameters:

See link in Match Information resource.

Link Parameters:

Field URL Description
match Match Information representation.
player Players resource representation.
homeTeam Home Team resource representation, club or national team.
awayTeam Away Team resource representation, club or national team.

Example:

Retrieve a penalty kick event.

GET /v1/national/matches/9649f4994bf2440b8870d6031815fe65/penalties HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Server: gunicorn/18.0
Date: Sun, 20 Jul 2014 06:04:57 GMT
Connection: close
Content-Type: application/json
Content-Length: 2227
Access-Control-Allow-Origin: *

{
  "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/matches/9649f4994bf2440b8870d6031815fe65/penalties?records=10&page=1",
    "last": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/penalties?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "foul": 10,
      "foulType": "Unknown",
      "group": "A",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "2201253f712742738601b295d5057166",
      "link": {
        "awayTeam": "/v1/teams/8a472ca1fac94ee99e0fe28536637946",
        "homeTeam": "/v1/teams/70ce7b6218a24e1d94c21ed8b5cd070c",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "player": "/v1/personnel/players/c1f25071e54647a7ad73b79aa792447e"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchday": 1,
      "outcome": 1,
      "outcomeType": "Goal",
      "phase": 2,
      "phaseName": "Group",
      "player": "c1f25071e54647a7ad73b79aa792447e",
      "playerName": "Neymar",
      "playerTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "playerTeamName": "Brazil",
      "round": 1,
      "roundName": "Group Stage",
      "stoppageMins": 0,
      "timeMins": 71,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/penalties/2201253f712742738601b295d5057166"
    }
  ]
}
OPTIONS /v1/(match_type)/matches/penalties

Returns documentation of the penalty kick event resource.

Offenses

GET /v1/(match_type)/matches/(matchID)/offenses/(ID)

Returns data on on-field disciplinary events in football matches.

If matchID is passed, return disciplinary data for the match the ID corresponds to.

To retrieve data for a specific bookable offense in a match, both matchID and ID must be passed.

If query parameters are passed, return match data that satisfy the specified filters.

Inject phase-specific data into every record of the response.

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

URL Parameters:

Field Type URL Description
match_type string Match Type.
matchID uuid Unique ID of football match.
ID uuid Unique ID of offense record.

Query and Response Parameters:

Field Type Description
phase integer The unique ID of competition phase to which the match corresponds.
phase_name string Competition phase.
home_team uuid The unique ID of the home team.
home_team_name string The name of the home team.
away_team uuid The unique ID of the away team.
away_team_name string The name of the away team.
player_team uuid 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 uuid 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.

League Match Query and Response Parameters:

See link in Match Information resource.

Group Match Query and Response Parameters:

See link in Match Information resource.

Knockout Match Query and Response Parameters:

See link in Match Information resource.

Link Parameters:

Field URL Description
match Match Information representation.
player Players resource representation.
homeTeam Home Team resource representation, club or national team.
awayTeam Away Team resource representation, club or national team.

Example:

Retrieve all of the bookable offenses in a specific match.

GET /v1/national/matches/9649f4994bf2440b8870d6031815fe65/offenses 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: Sun, 20 Jul 2014 06:14:26 GMT
Connection: close
Content-Type: application/json
Content-Length: 5700

{
  "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/matches/9649f4994bf2440b8870d6031815fe65/offenses?records=10&page=1",
    "last": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/offenses?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 4
  },
  "result": [
    {
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "card": 1,
      "cardType": "Yellow",
      "foul": 10,
      "foulType": "Unknown",
      "group": "A",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "d2b5fb2158754477b4009804add315cb",
      "link": {
        "awayTeam": "/v1/teams/8a472ca1fac94ee99e0fe28536637946",
        "homeTeam": "/v1/teams/70ce7b6218a24e1d94c21ed8b5cd070c",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "player": "/v1/personnel/players/4d8dc7d8d8b34b5da44d249bd7965afc"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchday": 1,
      "phase": 2,
      "phaseName": "Group",
      "player": "4d8dc7d8d8b34b5da44d249bd7965afc",
      "playerName": "Vedran \u0106orluka",
      "playerTeam": "8a472ca1fac94ee99e0fe28536637946",
      "playerTeamName": "Croatia",
      "round": 1,
      "roundName": "Group Stage",
      "stoppageMins": 0,
      "timeMins": 65,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/offenses/d2b5fb2158754477b4009804add315cb"
    },
    {
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "card": 1,
      "cardType": "Yellow",
      "foul": 10,
      "foulType": "Unknown",
      "group": "A",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "d580cbe4ec7340d8b272ce3fa1c5211a",
      "link": {
        "awayTeam": "/v1/teams/8a472ca1fac94ee99e0fe28536637946",
        "homeTeam": "/v1/teams/70ce7b6218a24e1d94c21ed8b5cd070c",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "player": "/v1/personnel/players/f6afa788aa774684b542f77c8d4478f3"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchday": 1,
      "phase": 2,
      "phaseName": "Group",
      "player": "f6afa788aa774684b542f77c8d4478f3",
      "playerName": "Dejan Lovren",
      "playerTeam": "8a472ca1fac94ee99e0fe28536637946",
      "playerTeamName": "Croatia",
      "round": 1,
      "roundName": "Group Stage",
      "stoppageMins": 0,
      "timeMins": 69,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/offenses/d580cbe4ec7340d8b272ce3fa1c5211a"
    },
    {
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "card": 1,
      "cardType": "Yellow",
      "foul": 10,
      "foulType": "Unknown",
      "group": "A",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "0c6314bc02154cd483ccc5e63b1b4cdf",
      "link": {
        "awayTeam": "/v1/teams/8a472ca1fac94ee99e0fe28536637946",
        "homeTeam": "/v1/teams/70ce7b6218a24e1d94c21ed8b5cd070c",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "player": "/v1/personnel/players/e9ea46491a824dc79a1fd140c8c006e6"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchday": 1,
      "phase": 2,
      "phaseName": "Group",
      "player": "e9ea46491a824dc79a1fd140c8c006e6",
      "playerName": "Luiz Gustavo",
      "playerTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "playerTeamName": "Brazil",
      "round": 1,
      "roundName": "Group Stage",
      "stoppageMins": 0,
      "timeMins": 87,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/offenses/0c6314bc02154cd483ccc5e63b1b4cdf"
    },
    {
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "card": 1,
      "cardType": "Yellow",
      "foul": 10,
      "foulType": "Unknown",
      "group": "A",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "52469e59cf744b5abe7e8dc8e894a74e",
      "link": {
        "awayTeam": "/v1/teams/8a472ca1fac94ee99e0fe28536637946",
        "homeTeam": "/v1/teams/70ce7b6218a24e1d94c21ed8b5cd070c",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "player": "/v1/personnel/players/c1f25071e54647a7ad73b79aa792447e"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchday": 1,
      "phase": 2,
      "phaseName": "Group",
      "player": "c1f25071e54647a7ad73b79aa792447e",
      "playerName": "Neymar",
      "playerTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "playerTeamName": "Brazil",
      "round": 1,
      "roundName": "Group Stage",
      "stoppageMins": 0,
      "timeMins": 27,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/offenses/52469e59cf744b5abe7e8dc8e894a74e"
    }
  ]
}
OPTIONS /v1/(match_type)/matches/offenses

Returns documentation of the disciplinary event resource.

Substitutions

GET /v1/(match_type)/matches/(matchID)/substitutions/(ID)

Returns data on substitution events in football matches.

If matchID is passed, return data for the match that the ID corresponds to.

To retrieve data for a specific substitution in a match, both matchID and ID must be passed.

If query parameters are passed, return match data that match the specified filters.

Inject phase-specific data into every record of the response.

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.

URL Parameters:

Field Type URL Description
match_type string Match Type.
matchID uuid Unique ID of football match.
ID uuid Unique ID of substitution record.

Query and Response Parameters:

Field Type Description
phase integer The unique ID of competition phase to which the match corresponds.
phase_name string Competition phase.
home_team uuid The unique ID of the home team.
home_team_name string The name of the home team.
away_team uuid The unique ID of the away team.
away_team_name string The name of the away team.
team uuid The unique ID of the team making a substitution.
team_name string The name of the team making a substitution.
in_player uuid 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 uuid 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.

League Match Query and Response Parameters:

See link in Match Information resource.

Group Match Query and Response Parameters:

See link in Match Information resource.

Knockout Match Query and Response Parameters:

See link in Match Information resource.

Link Parameters:

Field URL Description
match Match Information resource representation.
homeTeam Home Team resource representation, club or national team.
awayTeam Away Team resource representation, club or national team.
inPlayer Incoming Players resource representation.
outPlayer Outgoing Players resource representation.

Example:

Retrieve all of the substitutions in a specific match.

GET /v1/national/matches/9649f4994bf2440b8870d6031815fe65/substitutions 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: Sun, 20 Jul 2014 07:01:31 GMT
Connection: close
Content-Type: application/json
Content-Length: 7299

{
  "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/matches/9649f4994bf2440b8870d6031815fe65/substitutions?records=10&page=1",
    "last": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/substitutions?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 5
  },
  "result": [
    {
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "group": "A",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "af595f752788413a9e0711e92752880b",
      "inPlayer": "0325343e15524a25bedb7b0e72f5f3af",
      "inPlayerName": "Marcelo Brozovi\u0107",
      "link": {
        "awayTeam": "/v1/countries/8a472ca1fac94ee99e0fe28536637946",
        "homeTeam": "/v1/countries/70ce7b6218a24e1d94c21ed8b5cd070c",
        "inPlayer": "/v1/personnel/players/0325343e15524a25bedb7b0e72f5f3af",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "outPlayer": "/v1/personnel/players/108bd98a641c463fb8afd2645f312f91"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchday": 1,
      "outPlayer": "108bd98a641c463fb8afd2645f312f91",
      "outPlayerName": "Mateo Kova\u010di\u0107",
      "phase": 2,
      "phaseName": "Group",
      "round": 1,
      "roundName": "Group Stage",
      "stoppageMins": 0,
      "team": "8a472ca1fac94ee99e0fe28536637946",
      "teamName": "Croatia",
      "timeMins": 61,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/substitutions/af595f752788413a9e0711e92752880b"
    },
    {
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "group": "A",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "4346e99292c3426d95c11eeb0f5eb0b5",
      "inPlayer": "38df8e3e0b1f49f6bbaac3b38c8fcd2f",
      "inPlayerName": "Ante Rebi\u0107",
      "link": {
        "awayTeam": "/v1/countries/8a472ca1fac94ee99e0fe28536637946",
        "homeTeam": "/v1/countries/70ce7b6218a24e1d94c21ed8b5cd070c",
        "inPlayer": "/v1/personnel/players/38df8e3e0b1f49f6bbaac3b38c8fcd2f",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "outPlayer": "/v1/personnel/players/2f5c68be7ced4d0eb943f16e2a7c2759"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchday": 1,
      "outPlayer": "2f5c68be7ced4d0eb943f16e2a7c2759",
      "outPlayerName": "Nikica Jelavi\u0107",
      "phase": 2,
      "phaseName": "Group",
      "round": 1,
      "roundName": "Group Stage",
      "stoppageMins": 0,
      "team": "8a472ca1fac94ee99e0fe28536637946",
      "teamName": "Croatia",
      "timeMins": 78,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/substitutions/4346e99292c3426d95c11eeb0f5eb0b5"
    },
    {
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "group": "A",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "c8e4ca7c3be74370a197f5d5d92667ce",
      "inPlayer": "9a118c4ddffc45f3b5343dc2ab96e27b",
      "inPlayerName": "Hernanes",
      "link": {
        "awayTeam": "/v1/countries/8a472ca1fac94ee99e0fe28536637946",
        "homeTeam": "/v1/countries/70ce7b6218a24e1d94c21ed8b5cd070c",
        "inPlayer": "/v1/personnel/players/9a118c4ddffc45f3b5343dc2ab96e27b",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "outPlayer": "/v1/personnel/players/002d295099114f0e8345736a5afcfd66"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchday": 1,
      "outPlayer": "002d295099114f0e8345736a5afcfd66",
      "outPlayerName": "Paulinho",
      "phase": 2,
      "phaseName": "Group",
      "round": 1,
      "roundName": "Group Stage",
      "stoppageMins": 0,
      "team": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "teamName": "Brazil",
      "timeMins": 63,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/substitutions/c8e4ca7c3be74370a197f5d5d92667ce"
    },
    {
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "group": "A",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "43e31ce12a0346209ba29da07c9e2328",
      "inPlayer": "f0093c52da1c4463a7684f9b2f622d0f",
      "inPlayerName": "Ramires",
      "link": {
        "awayTeam": "/v1/countries/8a472ca1fac94ee99e0fe28536637946",
        "homeTeam": "/v1/countries/70ce7b6218a24e1d94c21ed8b5cd070c",
        "inPlayer": "/v1/personnel/players/f0093c52da1c4463a7684f9b2f622d0f",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "outPlayer": "/v1/personnel/players/c1f25071e54647a7ad73b79aa792447e"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchday": 1,
      "outPlayer": "c1f25071e54647a7ad73b79aa792447e",
      "outPlayerName": "Neymar",
      "phase": 2,
      "phaseName": "Group",
      "round": 1,
      "roundName": "Group Stage",
      "stoppageMins": 0,
      "team": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "teamName": "Brazil",
      "timeMins": 88,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/substitutions/43e31ce12a0346209ba29da07c9e2328"
    },
    {
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "group": "A",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "0b7ab3b313e948b98eceb74166508620",
      "inPlayer": "705674faac464750860697177fe2b4fb",
      "inPlayerName": "Bernard",
      "link": {
        "awayTeam": "/v1/countries/8a472ca1fac94ee99e0fe28536637946",
        "homeTeam": "/v1/countries/70ce7b6218a24e1d94c21ed8b5cd070c",
        "inPlayer": "/v1/personnel/players/705674faac464750860697177fe2b4fb",
        "match": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
        "outPlayer": "/v1/personnel/players/f11452929a644493a93cdab4ed8745ef"
      },
      "match": "9649f4994bf2440b8870d6031815fe65",
      "matchday": 1,
      "outPlayer": "f11452929a644493a93cdab4ed8745ef",
      "outPlayerName": "Hulk",
      "phase": 2,
      "phaseName": "Group",
      "round": 1,
      "roundName": "Group Stage",
      "stoppageMins": 0,
      "team": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "teamName": "Brazil",
      "timeMins": 68,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/substitutions/0b7ab3b313e948b98eceb74166508620"
    }
  ]
}
OPTIONS /v1/(match_type)/matches/substitutions

Returns documentation of the substitution event resource.

Penalty Shootouts

GET /v1/(match_type)/matches/(matchID)/shootouts/(ID)

Returns data on actions in a penalty kick shootout at the end of a football match.

If matchID is passed, return data for the match that the ID corresponds to.

To retrieve data for a specific shootout event in a match, both matchID and ID must be passed.

If query parameters are passed, return match data that match the specified filters.

Inject phase-specific data into every record of the response.

URL Parameters:

Field Type URL Description
match_type string Match Type.
matchID uuid Unique ID of football match.
ID uuid Unique ID of shootout record.

Query and Response Parameters:

Field Type Description
phase integer The unique ID of competition phase to which the match corresponds.
phase_name string Competition phase.
match uuid The unique ID of the football match.
home_team uuid The unique ID of the home team.
home_team_name string The name of the home team.
away_team uuid The unique ID of the away team.
away_team_name string The name of the away team.
opening_team uuid The unique ID of the team shooting first in the penalty kick shootout.
opening_team_name string The name of the team shooting first in the penalty kick shootout.
player_team uuid The unique ID of the player’s team.
player_team_name string The name of the player’s team.
player uuid The unique ID of the player in the shootout.
player_name string The name of the player in the shootout.
shootout_round integer The round of the penalty shootout in which the penalty kick took place.
outcome integer The unique ID of the penalty kick outcome.
outcome_type string The description of the penalty kick outcome.

League Match Query and Response Parameters:

See link in Match Information resource.

Group Match Query and Response Parameters:

See link in Match Information resource.

Knockout Match Query and Response Parameters:

See link in Match Information resource.

Link Parameters:

Field URL Description
match Match Information resource representation.
player Players resource representation.
homeTeam Home Team resource representation, club or national team.
awayTeam Away Team resource representation, club or national team.

Example:

Retrieve the kicks from a single round of a penalty shootout.

GET /v1/national/matches/7f08326167514246b1cea026edc5f644/shootouts?shootout_round=3 HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Content-Encoding: gzip
Content-Type: application/json
Date: Sun, 27 Jul 2014 04:40:56 GMT
Server: openresty/1.5.11.1
Vary: Accept-Encoding
Via: 1.1 vegur
Content-Length: 841
Connection: keep-alive

{
  "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/matches/7f08326167514246b1cea026edc5f644/shootouts?shootout_round=3&records=10&page=1",
    "last": "/v1/national/matches/7f08326167514246b1cea026edc5f644/shootouts?shootout_round=3&records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 2
  },
  "result": [
    {
      "awayTeam": "2805484eecd54103aa852fc8ea792955",
      "awayTeamName": "Argentina",
      "homeTeam": "9c2075ace5e6440e9c88ea6f3ef0a5a1",
      "homeTeamName": "Netherlands",
      "id": "cde33ad29c8f48dfb03f5256c9b00b3a",
      "link": {
        "awayTeam": "/v1/countries/2805484eecd54103aa852fc8ea792955",
        "homeTeam": "/v1/countries/9c2075ace5e6440e9c88ea6f3ef0a5a1",
        "match": "/v1/national/matches/7f08326167514246b1cea026edc5f644/info",
        "player": "/v1/personnel/players/a3e74029c3ed4ce5b138333bc780f823"
      },
      "match": "7f08326167514246b1cea026edc5f644",
      "matchday": 1,
      "openingTeam": "9c2075ace5e6440e9c88ea6f3ef0a5a1",
      "openingTeamName": "Netherlands",
      "outcome": 3,
      "outcomeType": "Save",
      "phase": 3,
      "phaseName": "Knockout",
      "player": "a3e74029c3ed4ce5b138333bc780f823",
      "playerName": "Wesley Sneijder",
      "playerTeam": "9c2075ace5e6440e9c88ea6f3ef0a5a1",
      "playerTeamName": "Netherlands",
      "round": 19,
      "roundName": "Semi-Final (1/2)",
      "shootoutRound": 3,
      "uri": "/v1/national/matches/7f08326167514246b1cea026edc5f644/shootouts/cde33ad29c8f48dfb03f5256c9b00b3a"
    },
    {
      "awayTeam": "2805484eecd54103aa852fc8ea792955",
      "awayTeamName": "Argentina",
      "homeTeam": "9c2075ace5e6440e9c88ea6f3ef0a5a1",
      "homeTeamName": "Netherlands",
      "id": "62dfa753684b4df3b0ea7c70cdf7c308",
      "link": {
        "awayTeam": "/v1/countries/2805484eecd54103aa852fc8ea792955",
        "homeTeam": "/v1/countries/9c2075ace5e6440e9c88ea6f3ef0a5a1",
        "match": "/v1/national/matches/7f08326167514246b1cea026edc5f644/info",
        "player": "/v1/personnel/players/8e1a9426c01948ff91f5dd67a9024c2b"
      },
      "match": "7f08326167514246b1cea026edc5f644",
      "matchday": 1,
      "openingTeam": "9c2075ace5e6440e9c88ea6f3ef0a5a1",
      "openingTeamName": "Netherlands",
      "outcome": 1,
      "outcomeType": "Goal",
      "phase": 3,
      "phaseName": "Knockout",
      "player": "8e1a9426c01948ff91f5dd67a9024c2b",
      "playerName": "Sergio Ag\u00fcero",
      "playerTeam": "2805484eecd54103aa852fc8ea792955",
      "playerTeamName": "Argentina",
      "round": 19,
      "roundName": "Semi-Final (1/2)",
      "shootoutRound": 3,
      "uri": "/v1/national/matches/7f08326167514246b1cea026edc5f644/shootouts/62dfa753684b4df3b0ea7c70cdf7c308"
    }
  ]
}
OPTIONS /v1/(match_type)/matches/shootouts

Returns documentation of the match penalty kick shootouts resource.