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 /v1/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.
second_name	string	The person’s second (middle) name.
last_name	string	The person’s surname.
second_last_name	string	The person’s second surname, or matronymic.
nickname	string	The person’s nickname or popularly known name.
birth_date	date	The person’s birthdate in ISO format (YYYY-MM-DD).
order	integer	The unique ID of the person’s name order.
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 /v1/persons/f5f9599bf6d747b6a2fad87fb6a36494 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 05:50:19 GMT
Connection: close
Content-Type: application/json
Content-Length: 1509

{
  "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/persons/f5f9599bf6d747b6a2fad87fb6a36494?records=10&page=1",
    "last": "/v1/persons/f5f9599bf6d747b6a2fad87fb6a36494?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "birthDate": "1968-03-18",
      "country": "4deb3943c99c4c01a7fd110a1637cfd1",
      "firstName": "Miguel",
      "id": "f5f9599bf6d747b6a2fad87fb6a36494",
      "lastName": "Herrera",
      "link": {
        "country": "/v1/countries/4deb3943c99c4c01a7fd110a1637cfd1"
      },
      "nickname": "",
      "order": 10,
      "secondLastName": "Aguirre",
      "secondName": "Ernesto",
      "uri": "/v1/persons/f5f9599bf6d747b6a2fad87fb6a36494"
    }
  ]
}

OPTIONS /v1/persons¶: Returns documentation of the persons resource.

Players¶

GET /v1/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
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.
club	Match Information representations in which player was in the match lineup for a club team.
natl	Match Information representations in which player was in the match lineup for a national team.

Example:

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

GET /v1/personnel/players?countryName=Bosnia+and+Herzegovina&position_name=Goalkeeper 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 06:01:54 GMT
Connection: close
Content-Type: application/json
Content-Length: 8302

{
  "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/personnel/players?country_name=Bosnia+and+Herzegovina&records=10&position_name=Goalkeeper&page=1",
    "last": "/v1/personnel/players?country_name=Bosnia+and+Herzegovina&records=10&position_name=Goalkeeper&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 4
  },
  "result": [
    {
      "birthDate": "1987-06-20",
      "country": "4bf4de9895094197860cd9e4e7ac778f",
      "countryName": "Bosnia and Herzegovina",
      "fullName": "Asmir Begovi\u0107",
      "id": "2f89727fabe54fc88499567c3c7a7afa",
      "link": {
        "club": {
          "goals": "/v1/clubs/matches/goals?player=2f89727fabe54fc88499567c3c7a7afa",
          "matches": "/v1/clubs/matches/lineups?player=2f89727fabe54fc88499567c3c7a7afa",
          "offenses": "/v1/clubs/matches/offenses?player=2f89727fabe54fc88499567c3c7a7afa",
          "penalties": "/v1/clubs/matches/penalties?player=2f89727fabe54fc88499567c3c7a7afa",
          "subbedIn": "/v1/clubs/matches/substitutions?in_player=2f89727fabe54fc88499567c3c7a7afa",
          "subbedOut": "/v1/clubs/matches/substitutions?out_player=2f89727fabe54fc88499567c3c7a7afa"
        },
        "country": "/v1/countries/4bf4de9895094197860cd9e4e7ac778f",
        "natl": {
          "goals": "/v1/national/matches/goals?player=2f89727fabe54fc88499567c3c7a7afa",
          "matches": "/v1/national/matches/lineups?player=2f89727fabe54fc88499567c3c7a7afa",
          "offenses": "/v1/national/matches/offenses?player=2f89727fabe54fc88499567c3c7a7afa",
          "penalties": "/v1/national/matches/penalties?player=2f89727fabe54fc88499567c3c7a7afa",
          "subbedIn": "/v1/national/matches/substitutions?in_player=2f89727fabe54fc88499567c3c7a7afa",
          "subbedOut": "/v1/national/matches/substitutions?out_player=2f89727fabe54fc88499567c3c7a7afa"
        },
        "person": "/v1/persons/1dc603373b9e44a996be83d3bab2f9dc"
      },
      "person": "1dc603373b9e44a996be83d3bab2f9dc",
      "position": 10,
      "positionName": "Goalkeeper",
      "uri": "/v1/personnel/players/2f89727fabe54fc88499567c3c7a7afa"
    },
    {
      "birthDate": "1981-05-13",
      "country": "4bf4de9895094197860cd9e4e7ac778f",
      "countryName": "Bosnia and Herzegovina",
      "fullName": "Asmir Avduki\u0107",
      "id": "d2527c4dedb64f6682ad0a1b13659db6",
      "link": {
        "club": {
          "goals": "/v1/clubs/matches/goals?player=d2527c4dedb64f6682ad0a1b13659db6",
          "matches": "/v1/clubs/matches/lineups?player=d2527c4dedb64f6682ad0a1b13659db6",
          "offenses": "/v1/clubs/matches/offenses?player=d2527c4dedb64f6682ad0a1b13659db6",
          "penalties": "/v1/clubs/matches/penalties?player=d2527c4dedb64f6682ad0a1b13659db6",
          "subbedIn": "/v1/clubs/matches/substitutions?in_player=d2527c4dedb64f6682ad0a1b13659db6",
          "subbedOut": "/v1/clubs/matches/substitutions?out_player=d2527c4dedb64f6682ad0a1b13659db6"
        },
        "country": "/v1/countries/4bf4de9895094197860cd9e4e7ac778f",
        "natl": {
          "goals": "/v1/national/matches/goals?player=d2527c4dedb64f6682ad0a1b13659db6",
          "matches": "/v1/national/matches/lineups?player=d2527c4dedb64f6682ad0a1b13659db6",
          "offenses": "/v1/national/matches/offenses?player=d2527c4dedb64f6682ad0a1b13659db6",
          "penalties": "/v1/national/matches/penalties?player=d2527c4dedb64f6682ad0a1b13659db6",
          "subbedIn": "/v1/national/matches/substitutions?in_player=d2527c4dedb64f6682ad0a1b13659db6",
          "subbedOut": "/v1/national/matches/substitutions?out_player=d2527c4dedb64f6682ad0a1b13659db6"
        },
        "person": "/v1/persons/8f08f1831d83432e9fd997337c1dee50"
      },
      "person": "8f08f1831d83432e9fd997337c1dee50",
      "position": 10,
      "positionName": "Goalkeeper",
      "uri": "/v1/personnel/players/d2527c4dedb64f6682ad0a1b13659db6"
    },
    {
      "birthDate": "1986-05-15",
      "country": "4bf4de9895094197860cd9e4e7ac778f",
      "countryName": "Bosnia and Herzegovina",
      "fullName": "Jasmin Fejzi\u0107",
      "id": "6099005600094382a0dd390d612d5391",
      "link": {
        "club": {
          "goals": "/v1/clubs/matches/goals?player=6099005600094382a0dd390d612d5391",
          "matches": "/v1/clubs/matches/lineups?player=6099005600094382a0dd390d612d5391",
          "offenses": "/v1/clubs/matches/offenses?player=6099005600094382a0dd390d612d5391",
          "penalties": "/v1/clubs/matches/penalties?player=6099005600094382a0dd390d612d5391",
          "subbedIn": "/v1/clubs/matches/substitutions?in_player=6099005600094382a0dd390d612d5391",
          "subbedOut": "/v1/clubs/matches/substitutions?out_player=6099005600094382a0dd390d612d5391"
        },
        "country": "/v1/countries/4bf4de9895094197860cd9e4e7ac778f",
        "natl": {
          "goals": "/v1/national/matches/goals?player=6099005600094382a0dd390d612d5391",
          "matches": "/v1/national/matches/lineups?player=6099005600094382a0dd390d612d5391",
          "offenses": "/v1/national/matches/offenses?player=6099005600094382a0dd390d612d5391",
          "penalties": "/v1/national/matches/penalties?player=6099005600094382a0dd390d612d5391",
          "subbedIn": "/v1/national/matches/substitutions?in_player=6099005600094382a0dd390d612d5391",
          "subbedOut": "/v1/national/matches/substitutions?out_player=6099005600094382a0dd390d612d5391"
        },
        "person": "/v1/persons/a7d43698f80042b1b59a608004f14fa6"
      },
      "person": "a7d43698f80042b1b59a608004f14fa6",
      "position": 10,
      "positionName": "Goalkeeper",
      "uri": "/v1/personnel/players/6099005600094382a0dd390d612d5391"
    },
    {
      "birthDate": "1983-06-11",
      "country": "4bf4de9895094197860cd9e4e7ac778f",
      "countryName": "Bosnia and Herzegovina",
      "fullName": "Dejan Bandovi\u0107",
      "id": "33733776a7db4be6bfcf7cd4d60b0041",
      "link": {
        "club": {
          "goals": "/v1/clubs/matches/goals?player=33733776a7db4be6bfcf7cd4d60b0041",
          "matches": "/v1/clubs/matches/lineups?player=33733776a7db4be6bfcf7cd4d60b0041",
          "offenses": "/v1/clubs/matches/offenses?player=33733776a7db4be6bfcf7cd4d60b0041",
          "penalties": "/v1/clubs/matches/penalties?player=33733776a7db4be6bfcf7cd4d60b0041",
          "subbedIn": "/v1/clubs/matches/substitutions?in_player=33733776a7db4be6bfcf7cd4d60b0041",
          "subbedOut": "/v1/clubs/matches/substitutions?out_player=33733776a7db4be6bfcf7cd4d60b0041"
        },
        "country": "/v1/countries/4bf4de9895094197860cd9e4e7ac778f",
        "natl": {
          "goals": "/v1/national/matches/goals?player=33733776a7db4be6bfcf7cd4d60b0041",
          "matches": "/v1/national/matches/lineups?player=33733776a7db4be6bfcf7cd4d60b0041",
          "offenses": "/v1/national/matches/offenses?player=33733776a7db4be6bfcf7cd4d60b0041",
          "penalties": "/v1/national/matches/penalties?player=33733776a7db4be6bfcf7cd4d60b0041",
          "subbedIn": "/v1/national/matches/substitutions?in_player=33733776a7db4be6bfcf7cd4d60b0041",
          "subbedOut": "/v1/national/matches/substitutions?out_player=33733776a7db4be6bfcf7cd4d60b0041"
        },
        "person": "/v1/persons/868ae0ac0fb14e078b5455fd0e52e1e4"
      },
      "person": "868ae0ac0fb14e078b5455fd0e52e1e4",
      "position": 10,
      "positionName": "Goalkeeper",
      "uri": "/v1/personnel/players/33733776a7db4be6bfcf7cd4d60b0041"
    }
  ]
}

OPTIONS /v1/personnel/players¶: Returns documentation of the football player resource.

Managers¶

GET /v1/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
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.
club	Club home/away match Information representations in which manager was involved.
natl	National team home/away match Information representations in which manager was involved.

Example:

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

GET /v1/personnel/managers?full_name=Luiz+Scolari 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 06:13:51 GMT
Connection: close
Content-Type: application/json
Content-Length: 1992

{
  "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/personnel/managers?records=10&page=1&full_name=Luiz+Scolari",
    "last": "/v1/personnel/managers?records=10&page=1&full_name=Luiz+Scolari",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "birthDate": "1948-11-09",
      "country": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "countryName": "Brazil",
      "fullName": "Luiz Scolari",
      "id": "7e9dc4c848ba442c8b05f30601e2d0b8",
      "link": {
        "club": {
          "awayMatches": "/v1/clubs/matches/info?away_manager=7e9dc4c848ba442c8b05f30601e2d0b8",
          "homeMatches": "/v1/clubs/matches/info?home_manager=7e9dc4c848ba442c8b05f30601e2d0b8"
        },
        "country": "/v1/countries/70ce7b6218a24e1d94c21ed8b5cd070c",
        "natl": {
          "awayMatches": "/v1/national/matches/info?away_manager=7e9dc4c848ba442c8b05f30601e2d0b8",
          "homeMatches": "/v1/national/matches/info?home_manager=7e9dc4c848ba442c8b05f30601e2d0b8"
        },
        "person": "/v1/persons/7ca2f07ccd2b45ebba051e7adf364151"
      },
      "person": "7ca2f07ccd2b45ebba051e7adf364151",
      "uri": "/v1/personnel/managers/7e9dc4c848ba442c8b05f30601e2d0b8"
    }
  ]
}

OPTIONS /v1/personnel/managers¶: Returns documentation of the football club manager resource.

Referees¶

GET /v1/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
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.
club	Club match Information representations in which referee officiated.
natl	National team match Information representations in which referee officiated.

Example:

Retrieve a specific referee’s record.

GET /v1/personnel/referees/cf09af2f18c2401b8370a9f0cc3afc7a 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 06:16:11 GMT
Connection: close
Content-Type: application/json
Content-Length: 1799

{
  "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/personnel/referees/cf09af2f18c2401b8370a9f0cc3afc7a?records=10&page=1",
    "last": "/v1/personnel/referees/cf09af2f18c2401b8370a9f0cc3afc7a?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "birthDate": "1970-12-10",
      "country": "6826af17dd544edb84be1f0222e5e8a1",
      "countryName": "Algeria",
      "fullName": "Djamel Haimoudi",
      "id": "cf09af2f18c2401b8370a9f0cc3afc7a",
      "link": {
        "club": {
          "matches": "/v1/clubs/matches/info?referee=cf09af2f18c2401b8370a9f0cc3afc7a"
        },
        "country": "/v1/countries/6826af17dd544edb84be1f0222e5e8a1",
        "natl": {
          "matches": "/v1/national/matches/info?referee=cf09af2f18c2401b8370a9f0cc3afc7a"
        },
        "person": "/v1/persons/f9140fabcfaf4b4b9dfb2c31dd5e9b7b"
      },
      "person": "f9140fabcfaf4b4b9dfb2c31dd5e9b7b",
      "uri": "/v1/personnel/referees/cf09af2f18c2401b8370a9f0cc3afc7a"
    }
  ]
}

OPTIONS /v1/personnel/referees¶: Returns documentation of the football match referee resource.