Search teams

Returns clubs and national teams, 20 per page by default. Search by name, or narrow it to one competition or season to get every team taking part.

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

const res = await fetch("https://api.soccer-data.co/v1/teams?search=Arsenal", {
  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/teams",
    params={"search": "Arsenal"},
    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/teams', ['search' => 'Arsenal'])
    ->json('data');

{
    "data": [
        {
            "id": "team_f0ibhxdw7hs5",
            "name": "Arsenal",
            "short_name": "Arsenal",
            "country": "England",
            "is_mens_team": true,
            "primary_competition": {
                "id": "competition_705uv6jm8myn",
                "name": "Premier League"
            }
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}

### GET /teams

Search teams

Returns clubs and national teams, 20 per page by default. Search by name, or narrow it to one competition or season to get every team taking part.
- A club's men's and women's sides can have the same name. Use is_mens_team to keep only the one you want.
- is_mens_team can be null when it isn't known, so don't assume it is always set.
- Asking for a page past the last one returns 400 PAGE_OUT_OF_RANGE.

Query parameters:
- `search` (string): Part of the team name, case-insensitive. With sort=relevance the closest match comes first.
- `competition_id` (string): Only teams in this competition. Without season_id, the latest season that has a table is used.
- `season_id` (string): Only teams in this season. Send it with competition_id; a season from another competition returns 400 SEASON_COMPETITION_MISMATCH.
- `country` (string): The team's country, case-insensitive, for example England.
- `is_mens_team` (boolean, one of true, false): true keeps men's teams only, false keeps women's teams only. Leave it out to get both.
- `sort` (string, default "relevance", one of relevance, name): relevance puts the best matches for search first; name orders results A to Z. Without search, both give A to Z.
- `page` (integer, default 1): Which page to return, starting at 1. meta.total_pages tells you how many there are.
- `per_page` (integer, default 20): How many results per page, from 1 to 100.

Response fields:
- `data[].id` (string): The team's id. Pass it as team_id to other endpoints.
- `data[].name` (string): The team's full name.
- `data[].short_name` (string): A shorter name for tight spaces.
- `data[].country` (string): The team's country.
- `data[].is_mens_team` (boolean): true for a men's team, false for a women's team, null when unknown.
- `data[].primary_competition` (object): The main competition the team plays in. Can be null.
- `data[].primary_competition.id` (string): That competition's id.
- `data[].primary_competition.name` (string): That competition's name.
- `meta.page` (integer): The page you're on.
- `meta.per_page` (integer): Results per page.
- `meta.total` (integer): Matching teams across all pages.
- `meta.total_pages` (integer): How many pages there are.

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