Top Athletes

Get top players/athletes sorted by popularity

GET /athletes/top

Top Players

cURL

curl --request GET \
  --url https://v1.basketball.sportsapipro.com/athletes/top \
  --header 'x-api-key: <api-key>'

200

{
  "athletes": [
    {
      "id": 123,
      "name": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "position": "<string>",
      "team": {
        "id": 123,
        "name": "<string>",
        "score": 123,
        "imageUrl": "<string>"
      },
      "imageUrl": "<string>",
      "stats": {
        "pointsPerGame": 123,
        "reboundsPerGame": 123,
        "assistsPerGame": 123,
        "gamesPlayed": 123
      }
    }
  ]
}

Endpoint

GET https://v1.football.sportsapipro.com/athletes/top

Description

Returns the top athletes (players) sorted by popularity, along with related sports, countries, and competitions data. Useful for featuring popular players on dashboards and discovery pages.

Parameters

Parameter	Type	Description
limit	number	Number of top athletes to return (e.g., 10, 20, 50)
sports	number	Filter by sport ID (e.g., 1 for Football)
appTypeId	number	Client application type identifier (auto-resolved)
langId	number	Language identifier (auto-resolved)
timezoneName	string	Timezone for date/time values (auto-resolved, or specify e.g., America/New_York)
userCountryId	number	User’s country for localization (auto-resolved)

Parameters marked as “auto-resolved” are automatically determined based on request context. You can override timezoneName with a specific timezone (e.g., America/New_York). All date/time fields use ISO 8601 format with a dynamic timezone offset.

Request

cURL

curl -X GET "https://v1.football.sportsapipro.com/athletes/top?limit=10&sports=1" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "lastUpdateId": 0,
  "ttl": 300,
  "athletes": [
    {
      "id": 874,
      "name": "Lionel Messi",
      "shortName": "Messi",
      "nameForURL": "lionel-messi",
      "sportId": 1,
      "clubId": 54729,
      "nationalityId": 10,
      "nationalTeamId": 2378,
      "nationalityName": "Argentina",
      "age": 38,
      "gender": 1,
      "status": 1,
      "imageVersion": 0,
      "position": {
        "id": 4,
        "name": "Attacker"
      },
      "formationPosition": {
        "id": 14,
        "name": "Right Forward",
        "order": 14
      },
      "nationalTeamStatsText": "",
      "HasPenaltiesShots": false
    },
    {
      "id": 817,
      "name": "Cristiano Ronaldo",
      "shortName": "Ronaldo",
      "nameForURL": "cristiano-ronaldo",
      "sportId": 1,
      "clubId": 7549,
      "nationalityId": 11,
      "nationalTeamId": 5028,
      "nationalityName": "Portugal",
      "age": 40,
      "gender": 1,
      "status": 1,
      "imageVersion": 0,
      "position": {
        "id": 4,
        "name": "Attacker"
      },
      "formationPosition": {
        "id": 12,
        "name": "Centre Forward",
        "order": 12
      }
    }
  ],
  "sports": [
    {
      "id": 1,
      "name": "Football",
      "nameForURL": "football",
      "drawSupport": true,
      "imageVersion": 1
    }
  ],
  "countries": [
    {
      "id": 10,
      "name": "Argentina",
      "nameForURL": "argentina",
      "sportTypes": [1, 2, 5, 8, 9],
      "imageVersion": 1,
      "isInternational": false
    }
  ],
  "competitions": [
    {
      "id": 104,
      "countryId": 18,
      "sportId": 1,
      "name": "MLS",
      "longName": "Major League Soccer",
      "nameForURL": "mls",
      "popularityRank": 7747442,
      "imageVersion": 2,
      "color": "#325CB1"
    }
  ]
}

Response Fields

Root Level

Field	Type	Description
lastUpdateId	number	Internal versioning ID for incremental updates
ttl	number	Cache time-to-live in seconds
athletes	array	List of top athletes sorted by popularity
sports	array	List of sports referenced by athletes
countries	array	List of countries/nationalities referenced
competitions	array	List of competitions where athletes play

Athlete Object

Field	Type	Description
id	number	Unique athlete identifier
name	string	Full athlete name
shortName	string	Abbreviated display name (e.g., “Messi”)
nameForURL	string	URL-friendly athlete name
sportId	number	ID of the sport (1 = Football, 2 = Basketball)
clubId	number	ID of the current club/team (-1 if no club)
nationalityId	number	Country ID of nationality
nationalTeamId	number	ID of national team (if applicable)
nationalityName	string	Name of nationality country
age	number	Current age in years
gender	number	Gender (1 = male, 0 = female)
status	number	Player status (1 = active)
imageVersion	number	Version number for athlete image assets
position	object	General playing position
formationPosition	object	Specific formation position
nationalTeamStatsText	string	National team statistics summary
HasPenaltiesShots	boolean	Whether player has penalty statistics
createdAt	string	ISO timestamp when athlete was added

Position Object

Field	Type	Description
id	number	Position identifier
name	string	Position name (e.g., “Attacker”, “Midfielder”)

Formation Position Object

Field	Type	Description
id	number	Formation position identifier
name	string	Specific position name (e.g., “Right Forward”, “Centre Forward”)
shortName	string	Abbreviated position (e.g., “C” for Center)
order	number	Display order in formation

Position Types

Football Positions

ID	Name
1	Goalkeeper
2	Defender
3	Midfielder
4	Attacker

Formation Positions (Football)

ID	Name
1	Goalkeeper
2-5	Defenders (CB, LB, RB, etc.)
6-10	Midfielders (DM, CM, AM, etc.)
11-14	Forwards (LW, RW, ST, CF)

Top Football Players

Player	Club	Nationality	ID
Lionel Messi	Inter Miami	Argentina	874
Cristiano Ronaldo	Al Nassr	Portugal	817
Lamine Yamal	FC Barcelona	Spain	131182
Erling Haaland	Manchester City	Norway	65760
Kylian Mbappe	Real Madrid	France	39820
Kevin De Bruyne	Manchester City	Belgium	843
Jude Bellingham	Real Madrid	England	73000
Raphinha	FC Barcelona	Brazil	39789

Athlete Images

Athlete photos can be accessed via the images proxy:

https://v1.football.sportsapipro.com/images/athletes/{id}?version={imageVersion}

Example:

https://v1.football.sportsapipro.com/images/athletes/874?version=0

Authorizations

x-api-key · string · header · required

Your SportsAPI Pro API key

Query Parameters

competitionId · integer · required

Competition ID

Example:

132

Response

200 - application/json

Top athletes retrieved successfully

athletes · object[]

Show child attributes