GETTING STARTED
GET/api/players
List players
Every player in the database — 1,700+ across current, classic, and all-time rosters — filterable on any attribute, sortable on any column. This is the endpoint the playground writes for you.
REQUIRES X-API-KEY HEADER · 500 REQ/HR FREE
QUERY PARAMETERS
eraNEW
string
curr (default), class, allt — or all to search every era in one call. teamType remains a supported alias.position
string
Position or group:
PG, SG, SF, PF, C — or guard, wing, big.team
string
Filter to one team by full name, e.g.
Los Angeles Lakers or 1995-96 Chicago Bulls.minRating / maxRating
number
Bound the overall rating, 0–99.
{attribute}_gte / _lteNEW
number
Bound any of the 40+ attributes in snake_case:
three_ball_gte=85, speed_lte=70, shot_iq_gte=90, …badge / badgeTierNEW
string
Filter by badge slug and optionally its exact tier:
badge=deadeye, badgeTier=Hall%20of%20Fame. Browse valid slugs in the badge almanac.sortNEW
string
Any attribute plus direction:
sort=overall:desc (default), sort=three_ball:asc, sort=name:asc.fieldsNEW
string
Trim the payload to just the fields you need:
fields=name,overall,slug.limit / cursor
number / string
Page size (max 100, default 50) and the offset cursor from
meta.pagination.nextCursor.RESPONSES ARE CACHED 1H AND SUPPORT ETAG / 304 REVALIDATION.
RELATED ENDPOINTS
/api/players/bulk
GET
The whole matching dataset in one call — one request against your rate limit.
/api/players/batch
POST
Resolve up to 100 names and/or slugs in one call, instead of searching one at a time. Names match case-, accent-, and punctuation-insensitively; unresolved entries come back in
meta.unmatched./api/players/slug/:slug
GET
One player, full detail: all attributes, badges, hot zones. Add
?teamType= for classic or all-time versions./api/players/:id/history
GET
Weekly rating snapshots — the dossier's history chart uses this.
curl 'https://api.nba2kapi.com/api/players?\ position=guard&era=all&\ three_ball_gte=85&sort=overall:desc' \ -H 'X-API-Key: YOUR_KEY'
RESPONSE200 OK
{
"success": true,
"data": [
{
"name": "Shai Gilgeous-Alexander",
"slug": "shai-gilgeous-alexander",
"team": "Oklahoma City Thunder",
"teamType": "curr",
"overall": 98,
"positions": ["PG", "SG"],
"attributes": { "threePointShot": 85, … },
"badges": { "total": 26, … }
},
…
],
"meta": { "pagination": { "total": 231, "nextCursor": "50" } }
}