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. |
| GET | /api/v1/football/teams/{team_id}/stats?season_id={season_id} | Provider season summary with home, away and total splits; season_id is required. |
| GET | /api/v1/football/players/{player_id}/stats?season_id={season_id} | Player season statistics separated by team after transfers; season_id is required. |
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.
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.
GET /api/v1/football/teams?q=united&page=1&limit=25Current scope
The team record contains identity and country metadata. Dedicated endpoints expose squads, player profiles, reported absences, match lineups and match-level statistics where covered. Team and player season statistics require season_id and report available plus support_status. Missing fields stay null and genuine zeros stay zero. Player transfer seasons retain separate team rows; ratings and accuracy are not summed. A missing player on a partial ingestion page is not proof of an empty season. observed_at records the first observation of the current values, not necessarily the latest poll. No player xG is promised.