Personnel

The Personnel resources let you access biographical and demographical data on all personnel involved in a football match – players, managers, and match referees.

We model football personnel as Persons – that’s what they are, after all – with specific characteristics for their respective roles. Football players have default positions, for example. Managers and referees have specific specifications as well, such as certifications, but for now we don’t capture those in the database.

By modeling personnel as persons with core attributes we make the database flexible enough to handle players who become managers or even referees. (The reverse applies as well, but that rarely happens.)

Note

Assistant referees and fourth officials are not tracked in the database.

Persons

GET /v0/persons/(int: ID)

Returns data on persons involved in football matches. If ID is passed, returns data for the person the ID corresponds to.

If query parameters are passed, it returns the persons who match the specified filters.

Query and Response Parameters:

Field Type Description
first_name string The person’s first name.
last_name string The person’s surname.
nickname string The person’s nickname or popularly known name.
birth_date date The person’s birthdate in ISO format (YYYY-MM-DD).
country integer The unique ID of the person’s nationality.

Link Parameters:

Field URL Description
country Countries resource representation.

Example:

Retrieve a specific person’s record.

GET /v0/persons/1000000 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: Wed, 21 Aug 2013 21:07:36 GMT
Server: gunicorn/0.15.0
Content-Length: 542
Connection: keep-alive

{
  "meta": {
    "totalPages": 1,
    "records": 10,
    "totalRecords": 1,
    "page": 1,
    "next": null,
    "first": "/v0/persons/1000000?records=10&page=1",
    "last": "/v0/persons/1000000?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": [
    {
      "uri": "/v0/persons/1000000",
      "link": {
        "country": "/v0/countries/280"
      },
      "id": 1000000,
      "country": 280,
      "nickname": "",
      "lastName": "Bruce",
      "birthDate": "1960-12-31",
      "firstName": "Steve"
    }
  ]
}
OPTIONS /v0/persons

Returns documentation of the persons resource.

Players

GET /v0/personnel/players/(int: ID)

Returns aggregated bio- and demographic data on football players. If ID is passed, return data for the player the ID corresponds to.

If query parameters are passed, it returns the football players who match the specified filters.

Query and Response Parameters:

Field Type Description
supplier_id integer The unique supplier ID of player record.
person string The unique ID of person.
full_name string Full name of player, or nickname if it exists.
birth_date date The player’s birthdate in ISO format (YYYY-MM-DD).
country integer The unique ID of the player’s nationality.
country_name string Popular name of FIFA-affiliated football association.
position integer The unique ID of default position of player.
position_name string Name of generic field position.

Link Parameters:

Field URL Description
country Countries resource representation.
person Persons resource representation.
matches Match Information representations in which player was in the match lineup.
events Match Events resource representations involving player.

Example:

Retrieve a list of player records (e.g. players from the same country) using the query parameter.

GET /v0/personnel/players?countryName=Bosnia+and+Herzegovina 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: Mon, 02 Sep 2013 06:37:37 GMT
Server: gunicorn/0.15.0
Content-Length: 2060
Connection: keep-alive

{
  "meta": {
    "totalPages": 1,
    "records": 10,
    "totalRecords": 2,
    "page": 1,
    "next": null,
    "first": "/v0/personnel/players?records=10&page=1&countryName=Bosnia+and+Herzegovina",
    "last": "/v0/personnel/players?records=10&page=1&countryName=Bosnia+and+Herzegovina",
    "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": [
    {
      "supplierId": 40349,
      "country": 274,
      "positionName": "Goalkeeper",
      "uri": "/v0/personnel/players/1000039",
      "person": 1000089,
      "link": {
        "matches": "/v0/matches/lineups?player=1000039",
        "country": "/v0/countries/274",
        "events": {
          "subbedOut": "/v0/events/substitutions?out_player=1000039",
          "offenses": "/v0/events/offenses?player=1000039",
          "penalties": "/v0/events/penalties?player=1000039",
          "goals": "/v0/events/goals?player=1000039",
          "subbedIn": "/v0/events/substitutions?in_player=1000039"
        },
        "person": "/v0/persons/1000089"
      },
      "fullName": "Asmir Begovi\u0107",
      "countryName": "Bosnia and Herzegovina",
      "birthDate": "1987-06-20",
      "position": 10,
      "id": 1000039
    },
    {
      "supplierId": 42544,
      "country": 274,
      "positionName": "Striker",
      "uri": "/v0/personnel/players/1000135",
      "person": 1000188,
      "link": {
        "matches": "/v0/matches/lineups?player=1000135",
        "country": "/v0/countries/274",
        "events": {
          "subbedOut": "/v0/events/substitutions?out_player=1000135",
          "offenses": "/v0/events/offenses?player=1000135",
          "penalties": "/v0/events/penalties?player=1000135",
          "goals": "/v0/events/goals?player=1000135",
          "subbedIn": "/v0/events/substitutions?in_player=1000135"
        },
        "person": "/v0/persons/1000188"
      },
      "fullName": "Edin D\u017eeko",
      "countryName": "Bosnia and Herzegovina",
      "birthDate": "1986-03-17",
      "position": 27,
      "id": 1000135
    }
  ]
}
OPTIONS /v0/personnel/players

Returns documentation of the football player resource.

Managers

GET /v0/personnel/managers/(int: ID)

Returns aggregated bio- and demographic data on football club managers. If ID is passed, return data for the manager the ID corresponds to.

If query parameters are passed, it returns the football club managers who match the specified filters.

Query and Response Parameters:

Field Type Description
supplier_id integer The unique supplier ID of manager record.
person string The unique ID of person.
full_name string Full name of manager, or nickname if it exists.
birth_date date The manager’s birthdate in ISO format (YYYY-MM-DD).
country integer The unique ID of the manager’s nationality.
country_name string Popular name of FIFA-affiliated football association.

Link Parameters:

Field URL Description
country Countries resource representation.
person Persons resource representation.
home_matches Home Match Information representations in which manager was involved.
away_matches Away Match Information representations in which manager was involved.

Example:

Retrieve a specific manager’s record using the query parameter.

GET /v0/personnel/managers?fullName=Arsène+Wenger 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: Mon, 02 Sep 2013 06:39:23 GMT
Server: gunicorn/0.15.0
Content-Length: 830
Connection: keep-alive

{
  "meta": {
    "totalPages": 1,
    "records": 10,
    "totalRecords": 1,
    "page": 1,
    "next": null,
    "first": "/v0/personnel/managers?records=10&page=1&fullName=Ars%C3%A8ne+Wenger",
    "last": "/v0/personnel/managers?records=10&page=1&fullName=Ars%C3%A8ne+Wenger",
    "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": [
    {
      "supplierId": null,
      "country": 284,
      "uri": "/v0/personnel/managers/10026",
      "person": 1000026,
      "link": {
        "awayMatches": "/v0/matches/info?away_manager=10026",
        "country": "/v0/countries/284",
        "homeMatches": "/v0/matches/info?home_manager=10026",
        "person": "/v0/persons/1000026"
      },
      "fullName": "Ars\u00e8ne Wenger",
      "countryName": "France",
      "birthDate": "1949-10-22",
      "id": 10026
    }
  ]
}
OPTIONS /v0/personnel/managers

Returns documentation of the football club manager resource.

Referees

GET /v0/personnel/referees/(int: ID)

Returns aggregated bio- and demographic data on football match referees. If ID is passed, return data for the referee the ID corresponds to.

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

Query and Response Parameters:

Field Type Description
supplier_id integer The unique supplier ID of referee record.
person string The unique ID of person.
full_name string Full name of referee, or nickname if it exists.
birth_date date The referee’s birthdate in ISO format (YYYY-MM-DD).
country integer The unique ID of the referee’s nationality.
country_name string Popular name of FIFA-affiliated football association.

Link Parameters:

Field URL Description
country Countries resource representation.
person Persons resource representation.
matches Match Information representations in which referee officiated.

Example:

Retrieve a specific referee’s record.

GET /v0/personnel/referees/10004 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: Mon, 02 Sep 2013 06:42:52 GMT
Server: gunicorn/0.15.0
Content-Length: 702
Connection: keep-alive

{
  "meta": {
    "totalPages": 1,
    "records": 10,
    "totalRecords": 1,
    "page": 1,
    "next": null,
    "first": "/v0/personnel/referees/10004?records=10&page=1",
    "last": "/v0/personnel/referees/10004?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": [
    {
      "supplierId": null,
      "country": 280,
      "uri": "/v0/personnel/referees/10004",
      "person": 1000031,
      "link": {
        "matches": "/v0/matches/info?referee=10004",
        "country": "/v0/countries/280",
        "person": "/v0/persons/1000031"
      },
      "fullName": "Phil Dowd",
      "countryName": "England",
      "birthDate": "1963-01-26",
      "id": 10004
    }
  ]
}
OPTIONS /v0/personnel/referees

Returns documentation of the football match referee resource.