# API-NBA

> Follow the NBA with API-NBA: every game since 2015 with its score by quarter, both teams' and every player's box scores, team season statistics, teams, players and the standings, and the summer leagues. Needs an API-SPORTS key; the free plan allows 100 requests a day.

App · Sports · 12 actions. Web page: https://docs.lodol.com/docs/integrations/api-nba

## Actions

### Find players

Find players by name, by team and season, by country or by ID, each with their birth, height, weight, college, years in the NBA and number and position in each league.

**Inputs**

- Player ID (`player_id`, text): Optional. Only this player, such as 882 for Jayson Tatum.
- Search (`search`, text): Optional. Only names containing this, at least 3 characters.
- Team (`team_id`, text): Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
- Season (`season`, number): Optional. Only this season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.
- Country (`country`, text): Optional. Only players born in this country, such as USA.

**Outputs**

- `count` (number): How many came back.
- `players` (list): The players.

**Example output**

```json
{
  "count": 1,
  "players": [
    {
      "affiliation": "Duke/USA",
      "birth": {
        "country": "USA",
        "date": "1998-03-03"
      },
      "college": "Duke",
      "firstname": "Jayson",
      "height": {
        "feet": 6,
        "inches": 8,
        "meters": 2.03
      },
      "id": 882,
      "lastname": "Tatum",
      "leagues": [
        {
          "active": true,
          "jersey": null,
          "league": "standard",
          "position": "F-G"
        }
      ],
      "name": "Jayson Tatum",
      "nba": {
        "pro": 4,
        "start": 2017
      },
      "weight": {
        "kilograms": 95.3,
        "pounds": 210
      }
    }
  ]
}
```

### Find teams

Find teams by name, code, league, conference, division or ID, each with its city, logo and place in each league. The API's teams include All-Star sides and international clubs; Franchises only keeps the 30 NBA franchises.

**Inputs**

- Team ID (`team_id`, text): Optional. Only this team, by ID, such as 2.
- Search (`search`, text): Optional. Only names containing this, at least 3 characters.
- Code (`code`, text): Optional. Only the team with this code, such as BOS.
- League (`league`, text): Optional. Only this league: the NBA, or one of its summer leagues. One of: `standard` (The NBA), `vegas` (Las Vegas Summer League), `utah` (Salt Lake City Summer League), `sacramento` (California Classic), `orlando` (Orlando Summer League), `africa` (NBA Africa Game).
- Conference (`conference`, text): Optional. Only this conference: East or West. One of: `East`, `West`.
- Division (`division`, text): Optional. Only this division, such as Atlantic. One of: `Atlantic`, `Central`, `Southeast`, `Northwest`, `Pacific`, `Southwest`.
- Franchises only (`franchises_only`, true/false): Optional. Only the 30 NBA franchises, leaving out All-Star sides and international clubs.

**Outputs**

- `count` (number): How many came back.
- `teams` (list): The teams.

**Example output**

```json
{
  "count": 1,
  "teams": [
    {
      "all_star": false,
      "city": "Boston",
      "code": "BOS",
      "id": 2,
      "leagues": [
        {
          "conference": "East",
          "division": "Atlantic",
          "league": "standard"
        },
        {
          "conference": "summer",
          "division": null,
          "league": "vegas"
        },
        {
          "conference": "East",
          "division": "Atlantic",
          "league": "utah"
        },
        {
          "conference": "East",
          "division": "Atlantic",
          "league": "sacramento"
        }
      ],
      "logo": "https://upload.wikimedia.org/wikipedia/en/8/8f/Boston_Celtics.svg",
      "name": "Boston Celtics",
      "nba_franchise": true,
      "nickname": "Celtics"
    }
  ]
}
```

### Get a game

Get one game by ID: when and where, its status, both teams and the score by quarter.

**Inputs**

- Game ID (`game_id`, text, required): The game's ID, such as 14145. List games returns them.

**Outputs**

- `arena` (object): Where it is played.
- `date` (object): When.
- `id` (number): The game's ID.
- `lead_changes` (number): Lead changes, when known.
- `league` (text): The league, such as standard for the NBA.
- `nugget` (text): A note on the game, when the API has one.
- `officials` (list): The referees, when the API has them.
- `periods` (object): Quarters.
- `scores` (object): Both sides' scores.
- `season` (number): The season, as the year it starts in.
- `stage` (number): 1 for the pre-season, 2 the regular season, 3 the play-in and playoffs.
- `status` (object): Where the game stands.
- `teams` (object): Both sides.
- `times_tied` (number): Times the score was tied, when known.

**Example output**

```json
{
  "arena": {
    "city": "Chicago",
    "country": null,
    "name": "United Center",
    "state": "IL"
  },
  "date": {
    "duration": null,
    "end": null,
    "start": "2024-10-27T00:00:00.000Z"
  },
  "id": 14145,
  "lead_changes": null,
  "league": "standard",
  "nugget": null,
  "officials": [],
  "periods": {
    "current": 4,
    "end_of_period": false,
    "total": 4
  },
  "scores": {
    "home": {
      "linescore": [
        21,
        18,
        26,
        30
      ],
      "points": 95
    },
    "visitors": {
      "linescore": [
        26,
        33,
        29,
        26
      ],
      "points": 114
    }
  },
  "season": 2024,
  "stage": 2,
  "status": {
    "clock": null,
    "halftime": false,
    "long": "Finished",
    "short": 3
  },
  "teams": {
    "home": {
      "code": "CHI",
      "id": 6,
      "logo": "https://upload.wikimedia.org/wikipedia/en/6/67/Chicago_Bulls_logo.svg",
      "name": "Chicago Bulls",
      "nickname": "Bulls"
    },
    "visitors": {
      "code": "OKC",
      "id": 25,
      "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
      "name": "Oklahoma City Thunder",
      "nickname": "Thunder"
    }
  },
  "times_tied": null
}
```

### Get account status

See the connected key's API-NBA plan, when it renews, and how many of today's requests are used and left. It is free: it never counts against the day.

**Inputs**: None.

**Outputs**

- `active` (true/false): True while the subscription is active.
- `daily_limit` (number): Requests allowed a day.
- `plan` (text): The plan, such as Free.
- `requests_remaining` (number): Requests left today; the day starts at midnight UTC.
- `requests_today` (number): Requests used today.
- `subscription_end` (text): When the plan renews or ends.

**Example output**

```json
{
  "active": true,
  "daily_limit": 100,
  "plan": "Free",
  "requests_remaining": 88,
  "requests_today": 12,
  "subscription_end": "2027-10-01T00:00:00+00:00"
}
```

### Get player box scores

Get players' box scores: every player's in a game, or a player's or a team's in every game of a season. Each has minutes, points, shooting, rebounds, assists, steals, blocks, turnovers and plus-minus.

**Inputs**

- Game ID (`game_id`, text): Optional. Every player's box score in this game. Set this, or a season with a player or a team.
- Player ID (`player_id`, text): Optional. Only this player's box scores, such as 882. Needs a season.
- Team (`team_id`, text): Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
- Season (`season`, number): Optional. Only this season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.

**Outputs**

- `count` (number): How many came back.
- `players` (list): The players' box scores.

**Example output**

```json
{
  "count": 2,
  "players": [
    {
      "assists": 2,
      "blocks": 0,
      "comment": null,
      "field_goals": {
        "attempted": 8,
        "made": 1,
        "percentage": 12.5
      },
      "fouls": 1,
      "free_throws": {
        "attempted": 0,
        "made": 0,
        "percentage": null
      },
      "game_id": 14145,
      "minutes": "26",
      "player": {
        "firstname": "Patrick",
        "id": 2664,
        "lastname": "Williams",
        "name": "Patrick Williams"
      },
      "plus_minus": -12,
      "points": 3,
      "position": null,
      "rebounds": {
        "defensive": 6,
        "offensive": 2,
        "total": 8
      },
      "steals": 1,
      "team": {
        "code": "CHI",
        "id": 6,
        "logo": "https://upload.wikimedia.org/wikipedia/en/6/67/Chicago_Bulls_logo.svg",
        "name": "Chicago Bulls",
        "nickname": "Bulls"
      },
      "three_pointers": {
        "attempted": 4,
        "made": 1,
        "percentage": 25.0
      },
      "turnovers": 1
    },
    {
      "assists": 2,
      "blocks": 1,
      "comment": null,
      "field_goals": {
        "attempted": 12,
        "made": 7,
        "percentage": 58.3
      },
      "fouls": 2,
      "free_throws": {
        "attempted": 2,
        "made": 2,
        "percentage": 100.0
      },
      "game_id": 14145,
      "minutes": "33",
      "player": {
        "firstname": "Nikola",
        "id": 534,
        "lastname": "Vucevic",
        "name": "Nikola Vucevic"
      },
      "plus_minus": -14,
      "points": 18,
      "position": null,
      "rebounds": {
        "defensive": 10,
        "offensive": 3,
        "total": 13
      },
      "steals": 0,
      "team": {
        "code": "CHI",
        "id": 6,
        "logo": "https://upload.wikimedia.org/wikipedia/en/6/67/Chicago_Bulls_logo.svg",
        "name": "Chicago Bulls",
        "nickname": "Bulls"
      },
      "three_pointers": {
        "attempted": 2,
        "made": 2,
        "percentage": 100.0
      },
      "turnovers": 3
    }
  ]
}
```

### Get standings

Get a season's standings by conference and record: each team's wins and losses in all, at home, away and in the last ten, its win percentage, its places in its conference and division, games behind and streak. Narrow to one conference, division or team.

**Inputs**

- League (`league`, text, required): The league: the NBA, or one of its summer leagues. One of: `standard` (The NBA), `vegas` (Las Vegas Summer League), `utah` (Salt Lake City Summer League), `sacramento` (California Classic), `orlando` (Orlando Summer League), `africa` (NBA Africa Game).
- Season (`season`, number, required): The season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.
- Team (`team_id`, text): Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
- Conference (`conference`, text): Optional. Only this conference: East or West. One of: `East`, `West`.
- Division (`division`, text): Optional. Only this division, such as Atlantic. One of: `Atlantic`, `Central`, `Southeast`, `Northwest`, `Pacific`, `Southwest`.

**Outputs**

- `count` (number): How many came back.
- `standings` (list): Each team's line, by conference and then best record first.

**Example output**

```json
{
  "count": 2,
  "standings": [
    {
      "conference": {
        "name": "east",
        "rank": 1
      },
      "division": {
        "name": "atlantic",
        "rank": 1
      },
      "games_behind": null,
      "league": "standard",
      "losses": {
        "away": 14,
        "home": 4,
        "last_ten": 3,
        "percentage": 0.22,
        "total": 18
      },
      "season": 2023,
      "streak": 2,
      "team": {
        "code": "BOS",
        "id": 2,
        "logo": "https://upload.wikimedia.org/wikipedia/en/8/8f/Boston_Celtics.svg",
        "name": "Boston Celtics",
        "nickname": "Celtics"
      },
      "tie_breaker_points": null,
      "win_streak": true,
      "wins": {
        "away": 27,
        "home": 37,
        "last_ten": 7,
        "percentage": 0.78,
        "total": 64
      }
    },
    {
      "conference": {
        "name": "west",
        "rank": 1
      },
      "division": {
        "name": "northwest",
        "rank": 1
      },
      "games_behind": null,
      "league": "standard",
      "losses": {
        "away": 17,
        "home": 8,
        "last_ten": 3,
        "percentage": 0.305,
        "total": 25
      },
      "season": 2023,
      "streak": 5,
      "team": {
        "code": "OKC",
        "id": 25,
        "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
        "name": "Oklahoma City Thunder",
        "nickname": "Thunder"
      },
      "tie_breaker_points": null,
      "win_streak": true,
      "wins": {
        "away": 24,
        "home": 33,
        "last_ten": 7,
        "percentage": 0.695,
        "total": 57
      }
    }
  ]
}
```

### Get team box scores

Get both teams' box scores for a game: points, shooting with its percentages, rebounds, assists, steals, blocks, turnovers, fouls and plus-minus.

**Inputs**

- Game ID (`game_id`, text, required): The game's ID, such as 14145. List games returns them.

**Outputs**

- `count` (number): How many came back.
- `game_id` (number): The game asked about.
- `teams` (list): Each side's box score.

**Example output**

```json
{
  "count": 2,
  "game_id": 14145,
  "teams": [
    {
      "assists": 23,
      "blocks": 2,
      "field_goals": {
        "attempted": 92,
        "made": 32,
        "percentage": 34.8
      },
      "fouls": 19,
      "free_throws": {
        "attempted": 22,
        "made": 16,
        "percentage": 72.7
      },
      "minutes": "240:00",
      "plus_minus": -19,
      "points": 95,
      "rebounds": {
        "defensive": 50,
        "offensive": 11,
        "total": 61
      },
      "steals": 6,
      "team": {
        "code": "CHI",
        "id": 6,
        "logo": "https://upload.wikimedia.org/wikipedia/en/6/67/Chicago_Bulls_logo.svg",
        "name": "Chicago Bulls",
        "nickname": "Bulls"
      },
      "three_pointers": {
        "attempted": 53,
        "made": 15,
        "percentage": 28.3
      },
      "turnovers": 26
    },
    {
      "assists": 21,
      "blocks": 5,
      "field_goals": {
        "attempted": 107,
        "made": 45,
        "percentage": 42.1
      },
      "fouls": 18,
      "free_throws": {
        "attempted": 20,
        "made": 16,
        "percentage": 80.0
      },
      "minutes": "240:00",
      "plus_minus": 19,
      "points": 114,
      "rebounds": {
        "defensive": 45,
        "offensive": 9,
        "total": 54
      },
      "steals": 15,
      "team": {
        "code": "OKC",
        "id": 25,
        "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
        "name": "Oklahoma City Thunder",
        "nickname": "Thunder"
      },
      "three_pointers": {
        "attempted": 40,
        "made": 8,
        "percentage": 20.0
      },
      "turnovers": 10
    }
  ]
}
```

### Get team statistics

Get a team's totals for a season, or for its pre-season, regular season or play-in and playoffs: games, points, shooting with its percentages, rebounds, assists, steals, blocks, turnovers and plus-minus.

**Inputs**

- Team (`team_id`, text, required): The team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
- Season (`season`, number, required): The season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.
- Stage (`stage`, text): Optional. Only this part of the season: the pre-season, the regular season, or the play-in and playoffs. One of: `1` (Pre-season), `2` (Regular season), `3` (Play-in and playoffs).

**Outputs**

- `assists` (number): Assists.
- `blocks` (number): Blocks.
- `field_goals` (object): Field goals.
- `fouls` (number): Personal fouls.
- `free_throws` (object): Free throws.
- `games` (number): Games played.
- `plus_minus` (number): The points margin while on the court.
- `points` (number): Points.
- `rebounds` (object): Rebounds.
- `steals` (number): Steals.
- `three_pointers` (object): Three-pointers.
- `turnovers` (number): Turnovers.

**Example output**

```json
{
  "assists": 2144,
  "blocks": 451,
  "field_goals": {
    "attempted": 7380,
    "made": 3413,
    "percentage": 46.2
  },
  "fouls": 1303,
  "free_throws": {
    "attempted": 1565,
    "made": 1251,
    "percentage": 79.9
  },
  "games": 82,
  "plus_minus": 747,
  "points": 9534,
  "rebounds": {
    "defensive": 2783,
    "offensive": 932,
    "total": 3715
  },
  "steals": 590,
  "three_pointers": {
    "attempted": 3954,
    "made": 1457,
    "percentage": 36.8
  },
  "turnovers": 975
}
```

### List games

List games and results by day, season, league or team, or the games in play, each with its arena, status, both teams and the score by quarter.

**Inputs**

- Date (`on_date`, date): Optional. Only games on this day, in UTC. The free plan takes only yesterday, today or tomorrow.
- Season (`season`, number): Optional. Only this season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.
- League (`league`, text): Optional. Only this league: the NBA, or one of its summer leagues. One of: `standard` (The NBA), `vegas` (Las Vegas Summer League), `utah` (Salt Lake City Summer League), `sacramento` (California Classic), `orlando` (Orlando Summer League), `africa` (NBA Africa Game).
- Team (`team_id`, text): Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
- In play (`live`, true/false): Optional. Only the games the API has in play right now.

**Outputs**

- `count` (number): How many came back.
- `games` (list): The games, in the order given.

**Example output**

```json
{
  "count": 1,
  "games": [
    {
      "arena": {
        "city": "Chicago",
        "country": null,
        "name": "United Center",
        "state": "IL"
      },
      "date": {
        "duration": null,
        "end": null,
        "start": "2024-10-27T00:00:00.000Z"
      },
      "id": 14145,
      "lead_changes": null,
      "league": "standard",
      "nugget": null,
      "officials": [],
      "periods": {
        "current": 4,
        "end_of_period": false,
        "total": 4
      },
      "scores": {
        "home": {
          "linescore": [
            21,
            18,
            26,
            30
          ],
          "points": 95
        },
        "visitors": {
          "linescore": [
            26,
            33,
            29,
            26
          ],
          "points": 114
        }
      },
      "season": 2024,
      "stage": 2,
      "status": {
        "clock": null,
        "halftime": false,
        "long": "Finished",
        "short": 3
      },
      "teams": {
        "home": {
          "code": "CHI",
          "id": 6,
          "logo": "https://upload.wikimedia.org/wikipedia/en/6/67/Chicago_Bulls_logo.svg",
          "name": "Chicago Bulls",
          "nickname": "Bulls"
        },
        "visitors": {
          "code": "OKC",
          "id": 25,
          "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
          "name": "Oklahoma City Thunder",
          "nickname": "Thunder"
        }
      },
      "times_tied": null
    }
  ]
}
```

### List head-to-head games

List the games two teams have played each other, in every season or only one season or league, with a count of each side's wins and points across the finished ones.

**Inputs**

- First team (`first_team_id`, text, required): One of the two teams, such as 2 for the Boston Celtics. The summary counts its wins first.
- Second team (`second_team_id`, text, required): The other team, such as 25 for the Oklahoma City Thunder.
- Season (`season`, number): Optional. Only this season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.
- League (`league`, text): Optional. Only this league: the NBA, or one of its summer leagues. One of: `standard` (The NBA), `vegas` (Las Vegas Summer League), `utah` (Salt Lake City Summer League), `sacramento` (California Classic), `orlando` (Orlando Summer League), `africa` (NBA Africa Game).

**Outputs**

- `count` (number): How many came back.
- `games` (list): Their games, oldest first.
- `summary` (object): A count of the finished games among them.

**Example output**

```json
{
  "count": 2,
  "games": [
    {
      "arena": {
        "city": "Oklahoma City",
        "country": null,
        "name": "Paycom Center",
        "state": "OK"
      },
      "date": {
        "duration": null,
        "end": null,
        "start": "2025-01-05T20:30:00.000Z"
      },
      "id": 14601,
      "lead_changes": null,
      "league": "standard",
      "nugget": null,
      "officials": [],
      "periods": {
        "current": 4,
        "end_of_period": false,
        "total": 4
      },
      "scores": {
        "home": {
          "linescore": [
            32,
            23,
            21,
            29
          ],
          "points": 105
        },
        "visitors": {
          "linescore": [
            35,
            30,
            15,
            12
          ],
          "points": 92
        }
      },
      "season": 2024,
      "stage": 2,
      "status": {
        "clock": null,
        "halftime": false,
        "long": "Finished",
        "short": 3
      },
      "teams": {
        "home": {
          "code": "OKC",
          "id": 25,
          "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
          "name": "Oklahoma City Thunder",
          "nickname": "Thunder"
        },
        "visitors": {
          "code": "BOS",
          "id": 2,
          "logo": "https://upload.wikimedia.org/wikipedia/en/8/8f/Boston_Celtics.svg",
          "name": "Boston Celtics",
          "nickname": "Celtics"
        }
      },
      "times_tied": null
    },
    {
      "arena": {
        "city": "Boston",
        "country": null,
        "name": "TD Garden",
        "state": "MA"
      },
      "date": {
        "duration": null,
        "end": null,
        "start": "2025-03-12T23:30:00.000Z"
      },
      "id": 15060,
      "lead_changes": null,
      "league": "standard",
      "nugget": null,
      "officials": [],
      "periods": {
        "current": 4,
        "end_of_period": false,
        "total": 4
      },
      "scores": {
        "home": {
          "linescore": [
            30,
            30,
            28,
            24
          ],
          "points": 112
        },
        "visitors": {
          "linescore": [
            33,
            30,
            25,
            30
          ],
          "points": 118
        }
      },
      "season": 2024,
      "stage": 2,
      "status": {
        "clock": null,
        "halftime": false,
        "long": "Finished",
        "short": 3
      },
      "teams": {
        "home": {
          "code": "BOS",
          "id": 2,
          "logo": "https://upload.wikimedia.org/wikipedia/en/8/8f/Boston_Celtics.svg",
          "name": "Boston Celtics",
          "nickname": "Celtics"
        },
        "visitors": {
          "code": "OKC",
          "id": 25,
          "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
          "name": "Oklahoma City Thunder",
          "nickname": "Thunder"
        }
      },
      "times_tied": null
    }
  ],
  "summary": {
    "first_team_points": 204,
    "first_team_wins": 0,
    "played": 2,
    "second_team_points": 223,
    "second_team_wins": 2
  }
}
```

### List leagues

List the leagues API-NBA covers: standard (the NBA itself) and the summer leagues, by the names the League fields take.

**Inputs**: None.

**Outputs**

- `count` (number): How many came back.
- `leagues` (list): The leagues, by name.

**Example output**

```json
{
  "count": 6,
  "leagues": [
    "africa",
    "orlando",
    "sacramento",
    "standard",
    "utah",
    "vegas"
  ]
}
```

### List seasons

List the seasons API-NBA has games for, oldest first, as the years the Season fields take. A season is named by the year it starts in.

**Inputs**: None.

**Outputs**

- `count` (number): How many came back.
- `seasons` (list): The seasons, oldest first.

**Example output**

```json
{
  "count": 5,
  "seasons": [
    2022,
    2023,
    2024,
    2025,
    2026
  ]
}
```