CBA API
Welcome to the BALLDONTLIE CBA API, covering the Chinese Basketball Association. An API key is required. You can obtain an API key by creating a free account on our website. Read the authentication section to learn how to use the API key.
Take a look at our other APIs.
AI-Powered Integration
Using the OpenAPI Specification with AI
Our complete OpenAPI specification allows AI assistants to automatically understand and interact with our API. Simply share the spec URL with your AI assistant and describe what you want to build—the AI will handle the technical implementation.
Getting Started with AI:
- Copy this URL:
https://www.balldontlie.io/openapi/cba.yml - Share it with your preferred AI assistant (ChatGPT, the agent, Gemini, etc.)
- Tell the AI what you want to build (e.g., "Create a dashboard showing today's CBA games")
- The AI will read the OpenAPI spec and write the code for you
Example prompts to try:
- "Using the OpenAPI spec at https://www.balldontlie.io/openapi/cba.yml, show me how to get CBA player season averages"
- "Read the BALLDONTLIE OpenAPI spec and create a Python script that fetches today's CBA games"
- "Help me understand the available CBA endpoints from this OpenAPI spec: https://www.balldontlie.io/openapi/cba.yml"
This makes it incredibly easy for non-technical users, analysts, and researchers to leverage our sports data without needing to learn programming from scratch.
Account Tiers
Annual billing saves 20%. Choose monthly or annual billing when subscribing. Annual prices are charged once per year.
| Plan | Monthly (USD) | Annual (USD) |
|---|---|---|
| ALL-STAR | $9.99/month | $95.90/year |
| GOAT | $39.99/month | $383.90/year |
| ALL-ACCESS | $299.99/month | $2,879.90/year |
There are three different account tiers which provide you access to different types of data. Visit our website to create an account for free.
Paid tiers do not apply across sports. The tier you purchase for CBA will not automatically be applied to other sports. You can purchase the ALL-ACCESS ($299.99/mo) tier to get access to every endpoint for every sport.
Read the table below to see the breakdown.
| Endpoint | Free | ALL-STAR | GOAT |
|---|---|---|---|
| Teams | Yes | Yes | Yes |
| Players | Yes | Yes | Yes |
| Games | Yes | Yes | Yes |
| Team Rosters | No | Yes | Yes |
| Standings | No | Yes | Yes |
| Lineups | No | Yes | Yes |
| Scoring | No | Yes | Yes |
| Player Stats | No | No | Yes |
| Team Stats | No | No | Yes |
| Season Averages | No | No | Yes |
The feature breakdown per tier is shown in the table below.
| Tier | Requests / Min | $USD / mo. |
|---|---|---|
| GOAT | 600 | 39.99 |
| ALL-STAR | 60 | 9.99 |
| Free | 5 | 0 |
48-hour free trial
Every paid sport offers a 48-hour trial of the GOAT tier (all endpoints, 5 req/min during the trial). ALL-ACCESS is also available as a 48-hour trial with the same 5 req/min trial limit. A payment method is required at signup; there is no charge until the trial ends, and you can cancel anytime from your dashboard. One trial per sport per account. Existing ALL-STAR subscribers may trial the GOAT upgrade for their sports.
Authentication
Send your API key in the Authorization header on every request. Base URL: https://api.balldontlie.io/cba/v1.
Conventions
- Season is the start year:
2025means the 2025–26 season. - Season types:
regular,playoffs,preseason,all_star,relegation. - Timestamps use UTC. Game date filters use the calendar date in
Asia/Shanghai; start and end dates are inclusive. - Availability varies by game and season. Missing values are
null, not zero. - Array filters require brackets:
team_ids[]=14&team_ids[]=20. Different filters are combined; values within one array match any listed value. - Omitted season filters do not default to the current season.
Pagination
List endpoints return {data: [...], meta: {...}}. Use per_page (default 25, range 1–100). Pass meta.next_cursor as cursor for the next page, keeping the same filters. Stop when next_cursor is absent. A full page can be followed by an empty final page. prev_cursor, when present, echoes the cursor supplied in the request; it is not a previous-page link.
Errors
| Status | Meaning |
|---|---|
| 400 | Invalid query or path parameter. Validation errors return an errors array with param and error; a reversed date range returns an error string. |
| 401 | Missing/invalid API key or insufficient subscription access. Body: Unauthorized. |
| 404 | Requested team, player, or game does not exist. Body: Not Found. |
| 429 | Rate limit exceeded. Retry after the rate-limit window. |
| 500 | Server error. |
Statistics Fields
All statistics below are numbers or null. Season averages may contain fractional values. seconds and plus_minus appear only in player game statistics.
| Field | Meaning |
|---|---|
pts |
Points |
reb |
Total rebounds |
oreb |
Offensive rebounds |
dreb |
Defensive rebounds |
ast |
Assists |
stl |
Steals |
blk |
Blocks |
turnover |
Turnovers |
pf |
Personal fouls |
fgm |
Field goals made |
fga |
Field goals attempted |
fg3m |
Three-pointers made |
fg3a |
Three-pointers attempted |
ftm |
Free throws made |
fta |
Free throws attempted |
seconds |
Playing time in seconds |
plus_minus |
Plus/minus |
Teams
Teams in the Chinese Basketball Association.
Minimum tier: Free.
List teams
GET /cba/v1/teams
curl -g 'https://api.balldontlie.io/cba/v1/teams?per_page=1' \
-H 'Authorization: YOUR_API_KEY'
const response = await fetch('https://api.balldontlie.io/cba/v1/teams?per_page=1', {
headers: { Authorization: 'YOUR_API_KEY' }
});
const result = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/cba/v1/teams?per_page=1',
headers={'Authorization': 'YOUR_API_KEY'},
)
response.raise_for_status()
result = response.json()
Example response:
{
"data": [
{
"id": 1,
"name": "北京控股"
}
],
"meta": {
"next_cursor": 1,
"per_page": 1
}
}
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Cursor from meta.next_cursor. Omit for the first page. |
per_page |
integer | No | Results per page. Default 25; maximum 100. |
search |
string | No | Case-insensitive substring match on name. |
Response fields
| Field | Type | Description |
|---|---|---|
id |
integer | ID. |
name |
string | Name. |
Get a team
GET /cba/v1/teams/{id}
Replace {id} with a team ID. Returns one object in data, without pagination metadata, or HTTP 404 if not found.
curl 'https://api.balldontlie.io/cba/v1/teams/14' \
-H 'Authorization: YOUR_API_KEY'
{
"data": {
"id": 14,
"name": "上海久事"
}
}
Players
Player profiles. Unavailable profile fields are null.
Minimum tier: Free.
List players
GET /cba/v1/players
curl -g 'https://api.balldontlie.io/cba/v1/players?per_page=1' \
-H 'Authorization: YOUR_API_KEY'
const response = await fetch('https://api.balldontlie.io/cba/v1/players?per_page=1', {
headers: { Authorization: 'YOUR_API_KEY' }
});
const result = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/cba/v1/players?per_page=1',
headers={'Authorization': 'YOUR_API_KEY'},
)
response.raise_for_status()
result = response.json()
Example response:
{
"data": [
{
"id": 1,
"name": "白啸桐",
"birth_date": "2007-05-18",
"height": 186,
"weight": 83,
"nationality": "中国",
"position": "控球后卫"
}
],
"meta": {
"next_cursor": 1,
"per_page": 1
}
}
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Cursor from meta.next_cursor. Omit for the first page. |
per_page |
integer | No | Results per page. Default 25; maximum 100. |
search |
string | No | Case-insensitive substring match on name. |
player_ids[] |
array | No | Filter by player IDs from /players. |
Response fields
| Field | Type | Description |
|---|---|---|
id |
integer | ID. |
name |
string | Name. |
birth_date |
string or null | Date of birth (YYYY-MM-DD). |
height |
number or null | Height. |
weight |
number or null | Weight. |
nationality |
string or null | Nationality. |
position |
string or null | Playing position. |
Get a player
GET /cba/v1/players/{id}
Replace {id} with a player ID. Returns one object in data, without pagination metadata, or HTTP 404 if not found.
curl 'https://api.balldontlie.io/cba/v1/players/261' \
-H 'Authorization: YOUR_API_KEY'
{
"data": {
"id": 261,
"name": "古德温",
"birth_date": "1995-10-02",
"height": 183,
"weight": 81,
"nationality": "美国",
"position": "得分后卫/控球后卫"
}
}
Games
Scheduled and completed games with teams and scores. Game timestamps are UTC; date filters use Asia/Shanghai.
Minimum tier: Free.
List games
GET /cba/v1/games
curl -g 'https://api.balldontlie.io/cba/v1/games?per_page=1&dates[]=2026-06-05' \
-H 'Authorization: YOUR_API_KEY'
const response = await fetch('https://api.balldontlie.io/cba/v1/games?per_page=1&dates[]=2026-06-05', {
headers: { Authorization: 'YOUR_API_KEY' }
});
const result = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/cba/v1/games?per_page=1&dates[]=2026-06-05',
headers={'Authorization': 'YOUR_API_KEY'},
)
response.raise_for_status()
result = response.json()
Example response:
{
"data": [
{
"id": 17705,
"season": 2025,
"season_type": "playoffs",
"datetime": "2026-06-05T11:35:00.000Z",
"status": "final",
"current_period": 4,
"home_team": {
"id": 14,
"name": "上海久事"
},
"visitor_team": {
"id": 20,
"name": "浙江浙商证券"
},
"home_team_score": 103,
"visitor_team_score": 82
}
],
"meta": {
"next_cursor": 17705,
"per_page": 1
}
}
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Cursor from meta.next_cursor. Omit for the first page. |
per_page |
integer | No | Results per page. Default 25; maximum 100. |
team_ids[] |
array | No | Filter by team IDs from /teams. |
season_type |
string | No | Season type: regular, playoffs, preseason, all_star, or relegation. |
seasons[] |
array | No | Season start years, for example 2025 for 2025–26. |
dates[] |
array | No | Game dates (YYYY-MM-DD) in Asia/Shanghai. |
start_date |
string | No | Inclusive first game date (YYYY-MM-DD) in Asia/Shanghai. |
end_date |
string | No | Inclusive last game date (YYYY-MM-DD) in Asia/Shanghai; must be on or after start_date. |
Response fields
| Field | Type | Description |
|---|---|---|
id |
integer | ID. |
season |
integer | Season start year. |
season_type |
string or null | Season type. |
datetime |
string | Game timestamp in UTC. |
status |
string | Game status. |
current_period |
integer or null | Current period number. |
home_team |
object | Home team. |
visitor_team |
object | Visiting team. |
home_team_score |
integer or null | Home team score. |
visitor_team_score |
integer or null | Visiting team score. |
Get a game
GET /cba/v1/games/{id}
Replace {id} with a game ID. Returns one object in data, without pagination metadata, or HTTP 404 if not found.
curl 'https://api.balldontlie.io/cba/v1/games/17705' \
-H 'Authorization: YOUR_API_KEY'
{
"data": {
"id": 17705,
"season": 2025,
"season_type": "playoffs",
"datetime": "2026-06-05T11:35:00.000Z",
"status": "final",
"current_period": 4,
"home_team": {
"id": 14,
"name": "上海久事"
},
"visitor_team": {
"id": 20,
"name": "浙江浙商证券"
},
"home_team_score": 103,
"visitor_team_score": 82
}
}
Team Rosters
Team rosters by season. A player can appear for more than one team.
Minimum tier: ALL-STAR.
List team rosters
GET /cba/v1/team_rosters
curl -g 'https://api.balldontlie.io/cba/v1/team_rosters?per_page=1&season=2025&team_ids[]=14' \
-H 'Authorization: YOUR_API_KEY'
const response = await fetch('https://api.balldontlie.io/cba/v1/team_rosters?per_page=1&season=2025&team_ids[]=14', {
headers: { Authorization: 'YOUR_API_KEY' }
});
const result = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/cba/v1/team_rosters?per_page=1&season=2025&team_ids[]=14',
headers={'Authorization': 'YOUR_API_KEY'},
)
response.raise_for_status()
result = response.json()
Example response:
{
"data": [
{
"id": 13765,
"team": {
"id": 14,
"name": "上海久事"
},
"player": {
"id": 244,
"name": "崔晓龙",
"birth_date": "1999-02-19",
"height": 193,
"weight": 87,
"nationality": "中国",
"position": "控球后卫/得分后卫"
},
"season": 2025,
"jersey_number": "5"
}
],
"meta": {
"next_cursor": 13765,
"per_page": 1
}
}
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Cursor from meta.next_cursor. Omit for the first page. |
per_page |
integer | No | Results per page. Default 25; maximum 100. |
team_ids[] |
array | No | Filter by team IDs from /teams. |
player_ids[] |
array | No | Filter by player IDs from /players. |
season |
integer | No | Season start year, for example 2025 for 2025–26. |
Response fields
| Field | Type | Description |
|---|---|---|
id |
integer | ID. |
team |
object | Team. |
player |
object | Player. |
season |
integer | Season start year. |
jersey_number |
string or null | Jersey number. |
Standings
Team standings by season.
Minimum tier: ALL-STAR.
List standings
GET /cba/v1/standings
curl -g 'https://api.balldontlie.io/cba/v1/standings?per_page=1&season=2025&team_ids[]=14' \
-H 'Authorization: YOUR_API_KEY'
const response = await fetch('https://api.balldontlie.io/cba/v1/standings?per_page=1&season=2025&team_ids[]=14', {
headers: { Authorization: 'YOUR_API_KEY' }
});
const result = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/cba/v1/standings?per_page=1&season=2025&team_ids[]=14',
headers={'Authorization': 'YOUR_API_KEY'},
)
response.raise_for_status()
result = response.json()
Example response:
{
"data": [
{
"id": 1509,
"team": {
"id": 14,
"name": "上海久事"
},
"season": 2025,
"rank": 1,
"games_played": 42,
"wins": 38,
"losses": 4,
"points_for": 4206,
"points_against": 3508
}
],
"meta": {
"next_cursor": 1509,
"per_page": 1
}
}
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Cursor from meta.next_cursor. Omit for the first page. |
per_page |
integer | No | Results per page. Default 25; maximum 100. |
team_ids[] |
array | No | Filter by team IDs from /teams. |
season |
integer | No | Season start year, for example 2025 for 2025–26. |
Response fields
| Field | Type | Description |
|---|---|---|
id |
integer | ID. |
team |
object | Team. |
season |
integer | Season start year. |
rank |
integer | Standing rank. |
games_played |
integer | Games played. |
wins |
integer | Wins. |
losses |
integer | Losses. |
points_for |
integer or null | Points scored. |
points_against |
integer or null | Points conceded. |
Lineups
Game participants with jersey numbers and starter status. This is not a complete list of inactive players.
Minimum tier: ALL-STAR.
List lineups
GET /cba/v1/lineups
curl -g 'https://api.balldontlie.io/cba/v1/lineups?per_page=1&game_id=17705' \
-H 'Authorization: YOUR_API_KEY'
const response = await fetch('https://api.balldontlie.io/cba/v1/lineups?per_page=1&game_id=17705', {
headers: { Authorization: 'YOUR_API_KEY' }
});
const result = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/cba/v1/lineups?per_page=1&game_id=17705',
headers={'Authorization': 'YOUR_API_KEY'},
)
response.raise_for_status()
result = response.json()
Example response:
{
"data": [
{
"id": 266511,
"team": {
"id": 14,
"name": "上海久事"
},
"player": {
"id": 261,
"name": "古德温",
"birth_date": "1995-10-02",
"height": 183,
"weight": 81,
"nationality": "美国",
"position": "得分后卫/控球后卫"
},
"game_id": 17705,
"jersey_number": "0",
"starter": true
}
],
"meta": {
"next_cursor": 266511,
"per_page": 1
}
}
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Cursor from meta.next_cursor. Omit for the first page. |
per_page |
integer | No | Results per page. Default 25; maximum 100. |
team_ids[] |
array | No | Filter by team IDs from /teams. |
player_ids[] |
array | No | Filter by player IDs from /players. |
game_id |
integer | Yes | Required game ID from /games. |
Response fields
| Field | Type | Description |
|---|---|---|
id |
integer | ID. |
team |
object | Team. |
player |
object | Player. |
game_id |
integer | Game ID from /games. |
jersey_number |
string or null | Jersey number. |
starter |
boolean or null | Whether the player started the game. |
Scoring
Cumulative scores ordered by period and sequence. These are scoring updates, not play-by-play events. Corrections can reduce a score.
Minimum tier: ALL-STAR.
List scoring
GET /cba/v1/scoring
curl -g 'https://api.balldontlie.io/cba/v1/scoring?per_page=1&game_id=17705' \
-H 'Authorization: YOUR_API_KEY'
const response = await fetch('https://api.balldontlie.io/cba/v1/scoring?per_page=1&game_id=17705', {
headers: { Authorization: 'YOUR_API_KEY' }
});
const result = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/cba/v1/scoring?per_page=1&game_id=17705',
headers={'Authorization': 'YOUR_API_KEY'},
)
response.raise_for_status()
result = response.json()
Example response:
{
"data": [
{
"id": 493756,
"game_id": 17705,
"period": 1,
"sequence": 1,
"home_team_score": 2,
"visitor_team_score": 0
}
],
"meta": {
"next_cursor": 493756,
"per_page": 1
}
}
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Cursor from meta.next_cursor. Omit for the first page. |
per_page |
integer | No | Results per page. Default 25; maximum 100. |
game_id |
integer | Yes | Required game ID from /games. |
period |
integer | No | Period number. Team statistics accept 0 for full-game totals; scoring starts at 1. Maximum 100. |
Response fields
| Field | Type | Description |
|---|---|---|
id |
integer | ID. |
game_id |
integer | Game ID from /games. |
period |
integer | Period number; 0 denotes full-game totals in team statistics. |
sequence |
integer | Order within the period. |
home_team_score |
integer | Home team score. |
visitor_team_score |
integer | Visiting team score. |
Player Stats
Player box scores by game. Missing statistics are null, not zero.
Minimum tier: GOAT.
List player stats
GET /cba/v1/player_stats
curl -g 'https://api.balldontlie.io/cba/v1/player_stats?per_page=1&game_ids[]=17705' \
-H 'Authorization: YOUR_API_KEY'
const response = await fetch('https://api.balldontlie.io/cba/v1/player_stats?per_page=1&game_ids[]=17705', {
headers: { Authorization: 'YOUR_API_KEY' }
});
const result = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/cba/v1/player_stats?per_page=1&game_ids[]=17705',
headers={'Authorization': 'YOUR_API_KEY'},
)
response.raise_for_status()
result = response.json()
Example response:
{
"data": [
{
"id": 266511,
"team": {
"id": 14,
"name": "上海久事"
},
"player": {
"id": 261,
"name": "古德温",
"birth_date": "1995-10-02",
"height": 183,
"weight": 81,
"nationality": "美国",
"position": "得分后卫/控球后卫"
},
"game_id": 17705,
"pts": 25,
"reb": 4,
"oreb": 0,
"dreb": 4,
"ast": 4,
"stl": 2,
"blk": 1,
"turnover": 4,
"pf": 2,
"fgm": 10,
"fga": 19,
"fg3m": 0,
"fg3a": 5,
"ftm": 5,
"fta": 5,
"seconds": 2134,
"plus_minus": 26
}
],
"meta": {
"next_cursor": 266511,
"per_page": 1
}
}
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Cursor from meta.next_cursor. Omit for the first page. |
per_page |
integer | No | Results per page. Default 25; maximum 100. |
team_ids[] |
array | No | Filter by team IDs from /teams. |
player_ids[] |
array | No | Filter by player IDs from /players. |
season_type |
string | No | Season type: regular, playoffs, preseason, all_star, or relegation. |
seasons[] |
array | No | Season start years, for example 2025 for 2025–26. |
game_ids[] |
array | No | Filter by game IDs from /games. |
dates[] |
array | No | Game dates (YYYY-MM-DD) in Asia/Shanghai. |
start_date |
string | No | Inclusive first game date (YYYY-MM-DD) in Asia/Shanghai. |
end_date |
string | No | Inclusive last game date (YYYY-MM-DD) in Asia/Shanghai; must be on or after start_date. |
Response fields
| Field | Type | Description |
|---|---|---|
id |
integer | ID. |
team |
object | Team. |
player |
object | Player. |
game_id |
integer | Game ID from /games. |
pts |
number or null | Points |
reb |
number or null | Total rebounds |
oreb |
number or null | Offensive rebounds |
dreb |
number or null | Defensive rebounds |
ast |
number or null | Assists |
stl |
number or null | Steals |
blk |
number or null | Blocks |
turnover |
number or null | Turnovers |
pf |
number or null | Personal fouls |
fgm |
number or null | Field goals made |
fga |
number or null | Field goals attempted |
fg3m |
number or null | Three-pointers made |
fg3a |
number or null | Three-pointers attempted |
ftm |
number or null | Free throws made |
fta |
number or null | Free throws attempted |
seconds |
number or null | Playing time in seconds |
plus_minus |
number or null | Plus/minus |
Team Stats
Team statistics by game and period. Use period=0 for full-game totals.
Minimum tier: GOAT.
List team stats
GET /cba/v1/team_stats
curl -g 'https://api.balldontlie.io/cba/v1/team_stats?per_page=1&game_ids[]=17705' \
-H 'Authorization: YOUR_API_KEY'
const response = await fetch('https://api.balldontlie.io/cba/v1/team_stats?per_page=1&game_ids[]=17705', {
headers: { Authorization: 'YOUR_API_KEY' }
});
const result = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/cba/v1/team_stats?per_page=1&game_ids[]=17705',
headers={'Authorization': 'YOUR_API_KEY'},
)
response.raise_for_status()
result = response.json()
Example response:
{
"data": [
{
"id": 131624,
"team": {
"id": 14,
"name": "上海久事"
},
"game_id": 17705,
"period": 0,
"pts": 103,
"reb": 45,
"oreb": 16,
"dreb": 29,
"ast": 17,
"stl": 10,
"blk": 4,
"turnover": 10,
"pf": 23,
"fgm": 39,
"fga": 78,
"fg3m": 5,
"fg3a": 21,
"ftm": 20,
"fta": 24
}
],
"meta": {
"next_cursor": 131624,
"per_page": 1
}
}
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Cursor from meta.next_cursor. Omit for the first page. |
per_page |
integer | No | Results per page. Default 25; maximum 100. |
team_ids[] |
array | No | Filter by team IDs from /teams. |
season_type |
string | No | Season type: regular, playoffs, preseason, all_star, or relegation. |
period |
integer | No | Period number. Team statistics accept 0 for full-game totals; scoring starts at 1. Maximum 100. |
seasons[] |
array | No | Season start years, for example 2025 for 2025–26. |
game_ids[] |
array | No | Filter by game IDs from /games. |
dates[] |
array | No | Game dates (YYYY-MM-DD) in Asia/Shanghai. |
start_date |
string | No | Inclusive first game date (YYYY-MM-DD) in Asia/Shanghai. |
end_date |
string | No | Inclusive last game date (YYYY-MM-DD) in Asia/Shanghai; must be on or after start_date. |
Response fields
| Field | Type | Description |
|---|---|---|
id |
integer | ID. |
team |
object | Team. |
game_id |
integer | Game ID from /games. |
period |
integer | Period number; 0 denotes full-game totals in team statistics. |
pts |
number or null | Points |
reb |
number or null | Total rebounds |
oreb |
number or null | Offensive rebounds |
dreb |
number or null | Defensive rebounds |
ast |
number or null | Assists |
stl |
number or null | Steals |
blk |
number or null | Blocks |
turnover |
number or null | Turnovers |
pf |
number or null | Personal fouls |
fgm |
number or null | Field goals made |
fga |
number or null | Field goals attempted |
fg3m |
number or null | Three-pointers made |
fg3a |
number or null | Three-pointers attempted |
ftm |
number or null | Free throws made |
fta |
number or null | Free throws attempted |
Season Averages
Player averages by team, season, and season type. A player who changes teams can have multiple rows. Missing averages are null.
Minimum tier: GOAT.
List season averages
GET /cba/v1/season_averages
curl -g 'https://api.balldontlie.io/cba/v1/season_averages?per_page=1&season=2025&team_ids[]=14' \
-H 'Authorization: YOUR_API_KEY'
const response = await fetch('https://api.balldontlie.io/cba/v1/season_averages?per_page=1&season=2025&team_ids[]=14', {
headers: { Authorization: 'YOUR_API_KEY' }
});
const result = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/cba/v1/season_averages?per_page=1&season=2025&team_ids[]=14',
headers={'Authorization': 'YOUR_API_KEY'},
)
response.raise_for_status()
result = response.json()
Example response:
{
"data": [
{
"id": 21674,
"team": {
"id": 14,
"name": "上海久事"
},
"player": {
"id": 261,
"name": "古德温",
"birth_date": "1995-10-02",
"height": 183,
"weight": 81,
"nationality": "美国",
"position": "得分后卫/控球后卫"
},
"season": 2025,
"season_type": "regular",
"games_played": 42,
"pts": 15.9,
"reb": 3.8,
"oreb": 0.7,
"dreb": 3.1,
"ast": 7.1,
"stl": 0.8,
"blk": 0.1,
"turnover": 2.1,
"pf": 1.5,
"fgm": 5.9,
"fga": 10.9,
"fg3m": 1.4,
"fg3a": 4,
"ftm": 2.8,
"fta": 4
}
],
"meta": {
"next_cursor": 21674,
"per_page": 1
}
}
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Cursor from meta.next_cursor. Omit for the first page. |
per_page |
integer | No | Results per page. Default 25; maximum 100. |
team_ids[] |
array | No | Filter by team IDs from /teams. |
player_ids[] |
array | No | Filter by player IDs from /players. |
season |
integer | No | Season start year, for example 2025 for 2025–26. |
season_type |
string | No | Season type: regular, playoffs, preseason, all_star, or relegation. |
Response fields
| Field | Type | Description |
|---|---|---|
id |
integer | ID. |
team |
object | Team. |
player |
object | Player. |
season |
integer | Season start year. |
season_type |
string or null | Season type. |
games_played |
number or null | Games played. |
pts |
number or null | Points |
reb |
number or null | Total rebounds |
oreb |
number or null | Offensive rebounds |
dreb |
number or null | Defensive rebounds |
ast |
number or null | Assists |
stl |
number or null | Steals |
blk |
number or null | Blocks |
turnover |
number or null | Turnovers |
pf |
number or null | Personal fouls |
fgm |
number or null | Field goals made |
fga |
number or null | Field goals attempted |
fg3m |
number or null | Three-pointers made |
fg3a |
number or null | Three-pointers attempted |
ftm |
number or null | Free throws made |
fta |
number or null | Free throws attempted |