Search players

Find players by name, list the players currently at a club, or load several players at once by id. Results come 20 per page. Most apps start here to get the player id that the other player endpoints need.

curl "https://api.soccer-data.co/v1/players?search=Saka" \
  -H "X-Api-Key: $SOCCER_DATA_KEY"

const res = await fetch("https://api.soccer-data.co/v1/players?search=Saka", {
  headers: { "X-Api-Key": process.env.SOCCER_DATA_KEY },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.soccer-data.co/v1/players",
    params={"search": "Saka"},
    headers={"X-Api-Key": os.environ["SOCCER_DATA_KEY"]},
)
data = res.json()["data"]

$data = Http::withHeaders(['X-Api-Key' => env('SOCCER_DATA_KEY')])
    ->get('https://api.soccer-data.co/v1/players', ['search' => 'Saka'])
    ->json('data');

{
    "data": [
        {
            "id": "player_ul3vc6om97u5",
            "name": "Bukayo Saka",
            "first_name": "Bukayo",
            "last_name": "Saka",
            "position": "F",
            "date_of_birth": "2001-09-05",
            "age": 25,
            "nationality": "England",
            "height_cm": 178,
            "current_team": {
                "id": "team_f0ibhxdw7hs5",
                "name": "Arsenal",
                "jersey_number": 7
            }
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}

### GET /players

Search players

Find players by name, list the players currently at a club, or load several players at once by id. Results come 20 per page. Most apps start here to get the player id that the other player endpoints need.
- search needs at least 3 characters. A shorter term returns 400 BAD_REQUEST.
- Search ignores case and accents, and treats hyphens and spaces as the same thing.
- When you search, meta.total is capped at 1,000 even if more players match.
- team_id looks at each player's current club only, so players who have left don't show up.

Query parameters:
- `search` (string): Part of the player's name, at least 3 characters. With sort=relevance the closest matches come first.
- `team_id` (string): Only players who are at this team right now.
- `position` (string, one of G, D, M, F): Only players in this position: G goalkeeper, D defender, M midfielder, F forward.
- `player_ids` (string): Comma-separated player ids. Returns just those players, which is handy for refreshing a saved list in one request.
- `sort` (string, default "relevance", one of relevance, name): relevance puts the best search matches first. name sorts A to Z. Without search, results are always A to Z.
- `page` (integer, default 1): Page number, starting at 1. meta.total_pages tells you how many pages there are.
- `per_page` (integer, default 20): Players per page, from 1 to 100.

Response fields:
- `data[]` (array): The players on this page.
- `data[].id` (string): The player's id. Pass it to the other player endpoints.
- `data[].name` (string): The name the player is usually shown under.
- `data[].first_name` (string): First name.
- `data[].last_name` (string): Last name.
- `data[].position` (string): G, D, M or F. An empty string when the position isn't known.
- `data[].date_of_birth` (string|null): Date of birth as YYYY-MM-DD. Null when unknown.
- `data[].age` (integer|null): Age in years. Null when the date of birth is unknown.
- `data[].nationality` (string): Country the player represents, by name.
- `data[].height_cm` (integer|null): Height in centimetres. Null when unknown.
- `data[].current_team` (object): The club the player is at now.
- `data[].current_team.id` (string): The club's team id.
- `data[].current_team.name` (string): The club's name.
- `data[].current_team.jersey_number` (integer|null): Shirt number at that club. Null when unknown.
- `meta.page` (integer): The page you asked for.
- `meta.per_page` (integer): Players per page.
- `meta.total` (integer): Matching players across all pages. Capped at 1,000 when you search.
- `meta.total_pages` (integer): Number of pages available.

Example: curl "https://api.soccer-data.co/v1/players?search=Saka" -H "X-Api-Key: $SOCCER_DATA_KEY"