Players

Retrieve detailed player information via one of our 5 player endpoints. You can retrieve more detailed information by using the correct includes. This section will briefly discuss all the options available to request players.

An overview of all the options available:

  • GET Player by ID: returns player information from your requested player id.

  • GET Players by Country ID: returns player information from your requested country id.

  • GET Players Search by Name: returns all the players that match your search query.

  • GET Last Updated Players: returns all the players that have received updates in the past two hours.

For all the player endpoints the base URL is the same:

https://api.sportmonks.com/v3/football/players/

Per endpoint the rest of the URL requires additional information. We will explain this per endpoint.

Requesting players

GET All Players

As mentioned before, a great starting point for your football application is to gather an overview of all the data available in your subscription. For players, you can do this via the GET All Players endpoint.

The URL to get all your players is the same as the base URL for players. All you have to do is authorize the request with your API token. Check our authentication section for more info.

https://api.sportmonks.com/v3/football/players?api_token=YOUR_TOKEN
Response

  "data": [
    {
      "id": 14,
      "sport_id": 1,
      "country_id": 320,
      "nationality_id": 320,
      "city_id": null,
      "position_id": 221,
      "detailed_position_id": null,
      "type_id": 25,
      "common_name": "D. Agger",
      "firstname": "Daniel Munthe",
      "lastname": "Agger",
      "name": "Daniel Munthe Agger",
      "display_name": "D. Agger",
      "image_path": "https://cdn.sportmonks.com/images/soccer/players/14/14.png",
      "height": 191,
      "weight": 84,
      "date_of_birth": "1984-12-12",
      "gender": "male"
    },
    {
      "id": 21,
      "sport_id": 1,
      "country_id": 455,
      "nationality_id": 455,
      "city_id": null,
      "position_id": 26,
      "detailed_position_id": null,
      "type_id": 26,
      "common_name": "L. Miller",
      "firstname": "Liam",
      "lastname": "Miller",
      "name": "Liam Miller",
      "display_name": "Liam Miller",
      "image_path": "https://cdn.sportmonks.com/images/soccer/players/21/21.png",
      "height": 170,
      "weight": 66,
      "date_of_birth": "1981-02-13",
      "gender": "male"
    },

You will receive the nationality of the player, the (detailed) position, height, weight, gender, date of birth and all kinds of information about the player’s name.

Now that you've requested all the Players, you also know their unique player id. You can use this id in the second option: GET Player by ID.

GET Players by ID

This endpoint is useful if you only want information about one particular player. You need to add the player_id to your request:

https://api.sportmonks.com/v3/football/players/{player_id}

For example, if you’re interested in information about Joe Hart (player id: 275).

https://api.sportmonks.com/v3/football/players/275?api_token=YOUR_TOKEN
Response
{
  "data": {
    "id": 275,
    "sport_id": 1,
    "country_id": 462,
    "nationality_id": 462,
    "city_id": null,
    "position_id": 24,
    "detailed_position_id": 24,
    "type_id": 24,
    "common_name": "J. Hart",
    "firstname": "Joe",
    "lastname": "Hart",
    "name": "Joe Hart",
    "display_name": "Joe Hart",
    "image_path": "https://cdn.sportmonks.com/images/soccer/players/19/275.png",
    "height": 196,
    "weight": 91,
    "date_of_birth": "1987-04-19",
    "gender": "male"
  },

GET Players by Country ID

This endpoint returns player information from your requested country id. Comes in handy when you want to know which players you have included in your subscription and want to list them per country. You need to add the country_id to your request:

https://api.sportmonks.com/v3/football/players/country/{country_id}

For example, if you want to show all English (country id: 462) players available in your subscription:

https://api.sportmonks.com/v3/football/players/countries/462?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 1595,
      "sport_id": 1,
      "country_id": 462,
      "nationality_id": 462,
      "city_id": null,
      "position_id": 25,
      "detailed_position_id": null,
      "type_id": 25,
      "common_name": "I. Iriekpen",
      "firstname": "Izzy",
      "lastname": "Iriekpen",
      "name": "Izzy Iriekpen",
      "display_name": "Izzy Iriekpen",
      "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
      "height": 185,
      "weight": 77,
      "date_of_birth": "1982-05-14",
      "gender": "male"
    },
    {
      "id": 10399,
      "sport_id": 1,
      "country_id": 462,
      "nationality_id": 462,
      "city_id": null,
      "position_id": 27,
      "detailed_position_id": 151,
      "type_id": 27,
      "common_name": "J. Morias",
      "firstname": "Junior",
      "lastname": "Morias",
      "name": "Junior Morias",
      "display_name": "Junior Morias",
      "image_path": "https://cdn.sportmonks.com/images/soccer/players/31/10399.png",
      "height": 173,
      "weight": 68,
      "date_of_birth": "1995-07-04",
      "gender": "male"
    },
    //and more

GET Players Search by Name

This endpoint returns all the players based on your search query. This might come in handy if you cannot find a player. To search on a players' name, you’ll need to add /search/{search_query} to the players base URL:

https://api.sportmonks.com/v3/football/players/search/{search_query}

For example, if you could not find Joe Hart:

https://api.sportmonks.com/v3/football/players/search/joe hart?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 275,
      "sport_id": 1,
      "country_id": 462,
      "nationality_id": 462,
      "city_id": null,
      "position_id": 24,
      "detailed_position_id": 24,
      "type_id": 24,
      "common_name": "J. Hart",
      "firstname": "Joe",
      "lastname": "Hart",
      "name": "Joe Hart",
      "display_name": "Joe Hart",
      "image_path": "https://cdn.sportmonks.com/images/soccer/players/19/275.png",
      "height": 196,
      "weight": 91,
      "date_of_birth": "1987-04-19",
      "gender": "male"
    }
  ],

The more complete your search query is, the more relevant response you’ll get.

GET Last Updated Players

This endpoint returns all the players that have received updates in the past two hours. This comes in handy to keep your database in sync. You’ll need to add /latest to the players base URL:

https://api.sportmonks.com/v3/football/players/latest

https://api.sportmonks.com/v3/football/players/latest?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 32315,
      "sport_id": 1,
      "country_id": 1578,
      "nationality_id": 1578,
      "city_id": null,
      "position_id": 27,
      "detailed_position_id": 151,
      "type_id": 27,
      "common_name": "B. Finne",
      "firstname": "Bård",
      "lastname": "Finne",
      "name": "Bård Finne",
      "display_name": "Bard Finne",
      "image_path": "https://cdn.sportmonks.com/images/soccer/players/27/32315.png",
      "height": 173,
      "weight": 70,
      "date_of_birth": "1995-02-13",
      "gender": "male"
    },
    {
      "id": 151353,
      "sport_id": 1,
      "country_id": 320,
      "nationality_id": 320,
      "city_id": null,
      "position_id": 25,
      "detailed_position_id": 155,
      "type_id": 25,
      "common_name": "T. Søndergaard Lange",
      "firstname": "Thor",
      "lastname": "Søndergaard Lange",
      "name": "Thor Søndergaard Lange",
      "display_name": "Thor Lange",
      "image_path": "https://cdn.sportmonks.com/images/soccer/players/25/151353.png",
      "height": 183,
      "weight": 85,
      "date_of_birth": "1993-08-04",
      "gender": "male"
    }
  ],

Adding useful information

As you’ve learnt in the includes tutorial, you can enrich your request with includes. This section will discuss some of the most common requests on the player’s endpoints.

First, you can find a list of all available includes on the endpoint pages. For the players, the most commonly used includes are metadata, position and statistics.

  • metadata: Returns information about a player's preferred foot.

  • position: Position returns the position of the player. Is he a goalkeeper, defender, midfielder or attacker? The include detailedPosition returns if a defender is a leftback, rightback, center back and so on.

  • statistics: This include returns player statistics.

For example, if we want all the above information about James Tavernier (player id: 758).

https://api.sportmonks.com/v3/football/players/758?api_token=YOUR_TOKEN&include=metadata;position;detailedPosition;statistics
Response
{
  "data": {
    "id": 758,
    "sport_id": 1,
    "country_id": 462,
    "nationality_id": 462,
    "city_id": null,
    "position_id": 25,
    "detailed_position_id": 154,
    "type_id": 25,
    "common_name": "J. Tavernier",
    "firstname": "James",
    "lastname": "Tavernier",
    "name": "James Tavernier",
    "display_name": "James Tavernier",
    "image_path": "https://cdn.sportmonks.com/images/soccer/players/22/758.png",
    "height": 182,
    "weight": 75,
    "date_of_birth": "1991-10-31",
    "gender": "male",
    "metadata": [
      {
        "id": 154942,
        "metadatable_type": "player",
        "metadatable_id": 758,
        "type_id": 229,
        "value_type": "string",
        "values": "right"
      }
    ],
    "position": {
      "id": 25,
      "name": "Defender",
      "code": "defender",
      "developer_name": "DEFENDER",
      "model_type": "position",
      "stat_group": null
    },
    "detailed_position": {
      "id": 154,
      "name": "Right Back",
      "code": "right-back",
      "developer_name": "RIGHT_BACK",
      "model_type": "position",
      "stat_group": null
    },
    "statistics": [
      {
        "id": 27268457,
        "player_id": 758,
        "team_id": 17,
        "season_id": 24,
        "position_id": null,
        "jersey_number": 2
      },
      //and more

Selecting and filtering

In our filtering tutorial you’ve learnt how to select specific fields or filter only on the data you’re interested in. By default, our API returns a set of data related to the player. We can imagine you’re not interested in all the player data the API returns. Let’s say you’re only interested in the player name and image.

We’re going to use the GET All Players endpoint for this example.

You can add the &select= parameter followed by the fields you want. In our case: name,image_path. This results in the below request and response:

https://api.sportmonks.com/v3/football/players/758?api_token=YOUR_TOKEN&select=name,image_path
Response
{
  "data": {
    "name": "James Tavernier",
    "image_path": "https://cdn.sportmonks.com/images/soccer/players/22/758.png",
    "id": 758,
    "country_id": 462,
    "sport_id": 1,
    "city_id": null,
    "position_id": 25,
    "detailed_position_id": 154,
    "nationality_id": 462
  },

Check our filtering tutorial for more information and tips.

Last updated