StatArena API
API documentation

Public reference for the v1 football data API.

StatArena API exposes authenticated REST endpoints for live scores, match detail, standings, schedules, squads, and historical football data. This reference is organized by entity so integration teams can move from discovery to implementation without guessing payload shapes.

Base host

Use the placeholder host https://{endpoint}.statarena-api.com while preparing integrations. Final production routing is intentionally not published on this page yet.

Versioning

All documented football services are currently published under /v1. New versions will be added as separate path versions instead of silently changing the existing contract.

Overview

The public contract uses JSON responses, API key authentication, and public StatArena entity IDs on route parameters. If a public ID cannot be translated back to the source provider identifier, the request fails with a client error instead of falling back to a raw provider ID.

The public contract accepts addon for expandable resources. Internal provider concepts such as include are not part of the website-facing API surface and should not be used by clients.

Global conventions

  • Country-specific routes accept ISO-style codes such as US and NO, and provider-style codes such as GB-ENG when exposed by the mapped entity model.
  • All /v1 endpoints require authentication.
  • Some match endpoints also accept legacy addons as a comma-separated query parameter for backward compatibility.

Not currently public

  • GET /v1/players/countries/:countryCode
  • GET /v1/coaches/countries/:countryCode
  • Operational and refresh routes used internally for cache management

Authentication

Send your API key either with the X-API-Key header or as a bearer token. The key is validated against plan status, expiration, and account state before the endpoint handler runs.

Header example 
curl "https://{endpoint}.statarena-api.com/v1/matches/live" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
Authentication error 
{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using the X-API-Key header or Authorization Bearer token."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Common response contract

Successful responses return a data payload plus request metadata. Error responses return a structured error object and a request_id that can be used for support and incident tracing.

Success envelope 
{
  "data": {},
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error envelope 
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Special case: GET /v1/matches/date/:date returns pagination inside data.pagination, not in meta.

Health

The health route is the only public route documented here that does not depend on API key authentication. Use it for basic service monitoring rather than business logic.

GET /health

Returns a minimal service-level heartbeat response.

Response example 
{
  "ok": true,
  "service": "statarena-api"
}

Leagues

League endpoints cover discovery, live competitions, country filtering, and the current competitions for a team.

Available routes

  • GET /v1/leagues
  • GET /v1/leagues/live
  • GET /v1/leagues/countries/:countryCode
  • GET /v1/leagues/teams/:teamId/current
  • GET /v1/leagues/:leagueId
GET /v1/leagues

Returns an array of league records. Collection routes return data as an array. The single-item route returns one league object.

Response shapes /v1/leagues, /live, /countries/:countryCode, and /teams/:teamId/current return arrays. /v1/leagues/:leagueId returns a single object.
Response example 
{
  "data": [
    {
      "id": "24222",
      "name": "Champions League",
      "active": true,
      "image_url": "https://cdn.statarena-api.com/images/soccer/leagues/2.png",
      "country_code": "EU"
    }
  ],
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_country_code",
    "message": "The countryCode parameter is not valid."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Matches

Matches are the richest part of the public contract. They cover live lists, date-based retrieval, ranges, team form, head-to-head data, and detailed match payloads with optional nested expansions.

Available routes

  • GET /v1/matches/live
  • GET /v1/matches/date/:date
  • GET /v1/matches/between/:startDate/:endDate
  • GET /v1/matches/teams/:teamId/form
  • GET /v1/matches/head-to-head/:firstTeam/:secondTeam
  • GET /v1/matches/:matchId
Route Useful query parameters Data shape
/v1/matches/live inPlay=true, addon, addons Array of match objects
/v1/matches/date/:date timezone, page, addon, addons Object with matches and pagination
/v1/matches/between/:startDate/:endDate timezone, page, addon, addons Array of match objects
/v1/matches/teams/:teamId/form leagueId Object
/v1/matches/head-to-head/:firstTeam/:secondTeam None Object
/v1/matches/:matchId addon, addons Single match object

Supported match add-ons

round, state, stadium, league, events, scores, coaches, lineups, periods, formations, statistics, participants, referees.

The public payload favors team, teams, and team_id naming even when the provider concept is named differently upstream.

GET /v1/matches/:matchId?addons=round,state,stadium,league,events,scores,coaches,lineups,periods,formations,statistics,participants,referees
Response example 
{
  "data": {
    "id": "19748782162",
    "league_id": "2472212",
    "season_id": "26760202",
    "stage_id": "77479518792",
    "group_id": null,
    "round_id": null,
    "state_id": "24122",
    "name": "Machida Zelvia vs Fujieda MYFC",
    "starting_at": "2026-07-18 07:30:00",
    "result_info": null,
    "leg": "1/1",
    "state": {
      "name": "Cancelled",
      "short_name": "CANC"
    },
    "stadium": {
      "id": "6034572",
      "name": "Machida Athletic Stadium"
    },
    "scores": [
      {
        "description": "CURRENT",
        "score": {
          "home": 2,
          "away": 1
        }
      }
    ],
    "teams": [
      {
        "id": "9270902",
        "name": "Machida Zelvia",
        "country_code": "JP",
        "location": "home"
      },
      {
        "id": "18284122",
        "name": "Fujieda MYFC",
        "country_code": "JP",
        "location": "away"
      }
    ]
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Pagination example for matches by date 
{
  "data": {
    "matches": [
      {
        "id": "19748782162",
        "league_id": "2472212",
        "season_id": "26760202",
        "stage_id": "77479518792",
        "state_id": "24122",
        "name": "Machida Zelvia vs Fujieda MYFC",
        "starting_at": "2026-07-18 01:30:00"
      }
    ],
    "pagination": {
      "count": 1,
      "has_more": true,
      "current_page": 1,
      "next_page": "https://{endpoint}.statarena-api.com/v1/matches/date/2026-07-18?timezone=America%2FMexico_City&page=2"
    }
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_match_addon",
    "message": "Unsupported live addon \"weather\".",
    "details": {
      "allowed_addons": [
        "round",
        "state",
        "stadium",
        "league",
        "events",
        "scores",
        "coaches",
        "lineups",
        "periods",
        "formations",
        "statistics",
        "participants",
        "referees"
      ]
    }
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Seasons

Season lookup is intentionally narrow and returns a single season object by public StatArena ID.

GET /v1/seasons/:seasonId
Response example 
{
  "data": {
    "id": "26646282",
    "league_id": "804722",
    "tie_breaker_rule": null,
    "name": "2026/2027",
    "finished": false,
    "pending": false,
    "is_current": true,
    "starting_at": "2026-08-01",
    "ending_at": "2027-05-31",
    "games_in_current_week": false
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_season_id",
    "message": "Invalid season id."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Stages

Stage routes support direct lookup and season-based listing. When required, stage payloads can be expanded with round data using addon=rounds.

  • GET /v1/stages/:stageId
  • GET /v1/stages/seasons/:seasonId
  • Optional add-on: addon=rounds
GET /v1/stages/:stageId?addon=rounds
Response example 
{
  "data": {
    "id": "77478660702",
    "sport_id": "1",
    "league_id": "804722",
    "season_id": "26646282",
    "type_id": "223",
    "name": "Regular Season",
    "sort_order": 1,
    "finished": false,
    "pending": false,
    "is_current": true,
    "starting_at": "2026-08-01",
    "ending_at": "2027-05-31",
    "rounds": [
      {
        "id": "395390302",
        "name": "Round 1",
        "is_current": false
      }
    ]
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_stage_id",
    "message": "Invalid stage id."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Rounds

Round routes support direct lookup and season-based listing. Round payloads can optionally embed mapped match objects using addon=matches.

  • GET /v1/rounds/:roundId
  • GET /v1/rounds/seasons/:seasonId
  • Optional add-on: addon=matches
  • Cache policy: 10 minutes
GET /v1/rounds/:roundId?addon=matches
Response example 
{
  "data": {
    "id": "395390302",
    "sport_id": "1",
    "league_id": "804722",
    "season_id": "26646282",
    "stage_id": "77478660702",
    "name": "Round 1",
    "finished": false,
    "is_current": false,
    "starting_at": "2026-08-01",
    "ending_at": "2026-08-03",
    "matches": [
      {
        "id": "19748782162",
        "name": "Machida Zelvia vs Fujieda MYFC",
        "starting_at": "2026-07-18 07:30:00"
      }
    ]
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_round_id",
    "message": "Invalid round id."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Teams

Team routes support single-team lookup, country collections, and season-based collections. Team payloads are intentionally compact and stable.

  • GET /v1/teams/:teamId
  • GET /v1/teams/countries/:countryCode
  • GET /v1/teams/seasons/:seasonId
GET /v1/teams/:teamId
Response example 
{
  "data": {
    "id": "18596182",
    "country_code": "GB-ENG",
    "stadium_id": "21852262",
    "gender": "male",
    "name": "Manchester City",
    "short_code": "MCI",
    "image_url": "https://cdn.statarena-api.com/images/soccer/teams/example.png",
    "founded": 1880,
    "type": "domestic",
    "placeholder": false,
    "last_played_at": "2026-07-19 19:00:00",
    "location": null,
    "winner": null,
    "table_position": null
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_country_code",
    "message": "The countryCode parameter is not valid."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Squads

Squad endpoints return team rosters either for the current setup or constrained to a specific season-team combination. The older extended squad variant is not part of the public contract.

  • GET /v1/squads/teams/:teamId
  • GET /v1/squads/seasons/:seasonId/teams/:teamId
GET /v1/squads/teams/:teamId
Response example 
{
  "data": [
    {
      "id": "squad_row_1",
      "team_id": "18596182",
      "player_id": "154432112",
      "position_id": "208",
      "jersey_number": 9,
      "player": {
        "id": "154432112",
        "display_name": "Erling Haaland"
      },
      "team": {
        "id": "18596182",
        "name": "Manchester City"
      }
    }
  ],
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_team_id",
    "message": "Invalid team id."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Players

Player detail is available by public player ID. Country collection routes are not currently enabled for the public website contract.

GET /v1/players/:playerId
Response example 
{
  "data": {
    "id": "154432112",
    "country_code": "GB-ENG",
    "position": "Attacker",
    "detailed_position": "Centre Forward",
    "type": "Attacker",
    "common_name": "E. Haaland",
    "firstname": "Erling Braut",
    "lastname": "Haaland",
    "name": "Erling Håland",
    "display_name": "Erling Haaland",
    "image_url": "https://cdn.statarena-api.com/images/soccer/players/example.png",
    "height": 195,
    "weight": 88,
    "date_of_birth": "2000-07-21",
    "gender": "male"
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_player_id",
    "message": "Invalid player id."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Coaches

Coach detail follows the same single-entity lookup pattern as players. Public country routes for coaches are intentionally omitted.

GET /v1/coaches/:coachId
Response example 
{
  "data": {
    "id": "37740500352",
    "country_code": "ES",
    "firstname": "Josep",
    "lastname": "Guardiola",
    "name": "Josep Guardiola",
    "display_name": "Pep Guardiola",
    "image_url": "https://cdn.statarena-api.com/images/soccer/coaches/example.png",
    "date_of_birth": "1971-01-18",
    "gender": "male"
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_coach_id",
    "message": "Invalid coach id."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Referees

Referee detail is exposed as a direct lookup resource with the same public ID rules used across the entity layer.

GET /v1/referees/:refereeId
Response example 
{
  "data": {
    "id": "16700152",
    "country_code": "AR",
    "firstname": "Facundo",
    "lastname": "Tello",
    "name": "Facundo Tello",
    "display_name": "Facundo Tello",
    "image_url": "https://cdn.statarena-api.com/images/soccer/referees/example.png",
    "date_of_birth": "1982-05-04",
    "gender": "male"
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_referee_id",
    "message": "Invalid referee id."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Stadiums

Stadium detail is exposed as a single object by public stadium ID.

GET /v1/stadiums/:stadiumId
Response example 
{
  "data": {
    "id": "21852262",
    "country_id": "826",
    "city_id": "2643743",
    "name": "Etihad Stadium",
    "address": "Ashton New Road",
    "zipcode": "M11 3FF",
    "latitude": "53.4831",
    "longitude": "-2.2004",
    "capacity": 53400,
    "image_path": "https://cdn.statarena-api.com/images/soccer/stadiums/example.png"
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_stadium_id",
    "message": "Invalid stadium id."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Standings

Standings are available by season, by round, and as a live table for specific leagues. Every variant returns an array of standing rows.

  • GET /v1/standings/seasons/:seasonId
  • GET /v1/standings/rounds/:roundId
  • GET /v1/standings/live/leagues/:leagueId
GET /v1/standings/seasons/:seasonId
Response example 
{
  "data": [
    {
      "id": "standing_row_1",
      "season_id": "26646282",
      "round_id": "395390302",
      "stage_id": "77478660702",
      "group_id": null,
      "team_id": "18596182",
      "position": 1,
      "result": null,
      "points": 87,
      "details": [],
      "form": ["W", "W", "D", "W", "W"]
    }
  ],
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_season_id",
    "message": "Invalid season id."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Schedules

Schedules return grouped match collections rather than raw fixtures. Public payloads use the key matches, not fixtures.

  • GET /v1/schedules/seasons/:seasonId
  • GET /v1/schedules/teams/:teamId
  • GET /v1/schedules/seasons/:seasonId/teams/:teamId
GET /v1/schedules/seasons/:seasonId/teams/:teamId
Response example 
{
  "data": {
    "id": null,
    "season_id": "26646282",
    "team_id": "18596182",
    "matches": [
      {
        "id": "19748782162",
        "league_id": "2472212",
        "season_id": "26760202",
        "name": "Machida Zelvia vs Fujieda MYFC",
        "starting_at": "2026-07-18 07:30:00"
      }
    ]
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_team_id",
    "message": "Invalid team id."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Top scorers

Top scorer endpoints are grouped by stage or season and require the query parameter type. StatArena requests a provider page size of 20 and exposes only the first 20 results. Public pagination is not used for this service.

  • GET /v1/topscorers/stages/:stageId?type=goal
  • GET /v1/topscorers/seasons/:seasonId?type=assist
  • Allowed type values: redcards, yellowcards, goal, assist, penalty, missedpenalty
GET /v1/topscorers/stages/:stageId?type=goal
Response example 
{
  "data": [
    {
      "id": "294414388292",
      "stage_id": "77478660702",
      "player_id": "184816182",
      "type_id": "236282",
      "position": 1,
      "total": 6,
      "team_type": "team",
      "team_id": "18658142",
      "player": {
        "id": "184816182",
        "display_name": "Lionel Messi",
        "country_code": "AR"
      },
      "team": {
        "id": "18658142",
        "name": "Argentina",
        "country_code": "AR"
      }
    }
  ],
  "meta": {
    "request_id": "req_01jexample"
  }
}
Error example 
{
  "error": {
    "code": "invalid_topscorer_type",
    "message": "Invalid topscorer type."
  },
  "meta": {
    "request_id": "req_01jexample"
  }
}

Error reference

Most client-side failures fall into a few predictable categories: authentication, invalid public IDs, invalid country codes, unsupported add-ons, invalid pages, and invalid top scorer types.

Code Status Meaning
missing_api_key 401 No API key was sent.
invalid_api_key 401 The provided key does not exist or does not match a valid record.
api_key_not_active 403 The key exists but is not currently active.
api_key_expired 403 The key exists but has expired.
invalid_country_code 400 The supplied country code cannot be mapped to a supported provider country.
invalid_page 400 The page query parameter is missing, non-integer, or lower than 1.
invalid_match_addon 400 An unsupported add-on was requested for a match endpoint.
invalid_topscorer_type 400 The type query parameter is not one of the supported public values.
Talk to the team