Basketball API Documentation

Simple REST API. Pass your API key as a query parameter — no headers required.

Authentication

Add api_key to every request URL. You can get a key by creating a free account.

https://live-basketball-api.com/api/v2/<endpoint>?api_key=YOUR_KEY

Credits

Each API call consumes credits from your balance. Credits never expire. New accounts get 100 free credits.

Remaining balance is returned in every response under credits_remaining and the X-Credits-Remaining header.

Errors

All errors return JSON with a code and message:

{ "error": "Invalid API key.", "code": 401 }

Code	Meaning
401	Missing or invalid api_key
402	Insufficient credits
400	Invalid parameter (e.g. bad date format)
503	Upstream data source unavailable

GET /matches

Returns basketball matches for a given date, grouped by area and competition. Optionally translate team and competition names.

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
date	No	Today	Match date in YYYY-MM-DD format
lang	No	en	Response language (en, tr, de, ru)

Example requests

Response

{
  "status": "ok",
  "date": "2026-09-14",
  "count": 52,
  "matches": [
    {
      "id": "1eqn6tjzbimqz9hmlx4nce1as",
      "start_time": "2026-09-13 22:00:00",
      "status": "Playing",
      "period": "Third Quarter",
      "clock": { "minute": 0, "second": 365 },
      "team1": { "id": "ebcguhyffr8em9ift0qwt7llg", "name": "Santos U23", "short_name": "SAN", "logo": "https://live-basketball-api.com/image/v2/teams/ebcguhyffr8em9ift0qwt7llg.png" },
      "team2": { // same shape },
      "competition": { "id": "...", "name": "1a Divisão Sub-23", "area": { "id": "...", "name": "Brazil", "flag": "https://live-basketball-api.com/image/v2/flags/....png" } },
      "round": "1st Round",
      "quarters": [ { "quarter": 1, "score": [20, 20] } ],
      "score": { "final": [50, 50] },
      "winner": null,
      "is_awarded": false,
      "has_broadcast": false
    }
  ],
  "credits_remaining": 99
}

GET /match/details

Returns full details for a single match: quarter-by-quarter score, teams, competition, season, round and venue.

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
match_id	Yes	—	Match ID from /matches
lang	No	en	Response language (en, tr, de, ru)

GET /match/form

Returns each team's last 5 results (recent form) leading into this match, with opponent and score for each.

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
match_id	Yes	—	Match ID from /matches
lang	No	en	Response language (en, tr, de, ru)

GET /team/players

Returns a team's full roster with per-player season stats (games played, points, assists, rebounds).

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
team_id	Yes	—	Team ID
season_id	No	active season	Season ID (from the seasons list in this endpoint's response) — roster differs by season
lang	No	en	Response language (en, tr, de, ru)

GET /team/matches

Returns a team's competition standings table and grouped fixture schedule.

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
team_id	Yes	—	Team ID
season_id	No	active season	Season ID (from the seasons list in this endpoint's response) — fixtures/standings differ by season
lang	No	en	Response language (en, tr, de, ru)

GET /competition/details

Returns competition info (seasons, area), the standings table for league-format competitions (null for cups/friendlies that don't have one), plus its full round-by-round schedule and results.

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
competition_id	Yes	—	Competition ID
season_id	No	active season	Season ID (from the seasons list in this endpoint's response) — defaults to the active season
lang	No	en	Response language (en, tr, de, ru)

GET /player/search

Searches for basketball players by name. Results are already filtered to basketball only — the underlying feed covers every sport, so any player from another sport is dropped before it reaches you.

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
q	Yes	—	Search text (player name)
lang	No	en	Response language (en, tr, de, ru)

Response

{
  "status": "ok",
  "query": "lebron james",
  "players": [
    { "id": "1ryu7mdwimohk0gin1u89b6x", "name": "LeBron James", "photo": "https://live-basketball-api.com/image/v2/players/....png", "area": { "id": "...", "name": "USA" } }
  ]
}

GET /team/search

Searches for basketball teams by name. Results are already filtered to basketball only.

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
q	Yes	—	Search text (team name)
lang	No	en	Response language (en, tr, de, ru)

Response

{
  "status": "ok",
  "query": "boston celtics",
  "teams": [
    { "id": "...", "name": "Boston", "logo": "https://live-basketball-api.com/image/v2/teams/....png", "area": { "id": "...", "name": "USA" } }
  ]
}

GET /league/search

Searches for basketball competitions/leagues by name. Use the returned id with GET /competition/details to get standings and fixtures.

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
q	Yes	—	Search text (league/competition name)
lang	No	en	Response language (en, tr, de, ru)

Response

{
  "status": "ok",
  "query": "Türkiye Sigorta BSL",
  "leagues": [
    { "id": "c744bzsdcz9n7pz90phxoxuh9", "name": "Türkiye Sigorta BSL", "area": { "id": "...", "name": "Türkiye" } }
  ]
}

GET /player/details

Returns a player's profile (position, height, weight, nationality, current club) plus their full club and international career history, broken down by team, season and competition (games played, points, assists).

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
player_id	Yes	—	Player ID, from /player/search or a roster in /team/players
lang	No	en	Response language (en, tr, de, ru)

Response

{
  "status": "ok",
  "player": {
    "id": "1ryu7mdwimohk0gin1u89b6x", "name": "L. James", "first_name": "LeBron", "last_name": "James",
    "photo": "https://live-basketball-api.com/image/v2/players/....png",
    "nationality": "USA", "position": "Forward", "height": "206 cm", "weight": "113 kg",
    "birthdate": "1984-12-30", "current_club": "Philadelphia", "shirt_number": "23"
  },
  "club_career": [
    {
      "team": { "id": "2ja1jlnhsy0ksuvvxzff3ky9e", "name": "LA Lakers", "logo": "https://live-basketball-api.com/image/v2/teams/....png" },
      "date_start": "2018-07-09Z", "date_end": "2026-07-25Z",
      "seasons": [
        { "name": "2025/2026", "competitions": [
          { "competition": { "id": "...", "name": "NBA" }, "games_played": 70, "points": 1488, "avg_points": 21.3, "assists": 507 }
        ] }
      ]
    }
  ],
  "international_career": [ // same shape, national team stints ]
}