Teams endpoints · Stats API

Squad, standings and absences

A team resource carries identity only. Squad membership, table position and reported absences are separate sub-resources, because each changes on a different cadence: identity is effectively static, a table moves weekly, and an injury list moves daily.

Method	Path	Purpose
GET	/api/v1/football/teams/{team_id}/players	Current-season squad with shirt number and position.
GET	/api/v1/football/teams/{team_id}/standings	Current-season table positions.
GET	/api/v1/football/teams/{team_id}/injuries-suspensions	Reported absences, where covered.

Worked example: resolving a team once

Search by name once, then keep the Stats API identifier. Team names are not stable keys — clubs rename, and the same club is spelled differently by different sources. The identifier is the thing that does not move.

Example

GET /api/v1/football/teams?q=arsenal&limit=3
Authorization: Bearer sapi_live_...

{
  "data": [
    { "id": "team_9f771cb2e781", "name": "Arsenal",
      "country_name": "England", "logo_url": "https://..." }
  ],
  "meta": { "page": 1, "limit": 3, "total": 1 }
}

GET /api/v1/football/teams/team_9f771cb2e781/players

{
  "data": [
    { "id": "player_9c1b2f4ea77d", "name": "Example Player",
      "shirt_number": 8, "position": "Midfielder",
      "season": { "id": "season_31a7c0d94b26", "name": "2026" } }
  ],
  "meta": { "count": 1 }
}

Coverage, and why a list can be empty

Squad and absence data are not available for every competition. Injury reporting in particular is sparse: most competitions supply none at all.

An empty list is therefore an ordinary answer, and the response distinguishes the two reasons it can occur. Treating both as an error produces false alarms on competitions that simply are not covered.

Response	Meaning	Correct handling
coverage.injuries_available true, empty data	Covered, and nothing is currently reported.	Show "no absences reported".
coverage.injuries_available false, empty data	The source does not supply this competition.	Show "not covered". Do not retry.
404 not_found	The team identifier does not exist.	Fix the identifier.
Squad empty mid-season	Roster sync has not yet run for that team.	Retry later; it fills on the weekly cycle.

Available operations

Method	Path	Purpose
GET	/api/v1/football/teams	Search and paginate the team catalog.
GET	/api/v1/football/teams/{team_id}	Retrieve one team by Stats API public ID.

Search

Use q for a case-insensitive name search. Results can contain clubs with similar names, so retain the returned ID and country metadata rather than matching by display name alone.