​
Overview

The Season Team Roster API returns the registered team rosters for a specific season. The response identifies the tournament and season, then provides each team’s players together with their names, positions, date of birth, shirt number, and roster membership dates. By default, the endpoint returns all available teams and players in the requested season. Supply the optional team_id parameter when only one team’s roster is required. Roster records are season-specific. The join_date and leave_date fields describe the period during which a player belonged to that team’s season roster. A player whose leave_date is null has no recorded departure date for that roster entry.

​
Typical Use Cases

  • Build season squad and roster pages.
  • Retrieve all registered players across a competition season.
  • Request the season roster of one specific team.
  • Synchronize KoraStats team and player IDs with an external platform.
  • Track when players joined or left a team during the season.
  • Display player shirt numbers and primary or secondary positions.

​
Parameters

​
module
string
required
Fixed module name. Always use api.
​
api
string
required
Fixed API name. Always use SeasonTeamRoster.
​
season_id
integer
required
The unique KoraStats ID of the season whose team rosters should be returned.
​
team_id
integer
Optional KoraStats team ID. When supplied, the response is limited to that team’s roster within the requested season. Omit it to retrieve all teams.
​
version
string
required
API version. Use V2.
​
lang
string
Language used for supported names and response values. Use en for English or ar for Arabic. Defaults to English when omitted or unsupported.
​
response
string
required
Response format. Use json to receive a JSON response.
​
key
string
required
Your KoraStats API key. Keep this value confidential and send it only over HTTPS.

​
Endpoint

GET https://premium.korastats.pro/api.php

​
Code Examples

curl --get "https://premium.korastats.pro/api.php" \
  --data-urlencode "module=api" \
  --data-urlencode "api=SeasonTeamRoster" \
  --data-urlencode "season_id=SEASON_ID" \
  --data-urlencode "version=V2" \
  --data-urlencode "lang=en" \
  --data-urlencode "response=json" \
  --data-urlencode "key=YOUR_API_KEY"
Add team_id to any request when you need only one team. For example, use team_id=1 with season_id=SEASON_ID to request Zamalek’s roster for that season.

​
Response Example

{
  "result": true,
  "title": "Success",
  "message": "21 teams and 774 players retrieved.",
  "object": {
    "_type": "SEASON_TEAM_ROSTER",
    "tournament": {
      "_type": "TOURNAMENT",
      "id": 33,
      "name": "Egyptian Premier League"
    },
    "season": {
      "_type": "SEASON",
      "id": SEASON_ID,
      "name": "2025/2026"
    },
    "teams": [
      {
        "_type": "TEAM",
        "id": 1,
        "name": "Zamalek",
        "players": [
          {
            "_type": "PLAYER",
            "id": 23,
            "position": {
              "primary": {
                "id": 4,
                "name": "RB"
              },
              "secondary": {
                "id": 5,
                "name": "LB"
              }
            },
            "nickname": "Omar Gaber",
            "name": "Omar Mahmoud Sayed Gaber",
            "dob": "1992-01-30",
            "shirt_number": 4,
            "join_date": "2025-08-08",
            "leave_date": null
          },
          {
            "_type": "PLAYER",
            "id": 11073,
            "position": {
              "primary": {
                "id": 8,
                "name": "AM"
              },
              "secondary": {
                "id": 7,
                "name": "CM"
              }
            },
            "nickname": "Nasser Maher",
            "name": "Nasser Maher Abdul Hamid Abdul Hamid",
            "dob": "1997-02-08",
            "shirt_number": 22,
            "join_date": "2025-08-08",
            "leave_date": "2025-11-02"
          }
        ]
      },
      {
        "_type": "TEAM",
        "id": 2,
        "name": "Al Ahly FC",
        "players": [
          {
            "_type": "PLAYER",
            "id": 426,
            "position": {
              "primary": {
                "id": 1,
                "name": "GK"
              },
              "secondary": {
                "id": 1,
                "name": "GK"
              }
            },
            "nickname": "Mohamed El Shenawy",
            "name": "Mohamed El Sayed Mohamed",
            "dob": "1988-12-18",
            "shirt_number": 1,
            "join_date": "2025-08-08",
            "leave_date": null
          }
        ]
      }
    ]
  }
}

​
Response Fields

FieldTypeDescription
resultbooleanIndicates whether the request was processed successfully.
titlestringShort response title.
messagestringHuman-readable summary including the number of teams and players retrieved.
objectobjectSeason roster payload.
object._typestringObject type discriminator. Returns SEASON_TEAM_ROSTER.
object.tournamentobjectTournament associated with the requested season.
object.tournament._typestringObject type discriminator. Returns TOURNAMENT.
object.tournament.idintegerUnique KoraStats tournament ID.
object.tournament.namestringTournament name in the requested language when available.
object.seasonobjectRequested season identity.
object.season._typestringObject type discriminator. Returns SEASON.
object.season.idintegerUnique KoraStats season ID.
object.season.namestringSeason name.
object.teamsarrayTeams returned for the season. Contains all teams unless team_id limits the request.
object.teams[]._typestringObject type discriminator. Returns TEAM.
object.teams[].idintegerUnique KoraStats team ID.
object.teams[].namestringTeam name in the requested language when available.
object.teams[].playersarrayPlayer roster entries registered for the team in the season.
object.teams[].players[]._typestringObject type discriminator. Returns PLAYER.
object.teams[].players[].idintegerUnique KoraStats player ID.
object.teams[].players[].positionobjectPlayer’s primary and secondary positions.
object.teams[].players[].position.primary.idinteger or nullKoraStats ID of the player’s primary position, or null when unknown.
object.teams[].players[].position.primary.namestringAbbreviation of the player’s primary position; may be empty when unknown.
object.teams[].players[].position.secondary.idinteger or nullKoraStats ID of the player’s secondary position, or null when unknown.
object.teams[].players[].position.secondary.namestringAbbreviation of the player’s secondary position; may be empty when unknown.
object.teams[].players[].nicknamestringPlayer’s commonly used or display name.
object.teams[].players[].namestringPlayer’s full name.
object.teams[].players[].dobstring or nullPlayer’s date of birth in YYYY-MM-DD format, or null when unavailable.
object.teams[].players[].shirt_numberinteger or nullPlayer’s shirt number for the roster, when available.
object.teams[].players[].join_datestring or nullDate the player joined the season roster, in YYYY-MM-DD format.
object.teams[].players[].leave_datestring or nullDate the player left the season roster, or null when no departure is recorded.
The teams and players arrays are shortened in the example for readability. The actual response contains all available records matching the requested season_id and optional team_id.