Basketball API Documentation

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

Base URL: https://live-basketball-api.com/api/v1

Authentication

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

https://live-basketball-api.com/api/v1/matches?api_key=YOUR_KEY

Do not expose your API key in public client-side code or public repos.

Credits

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

Endpoint	Cost
GET /matches	1 credit per call
GET /match/details	1 credit per call
GET /match/scores	1 credit per call
GET /standings	1 credit per call
GET /fixtures	1 credit per call
GET /team/players	1 credit per call
GET /team/matches	1 credit per call
GET /player/search	1 credit per call
GET /player/statistics	1 credit per call
GET /webhook/register	Free
GET /webhook/delete	Free
GET /webhook/list	Free
Webhook notification delivery	1 credit per call

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. Optionally translate team and competition names.

GET /api/v1/matches 1 credit

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

# Today's matches (English)
https://live-basketball-api.com/api/v1/matches?api_key=YOUR_KEY

# Specific date
https://live-basketball-api.com/api/v1/matches?api_key=YOUR_KEY&date=2026-06-29

# Turkish translation
https://live-basketball-api.com/api/v1/matches?api_key=YOUR_KEY&lang=tr

# Russian + specific date
https://live-basketball-api.com/api/v1/matches?api_key=YOUR_KEY&date=2026-06-29&lang=ru
                

curl "https://live-basketball-api.com/api/v1/matches?api_key=YOUR_KEY&date=2026-06-29&lang=en"
                

const res = await fetch(
  'https://live-basketball-api.com/api/v1/matches'
  + '?api_key=YOUR_KEY&date=2026-06-29&lang=en'
);
const data = await res.json();
console.log(data.matches);
                

<?php
$url = 'https://live-basketball-api.com/api/v1/matches'
      . '?api_key=YOUR_KEY&date=2026-06-29&lang=en';

$data = json_decode(file_get_contents($url), true);
var_dump($data['matches']);
                

import requests

data = requests.get(
    'https://live-basketball-api.com/api/v1/matches',
    params={
        'api_key': 'YOUR_KEY',
        'date': '2026-06-29',
        'lang': 'en',
    }
).json()
print(data['matches'])
                

Response

{
  "status":      "success",
  "date":        "2026-07-02",
  "lang":        "en",
  "match_count": 54,
  "matches": [
    {
      "id":      15395207,
      "date":    "2026-07-02",
      "kickoff": "23:00",
      "competition": {
        "id":      21995,
        "name":    "CEBL",
        "country": "Canada"
      },
      "home": {
        "id":   506781,
        "name": "Scarborough Shooting Stars",
        "logo": "https://live-basketball-api.com/image/teams/506781.png"
      },
      "away": {
        "id":   507014,
        "name": "Montreal Alliance",
        "logo": "https://live-basketball-api.com/image/teams/507014.png"
      },
      "status": "Not Started",
      "score": {
        "home": null, "away": null,
        "q1": null, "q2": null, "q3": null, "q4": null, "ot": null
      },
      "winner": null
    }
  ],
  "credits_used": 1
}

Field reference

Field	Type	Description
id	integer	Unique match identifier
date	string	Match date `YYYY-MM-DD`
kickoff	string	Start time in `HH:MM` UTC
competition.id	integer	Sofascore uniqueTournament ID (use for standings/fixtures)
competition.name	string	`{id, name, country}`
competition.country	string	Country/region of the competition
home / away	object	Team id (integer), name, logo URL
status	string	Short display label: `FT` · `HT` · `Q1`–`Q4` · `OT` (translated per lang)
score.home / .away	integer\|null	Current score
score.q1–q4	array\|null	[home, away] per quarter; null if not played
score.ot	array\|null	[home, away] overtime score; null if no overtime
winner	string\|null	`"home"` · `"away"` · `null` — "home", "away", or null

GET /match/details

Returns live match details — venue, current score, period and quarter-by-quarter breakdown.

GET /api/v1/match/details 1 credit

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
match_id	Yes	—	Numeric match ID (from /matches or /fixtures)
lang	No	`en`	Response language: `en` `tr` `de` `ru`

Example request

https://live-basketball-api.com/api/v1/match/details?api_key=YOUR_KEY&match_id=15395205&lang=en

Response

{
  "status":       "success",
  "match_id":     15395205,
  "lang":         "en",
  "date":         "2026-07-01",
  "kickoff":      "23:00",
  "competition": {
    "id":      21995,
    "name":    "CEBL",
    "country": "Canada"
  },
  "home": {
    "id":   506781,
    "name": "Scarborough Shooting Stars",
    "logo": "https://live-basketball-api.com/image/teams/506781.png"
  },
  "away": {
    "id":   507014,
    "name": "Montreal Alliance",
    "logo": "https://live-basketball-api.com/image/teams/507014.png"
  },
  "match_status": "Finished",
  "period":       null,
  "clock":        null,
  "score": {
    "home": 97, "away": 83,
    "q1": [26, 16], "q2": [22, 22],
    "q3": [26, 22], "q4": [23, 23], "ot": null
  },
  "winner":      "home",
  "venue":        null,
  "statistics": {
    "all": [
      { "key": "fieldGoalsScored", "label": "Field Goals", "home": "35/72", "away": "31/69", "homeValue": 48.6, "awayValue": 44.9 },
      /* ... more stat keys ... */
    ],
    "period1": [/* quarter 1 stats */],
    "period2": [/* quarter 2 stats */]
  },
  "credits_used": 1
}

Field reference

Field	Type	Description
match_id	integer	Numeric Sofascore event ID
date / kickoff	string	Match date (Y-m-d) and start time (H:i) in UTC
competition.id	integer	Sofascore uniqueTournament ID
home / away	object	id (integer), name, logo URL
match_status	string	Translated status label (e.g. "Finished", "Live", "Not Started")
period	string\|null	Current period label when live (e.g. "3rd Quarter", "Overtime"); null otherwise
clock	object\|null	Live clock — played_seconds (integer) and running (bool); null when not live
score.home / .away	integer\|null	Total score; null if match not started
score.q1–q4	array\|null	[home, away] per quarter; null if not played
score.ot	array\|null	[home, away] overtime score; null if no overtime
winner	string\|null	"home", "away", or null if not finished
venue	string\|null	Venue city/country when available
statistics	object\|null	Per-period stat arrays; keys: "all", "period1"–"period4", "overtime". Each item has key, label, home, away, homeValue, awayValue

Get the match_id from the id field in /matches response.

GET /match/scores

Returns per-player statistics and team totals for a match. Only available for live or finished games.

GET /api/v1/match/scores 1 credit

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
match_id	Yes	—	Numeric match ID (from /matches or /fixtures)
lang	No	`en`	Response language: `en` `tr` `de` `ru`

Example request

https://live-basketball-api.com/api/v1/match/scores?api_key=YOUR_KEY&match_id=15395205&lang=en

Response

{
  "status":    "success",
  "match_id":  15395205,
  "available": true,
  "lang":      "en",
  "competition": { "id": 21995, "name": "CEBL", "country": "Canada" },
  "home": {
    "players": [
      {
        "name":       "DeShawn Stevenson",
        "photo":      "https://live-basketball-api.com/image/players/1969378.png",
        "jersey":     "1",
        "position":   "Guard",
        "starter":    true,
        "minutes":    "26:07",
        "points":     14,
        "fg2":        { "made": 4, "attempted": 7 },
        "fg3":        { "made": 2, "attempted": 4 },
        "ft":         { "made": 0, "attempted": 0 },
        "fg_pct":     54,
        "rebounds":   { "total": 4, "offensive": 1, "defensive": 3 },
        "assists":    3,
        "steals":     1,
        "blocks":     0,
        "turnovers":  2,
        "fouls":      3,
        "plus_minus": 8
      }
    ]
  },
  "away": { /* same structure */ },
  "credits_used": 1
}

Field reference

Field	Type	Description
available	bool	`false` for upcoming matches (no data yet) (false for upcoming matches)
competition.id	integer	Sofascore uniqueTournament ID
players[].name	string	Full name
players[].photo	string	Player photo URL (/image/players/{id}.png)
players[].jersey	string\|null	Jersey number
players[].position	string\|null	Translated position name (Guard, Forward, Center, G-F, F-C)
players[].starter	bool	`true` if in starting lineup
players[].minutes	string\|null	Time played e.g. `"12:34"` (MM:SS format)
players[].points	integer\|null	Points scored
players[].fg2 / fg3 / ft	object\|null	made and attempted counts; null if no data
players[].fg_pct	integer\|null	Field goal percentage (0–100)
players[].rebounds	object\|null	total, offensive, defensive; null if no data
players[].assists / steals / blocks / turnovers / fouls	integer\|null	Per-player stat; null if unavailable
players[].plus_minus	integer\|null	Plus/minus stat (can be negative)

GET /standings

Returns standings (league table) for a competition. Supports multi-group competitions (e.g. cup stages).

GET /api/v1/standings 1 credit

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
league_id	Yes	—	Sofascore uniqueTournament ID (numeric — from competition.id in match responses)
season_id	No	latest	Sofascore season ID (numeric — from seasons[] in response); defaults to current season
lang	No	`en`	Response language: `en` `tr` `de` `ru`

Example request

https://live-basketball-api.com/api/v1/standings?api_key=YOUR_KEY&league_id=21995&lang=en

# With specific season
https://live-basketball-api.com/api/v1/standings?api_key=YOUR_KEY&league_id=21995&season_id=88780&lang=tr

Response

{
  "status":    "success",
  "league_id": 21995,
  "season":    { "id": 88780, "name": "CEBL 2026", "year": "2026" },
  "seasons":   [
    { "id": 88780, "name": "CEBL 2026", "year": "2026" },
    { "id": 71219, "name": "CEBL 2025", "year": "2025" }
  ],
  "lang": "en",
  "groups": [
    {
      "name": "Eastern Conference",
      "teams": [
        {
          "position":       1,
          "team":           "Scarborough Shooting Stars",
          "logo":           "https://live-basketball-api.com/image/teams/506781.png",
          "played":         14,
          "won":            12,
          "lost":           2,
          "points_for":     1329,
          "points_against": 1225,
          "point_diff":     "+104",
          "win_pct":        85.7,
          "games_behind":   0,
          "streak":         "W2",
          "points":         12,
          "promotion":      "Playoffs"
        }
      ]
    }
  ],
  "credits_used": 1
}

Field reference

Field	Type	Description
league_id	integer	Sofascore uniqueTournament ID
season	object	Active season: id, name, year
seasons	array	All available seasons for this league — use season_id from here
groups[].name	string\|null	Conference/group name (translated per lang)
groups[].teams[].position	integer	Standing position
groups[].teams[].logo	string	Team logo URL (/image/teams/{id}.png)
groups[].teams[].played/won/lost	integer	Games played, won, and lost
groups[].teams[].points_for / points_against	integer	Total points scored / conceded
groups[].teams[].point_diff	string\|null	Point differential (e.g. "+104", "-32")
groups[].teams[].win_pct	float\|null	Win percentage (0–100)
groups[].teams[].games_behind	float\|null	Games behind the leader
groups[].teams[].streak	string\|null	Current streak — "W3" (3 wins), "L2" (2 losses), or null
groups[].teams[].promotion	string\|null	Promotion/relegation label if applicable (translated)

GET /fixtures

Returns the full fixture schedule for a competition — all rounds in a single response. Scores are included for completed matches.

GET /api/v1/fixtures 1 credit

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
league_id	Yes	—	Sofascore uniqueTournament ID (numeric — from competition.id in match responses)
season_id	No	latest	Sofascore season ID (numeric — from seasons[] in response); defaults to current season
direction	No	`next`	`next` for upcoming matches, `last` for past matches
page	No	`0`	Page number (0-based). Each page returns up to 30 matches. Use has_next_page to paginate.
lang	No	`en`	Response language: `en` `tr` `de` `ru`

Example request

# Upcoming matches for CEBL
https://live-basketball-api.com/api/v1/fixtures?api_key=YOUR_KEY&league_id=21995&lang=en

# Past matches, page 1
https://live-basketball-api.com/api/v1/fixtures?api_key=YOUR_KEY&league_id=21995&direction=last&page=1&lang=tr

Response

{
  "status":        "success",
  "league_id":     21995,
  "season":        { "id": 88780, "name": "CEBL 2026", "year": "2026" },
  "lang":          "en",
  "direction":     "next",
  "page":          0,
  "has_next_page": true,
  "match_count":   30,
  "seasons": [
    { "id": 88780, "name": "CEBL 2026", "year": "2026" }
  ],
  "matches": [
    {
      "id":      15395207,
      "round":   1,
      "date":    "2026-07-02",
      "kickoff": "23:00",
      "competition": { "id": 21995, "name": "CEBL", "country": "Canada" },
      "home": { "id": 506781, "name": "Scarborough Shooting Stars", "logo": "https://live-basketball-api.com/image/teams/506781.png" },
      "away": { "id": 507014, "name": "Montreal Alliance", "logo": "https://live-basketball-api.com/image/teams/507014.png" },
      "status":  "Not Started",
      "score":   { "home": null, "away": null, "q1": null, "q2": null, "q3": null, "q4": null, "ot": null },
      "winner":  null
    }
  ],
  "credits_used": 1
}

Field reference

Field	Type	Description
direction	string	"next" (upcoming) or "last" (past) — reflects the direction param you sent
page / has_next_page	integer / bool	Current page and whether more pages exist
seasons	array	All seasons for this league — use season_id from here to switch seasons
matches[].id	integer	Numeric match ID — use in /match/details and /match/scores
matches[].round	integer\|null	Round number within the season; null if league doesn't use rounds
matches[].competition.id	integer	Sofascore uniqueTournament ID
matches[].home / away	object	id (integer), name, logo URL
matches[].status	string	Translated status label (e.g. "Finished", "Not Started")
matches[].score	object	home/away totals and q1–q4, ot arrays; null values before match starts
matches[].winner	string\|null	"home", "away", or null

Where to find team_id
Use the home_team.id or away_team.id values returned by /matches or /fixtures.

GET /team/players

Returns the full squad roster for a team including physical stats, contract details, injury status, and player photos. The endpoint automatically resolves the team name and fetches the roster. Covers all 30 NBA teams.

GET /api/v1/team/players 1 credit

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
team_id	Yes	—	Team ID — obtained from `home_team.id` / `away_team.id` in `/matches` or `/team/matches`
lang	No	en	Response language: `en` `tr` `de` `ru`

Example request

https://live-basketball-api.com/api/v1/team/players?api_key=YOUR_KEY&team_id=4kjso6vrhugyaktbc7751ijm1

Response

{
  "status":        "success",
  "team_id":       "4kjso6vrhugyaktbc7751ijm1",
  "team_name":     "New York Knicks",
  "league":        "NBA",
  "lang":          "en",
  "season":        null,
  "player_count":  18,
  "players": [
    {
      "id":                  990222,
      "name":                "Karl-Anthony Towns",
      "short_name":          "K. Towns",
      "first_name":          "Karl-Anthony",
      "last_name":           "Towns",
      "slug":                "karl-anthony-towns",
      "jersey_number":       "32",
      "position":            "C",
      "position_name":       "Center",
      "height_cm":           213,
      "height_display":      "213 cm",
      "weight_kg":           113,
      "weight_display":      "113 kg",
      "date_of_birth":       "1995-11-15",
      "age":                 30,
      "birth_country":       "United States",
      "nationality":         "United States",
      "nationality_code":    "US",
      "salary":              50400000,
      "salary_currency":     "USD",
      "contract_until":      "2030-06-30",
      "status":              "Active",
      "injured":             false,
      "injury_reason":       null,
      "injury_status":       null,
      "depth":               1,
      "depth_position":      "C",
      "previous_clubs":      [
        { "team": "Minnesota Timberwolves", "date": "2024-09-27" }
      ],
      "name_translations":   { "ar": "كارل أنتوني تاونز", "ru": "Карл-Энтони Таунс" },
      "photo":               "https://live-basketball-api.com/players/v2/990222.png"
    }
  ],
  "credits_used": 1
}

Field reference

Field	Type	Description
team_name	string	Resolved team name
league	string	League name (e.g. NBA)
season	integer\|null	Current roster season year
player_count	integer	Number of players returned
players[].id	integer	Player ID
players[].name	string	Full player name
players[].short_name	string	Abbreviated display name
players[].first_name / last_name	string	First and last name separately
players[].jersey_number	string\|null	Jersey number
players[].position	string\|null	Position abbreviation (G, F, C)
players[].position_name	string\|null	Full position name (Guard, Forward, Center)
players[].height_cm	integer\|null	Height in centimetres
players[].height_display	string\|null	Height in feet/inches e.g. `6'6"`
players[].weight_kg	integer\|null	Weight in kilograms
players[].weight_display	string\|null	Weight in lbs e.g. `195 lbs`
players[].date_of_birth	string\|null	Date of birth (ISO 8601)
players[].age	integer\|null	Current age in years
players[].birth_country	string\|null	Country of birth
players[].nationality	string\|null	Country of birth
players[].nationality_code	string\|null	ISO 3166-1 alpha-2 country code
players[].salary	integer\|null	Annual salary in USD (null if not disclosed)
players[].salary_currency	string\|null	Salary currency — always USD for NBA
players[].contract_until	string\|null	Contract expiry date (YYYY-MM-DD)
players[].status	string\|null	Roster status: Active, Two-Way Contract, Injured, Suspended
players[].injured	bool	Whether the player is currently injured
players[].injury_reason	string\|null	Injury description (e.g. "Fractured hand", "Left knee ligament tear")
players[].injury_status	string\|null	Injury designation (day-to-day, out, etc.)
players[].depth	integer\|null	Depth chart position: 1 = starter, 2 = second string, etc.
players[].depth_position	string\|null	Position assigned at this depth slot (e.g. PG, C)
players[].previous_clubs	array	Most recent previous club per player
players[].previous_clubs[].team	string	Previous team name
players[].previous_clubs[].date	string\|null	Transfer / arrival date (YYYY-MM-DD)
players[].name_translations	object\|null	Name translations keyed by language code (ar, hi, bn, ru, etc.)
players[].photo	string	Proxied player headshot URL

GET /team/matches

Returns past or upcoming matches for a team with scores, periods, and season info. Paginated — 30 matches per page.

GET /api/v1/team/matches 1 credit

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
team_id	Yes	—	Team ID — obtained from `home_team.id` / `away_team.id` in `/matches` or `/team/matches`
type	No	`last`	`last` — past matches \| `next` — upcoming \| `all` — both (page 0 only)
page	No	`0`	Page number (0-based). Each page returns up to 30 matches.
lang	No	`en`	Response language: `en` `tr` `de` `ru`

Example request

https://live-basketball-api.com/api/v1/team/matches?api_key=YOUR_KEY&team_id=4kjso6vrhugyaktbc7751ijm1&type=last&page=0

Response

{
  "status":         "success",
  "team_id":        "4kjso6vrhugyaktbc7751ijm1",
  "team_name":      "New York Knicks",
  "league":         "NBA",
  "lang":           "en",
  "type":           "last",
  "page":           0,
  "has_next_page": true,
  "match_count":   30,
  "matches": [
    {
      "id":             14439297,
      "slug":           "new-york-knicks-washington-wizards",
      "tournament":    "NBA",
      "unique_tournament": "NBA",
      "season":         "2025/2026",
      "season_name":    "NBA 25/26",
      "round":          41,
      "date":           "2026-02-23",
      "time":           "20:30",
      "timestamp":      1774222200,
      "status":         "FT",
      "status_type":    "finished",
      "home_team": {
        "id":   3421,
        "name": "New York Knicks",
        "slug": "new-york-knicks",
        "logo": "https://live-basketball-api.com/teams/3421.png"
      },
      "away_team": {
        "id":   3427,
        "name": "Washington Wizards",
        "slug": "washington-wizards",
        "logo": "https://live-basketball-api.com/teams/3427.png"
      },
      "score":          { "home": 145, "away": 113 },
      "periods": {
        "Q1": { "home": 32, "away": 27 },
        "Q2": { "home": 36, "away": 25 },
        "Q3": { "home": 37, "away": 29 },
        "Q4": { "home": 40, "away": 32 }
      },
      "winner":         "home",
      "side":           "home",
      "result":         "W",
      "team_score":     145,
      "opp_score":      113
    }
  ],
  "credits_used": 1
}

Field reference

Field	Type	Description
type	string	Requested match type
page	integer\|null	Current page number (`null` for `type=all`)
has_next_page	bool\|null	`true` if more pages are available (`null` for `type=all`)
match_count	integer	Number of matches in this response
matches[].id	integer	Match ID — use with `/match/details` and `/match/scores`
matches[].tournament	string\|null	Tournament / competition name
matches[].season	string\|null	Season identifier e.g. `2025/2026`
matches[].season_name	string\|null	Season display name e.g. `NBA 25/26`
matches[].round	integer\|null	Round number within the season
matches[].date	string	Match date `YYYY-MM-DD`
matches[].time	string	Kick-off time `HH:MM` UTC
matches[].timestamp	integer	Unix timestamp of match start
matches[].status	string	Short status label: `FT` · `Live` · `Upcoming` · `Postponed`
matches[].status_type	string	Raw status: `finished` · `inprogress` · `notstarted` · `postponed` · `canceled`
matches[].home_team / away_team	object	`{id, name, slug, logo}`
matches[].score	object	Final score `{home, away}` — `null` for upcoming matches
matches[].periods	object	Per-quarter scores `{Q1…Q4, OT}` each `{home, away}`
matches[].winner	string\|null	`"home"` · `"away"` · `null`
matches[].side	string	`"home"` or `"away"` — which side the requested team played on
matches[].result	string\|null	Result from the team's perspective: `W` Win · `L` Loss · `D` Draw · `null` for upcoming
matches[].team_score / opp_score	integer\|null	Score of the requested team and their opponent respectively

GET /player/search

Search basketball players by name. Sofascore's underlying search mixes every sport together — this endpoint filters the raw results down to basketball players only, de-duplicates them, and paginates the clean list for you (20 players per page).

GET /api/v1/player/search 1 credit

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
q	Yes	—	Search text — player name (min 2, max 100 characters)
page	No	`0`	0-based page number over the filtered, basketball-only results (20 per page)
lang	No	`en`	Response language: `en` `tr` `de` `ru`

Example requests

# Search for a player
https://live-basketball-api.com/api/v1/player/search?api_key=YOUR_KEY&q=michael%20jordan

# Second page of a common-surname search
https://live-basketball-api.com/api/v1/player/search?api_key=YOUR_KEY&q=smith&page=1

# Turkish position labels
https://live-basketball-api.com/api/v1/player/search?api_key=YOUR_KEY&q=luka&lang=tr
                

curl "https://live-basketball-api.com/api/v1/player/search?api_key=YOUR_KEY&q=michael%20jordan&lang=en"
                

const res = await fetch(
  'https://live-basketball-api.com/api/v1/player/search'
  + '?api_key=YOUR_KEY&q=michael+jordan'
);
const data = await res.json();
console.log(data.players);
                

<?php
$url = 'https://live-basketball-api.com/api/v1/player/search'
      . '?api_key=YOUR_KEY&q=michael+jordan';

$data = json_decode(file_get_contents($url), true);
var_dump($data['players']);
                

import requests

data = requests.get(
    'https://live-basketball-api.com/api/v1/player/search',
    params={'api_key': 'YOUR_KEY', 'q': 'michael jordan'}
).json()
print(data['players'])
                

Response

{
  "status":        "success",
  "query":         "michael jordan",
  "lang":          "en",
  "page":          0,
  "page_size":     20,
  "has_next_page": false,
  "result_count":  2,
  "players": [
    {
      "id":               2356422,
      "name":             "Michael Jordan",
      "short_name":       "M. Jordan",
      "slug":             "michael-jordan",
      "jersey_number":    null,
      "position":         "G",
      "position_name":    "Guard",
      "nationality":      "USA",
      "nationality_code": "US",
      "retired":          true,
      "deceased":         false,
      "team": {
        "id":       273129,
        "name":     "No team",
        "slug":     "no-team",
        "national": false,
        "logo":     "https://live-basketball-api.com/image/teams/273129.png"
      },
      "photo": "https://live-basketball-api.com/image/players/2356422.png"
    }
  ],
  "credits_used": 1
}

Field reference

Field	Type	Description
query	string	The search text you sent
page / page_size	integer	Current 0-based page and page size (fixed at 20)
has_next_page	bool	Whether another page of basketball results is available
result_count	integer	Number of players in this page
players[].id	integer	Sofascore player ID — use with other endpoints where applicable
players[].name / short_name / slug	string	Full name, abbreviated name, and URL slug
players[].jersey_number	string\|null	Current jersey number, if known
players[].position / position_name	string\|null	Position abbreviation and localized full name
players[].nationality / nationality_code	string\|null	Country name and ISO alpha-2 code
players[].retired / deceased	bool	Career/life status flags
players[].team	object\|null	Current team id, name, slug, national-team flag, and logo URL
players[].photo	string	Player photo URL

Sofascore's search is fuzzy and covers every sport, so hit rates for basketball vary by query. This endpoint scans up to 20 raw result pages behind the scenes to fill each 20-player page — for very obscure names it may return fewer than 20 results, or none at all (still a normal 200 response with an empty players array).

GET /player/statistics

Player career statistics, broken down by competition and season. You won't usually know a player's league_id/season_id up front, so send only player_id and the endpoint automatically returns their most recent season in their primary competition — plus a full competitions catalogue listing every league_id/season_id this player has stats for, so you can call it again for any other one.

GET /api/v1/player/statistics 1 credit

Parameters

Parameter	Required	Default	Description
api_key	Yes	—	Your API key
player_id	Yes	—	Sofascore player ID (numeric) — find it via `/player/search`
league_id	No	auto	Sofascore uniqueTournament ID, taken from a previous call's `competitions[].league_id`. Omit it and the player's primary competition is picked for you.
season_id	No	auto — latest	Sofascore season ID. Works with or without `league_id` — if you only have a `season_id` (e.g. from `competitions[].seasons[].season_id`), the endpoint finds which competition it belongs to for you.
lang	No	`en`	Response language: `en` `tr` `de` `ru`

Example requests

# Just the player_id — auto-picks their primary league + latest season,
# and returns the full competitions catalogue for follow-up calls
https://live-basketball-api.com/api/v1/player/statistics?api_key=YOUR_KEY&player_id=861608

# A specific competition (league_id from the "competitions" list above)
https://live-basketball-api.com/api/v1/player/statistics?api_key=YOUR_KEY&player_id=861608&league_id=132

# A specific competition + season
https://live-basketball-api.com/api/v1/player/statistics?api_key=YOUR_KEY&player_id=861608&league_id=132&season_id=65360

# Only a season_id, no league_id — endpoint resolves the competition itself
https://live-basketball-api.com/api/v1/player/statistics?api_key=YOUR_KEY&player_id=861608&season_id=65360
                

curl "https://live-basketball-api.com/api/v1/player/statistics?api_key=YOUR_KEY&player_id=861608"
                

const res = await fetch(
  'https://live-basketball-api.com/api/v1/player/statistics'
  + '?api_key=YOUR_KEY&player_id=861608'
);
const data = await res.json();
console.log(data.regular_season);
console.log(data.competitions); // other league_id / season_id options
                

<?php
$url = 'https://live-basketball-api.com/api/v1/player/statistics'
      . '?api_key=YOUR_KEY&player_id=861608';

$data = json_decode(file_get_contents($url), true);
var_dump($data['regular_season']);
                

import requests

data = requests.get(
    'https://live-basketball-api.com/api/v1/player/statistics',
    params={'api_key': 'YOUR_KEY', 'player_id': 861608}
).json()
print(data['regular_season'])
                

Response

Only player_id was sent, so mode is "auto" — the endpoint picked NBA (the player's primary competition) and their latest season:

{
  "status": "success",
  "mode":   "auto",
  "player": {
    "id": 861608, "name": "Luka Dončić", "position": "FG", "position_name": "Forward-Guard",
    "current_team": { "id": 3427, "name": "Los Angeles Lakers", "logo": "..." },
    "photo": "https://live-basketball-api.com/image/players/861608.png"
  },
  "league": { "id": 132, "name": "NBA", "country": "USA" },
  "season": { "id": 80229, "name": "NBA 25/26", "year": "2025/2026" },
  "lang": "en",
  "available_types": ["regular_season"],
  "regular_season": {
    "games_played": 64,
    "minutes_per_game": 35.8,
    "points": 2143, "points_per_game": 33.5,
    "rebounds": { "total": 495, "offensive": 41, "defensive": 454, "per_game": 7.7 },
    "assists": 530, "assists_per_game": 8.3,
    "steals": 105, "blocks": 34, "turnovers": 255, "fouls": 153,
    "field_goals": { "made": 693, "attempted": 1457, "pct": 47.6 },
    "two_pointers": { "made": 439, "attempted": 763, "pct": 57.5 },
    "three_pointers": { "made": 254, "attempted": 694, "pct": 36.6 },
    "free_throws": { "made": 503, "attempted": 645, "pct": 78.0 },
    "double_doubles": 34, "triple_doubles": 8,
    "rating": 8.3, "plus_minus": 187,
    "team": { "id": 3427, "name": "Los Angeles Lakers", "logo": "..." },
    "ranking": {
      "points": { "rank_total": 1, "rank_per_game": 1, "out_of": 582 }
    }
  },
  "playoffs": null,
  "overall": null,
  "competitions": [
    {
      "league_id": 132, "league_name": "NBA", "country": "USA",
      "seasons": [
        { "season_id": 80229, "name": "NBA 25/26", "year": "2025/2026", "types": ["regular_season"] },
        { "season_id": 65360, "name": "NBA 24/25", "year": "2024/2025", "types": ["regular_season", "playoffs"] }
      ]
    },
    {
      "league_id": 138, "league_name": "Euroleague", "country": "International",
      "seasons": [
        { "season_id": 13537, "name": "Euroleague 17/18", "year": "17/18", "types": ["regular_season", "playoffs"] }
      ]
    }
  ],
  "credits_used": 1
}

Field reference

Field	Type	Description
mode	string	`auto` (neither given — we picked league+season), `league` (you sent `league_id`), or `season_lookup` (you sent `season_id` only)
league / season	object	Which competition/season this response's stats are for
available_types	array	Which of `regular_season` / `playoffs` / `overall` are populated below
regular_season / playoffs / overall	object\|null	Full stat block for that split, or `null` if not applicable to this competition/season
games_played	integer	Appearances in this split
points / rebounds / assists / steals / blocks / turnovers / fouls	integer	Season totals
points_per_game / assists_per_game / minutes_per_game / rebounds.per_game	float\|null	Per-game averages (null if 0 games played)
field_goals / two_pointers / three_pointers / free_throws	object	`made`, `attempted`, `pct`
double_doubles / triple_doubles	integer\|null	Games with double/triple-digit stats in two/three categories
rating	float\|null	Sofascore's average game rating for this split
team	object\|null	Team played for during this split
ranking	object\|null	League-wide rank (total & per-game) for points/rebounds/assists/steals/blocks/turnovers/plus-minus/minutes/shooting %, out of all players with recorded stats that season
competitions	array	Every league/season this player has recorded stats for — always included, use it to pick a different `league_id`/`season_id` for your next call
competitions[].seasons[].types	array	Which stat blocks exist for that season: `regular_season`, `playoffs`, `overall`

You don't need to know a player's league_id or season_id in advance — send just player_id, read the stats for their current competition directly off the response, and use the competitions array whenever you want a different league or a past season (e.g. their Euroleague years, or an NBA season before a trade).

Webhooks

Register HTTP endpoints to receive real-time push notifications when basketball events occur. Registering, deleting, and listing webhooks is free. Each notification delivered to your URL costs 1 credit.

How it works: When a monitored match event fires, our system sends a POST request to your registered URL with a JSON payload. If you provided a secret, the request includes an X-Webhook-Signature: sha256=HMAC header for verification.

Available Event Types

Event	Triggers when…	Cost
Match lifecycle
`match.start`	Match kicks off (status → in-progress)	1 credit
`match.finish`	Final whistle — full-time result available	1 credit
`match.postponed`	Match officially postponed	1 credit
`match.cancelled`	Match cancelled	1 credit
Periods
`period.start`	New quarter/period starts (Q1, Q2, Q3, Q4, OT)	1 credit
`period.end`	Quarter/period ends (includes half-time)	1 credit
Scoring
`score.update`	Score changed (any basket)	1 credit
`basket.2pt`	2-point field goal made	1 credit
`basket.3pt`	3-point field goal made	1 credit
`basket.freethrow`	Free throw made	1 credit
In-game events
`foul`	Foul committed (personal, technical, or flagrant)	1 credit
`timeout`	Timeout called	1 credit
`substitution`	Player substitution (in/out)	1 credit

GET /webhook/register

GET /api/v1/webhook/register Free

Parameters

Parameter	docs_th_req	Description
api_key	✓	Your API key
url	✓	HTTP/HTTPS endpoint that will receive POST notifications (max 500 chars)
events		Comma-separated event slugs, or `all` (default: `all`). Example: `match.start,score.update`
secret		Optional secret (max 64 chars). Used to sign payloads via `X-Webhook-Signature: sha256=HMAC`

Example request

https://live-basketball-api.com/api/v1/webhook/register?api_key=YOUR_KEY&url=https://yoursite.com/hook&events=match.start,score.update,match.finish&secret=mysecret

Response

{
  "status":   "success",
  "message":  "Webhook registered successfully.",
  "webhook": {
    "id":         7,
    "url":        "https://yoursite.com/hook",
    "events":     ["match.finish", "match.start", "score.update"],
    "has_secret": true,
    "created_at": "2026-07-02 14:30:00"
  },
  "note":        "Each notification delivered to this URL costs 1 credit.",
  "credits_used": 0
}

Maximum 10 webhooks per account. Registering the same URL twice returns a 409 error.

Verifying the Signature (Secret)

When you register a webhook with a secret, every delivery includes an X-Webhook-Signature: sha256=HMAC header. Verify it on your server to confirm the request came from us and was not tampered with.

<?php
$secret  = 'your_webhook_secret';
$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $header)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($payload, true);
// handle $data['event'], $data['match'], $data['data']

const crypto  = require('crypto');
const express = require('express');
const app     = express();

app.use(express.raw({ type: 'application/json' }));

app.post('/hook', (req, res) => {
  const secret   = 'your_webhook_secret';
  const sig      = req.headers['x-webhook-signature'] ?? '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');

  if (sig !== expected) return res.status(401).send('Invalid signature');

  const data = JSON.parse(req.body);
  // handle data.event, data.match, data.data
  res.sendStatus(200);
});

import hmac, hashlib, json
from flask import Flask, request, abort

app    = Flask(__name__)
SECRET = b'your_webhook_secret'

@app.route('/hook', methods=['POST'])
def webhook():
    sig      = request.headers.get('X-Webhook-Signature', '')
    expected = 'sha256=' + hmac.new(
        SECRET, request.data, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, sig):
        abort(401)

    data = request.get_json()
    # handle data['event'], data['match'], data['data']
    return '', 200

// Example payload for a basket.3pt event
{
  "event":     "basket.3pt",
  "timestamp": 1751234567,
  "match": {
    "id":             15395205,
    "competition_id": 132,
    "competition":    "NBA",
    "home":           { "id": 3428, "name": "Boston Celtics" },
    "away":           { "id": 3412, "name": "Golden State Warriors" },
    "status":         "inprogress",
    "period":         3,
    "score":          { "home": 87, "away": 79 }
  },
  "data": {
    "incident_id": 987654321,
    "team":        "home",
    "player":      "Jayson Tatum",
    "game_time":   "7'",
    "score":       { "home": 87, "away": 79 }
  }
}

Payload Examples

Every webhook POST uses the same JSON envelope. The match block reflects the match state at the moment the event fired. Only the data field differs per event type.

{
  "event":     "match.start",
  "timestamp": 1751234500,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "inprogress", "period": 1,
    "score": { "home": 0, "away": 0 },
    "start_timestamp": 1751234500
  },
  "data": {}
}

{
  "event":     "match.finish",
  "timestamp": 1751241000,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "finished", "period": 4,
    "score": { "home": 112, "away": 98 },
    "start_timestamp": 1751234500
  },
  "data": {
    "score":  { "home": 112, "away": 98 },
    "winner": "home"  // "home" | "away" | "draw"
  }
}

{
  "event":     "match.postponed",
  "timestamp": 1751234400,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "postponed", "period": 0,
    "score": { "home": 0, "away": 0 },
    "start_timestamp": 1751234500
  },
  "data": {}
}

{
  "event":     "match.cancelled",
  "timestamp": 1751234400,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "cancelled", "period": 0,
    "score": { "home": 0, "away": 0 },
    "start_timestamp": 1751234500
  },
  "data": {}
}

{
  "event":     "period.start",
  "timestamp": 1751236100,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "inprogress", "period": 2,
    "score": { "home": 28, "away": 24 },
    "start_timestamp": 1751234500
  },
  "data": {
    "period":       2,
    "period_label": "Q2"  // Q1–Q4 or OT
  }
}

{
  "event":     "period.end",
  "timestamp": 1751236000,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "halftime", "period": 1,
    "score": { "home": 28, "away": 24 },
    "start_timestamp": 1751234500
  },
  "data": {
    "period":       1,
    "period_label": "Q1"
  }
}

{
  "event":     "score.update",
  "timestamp": 1751235820,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "inprogress", "period": 2,
    "score": { "home": 54, "away": 49 },
    "start_timestamp": 1751234500
  },
  "data": {
    "score": { "home": 54, "away": 49 }
  }
}

{
  "event":     "basket.2pt",
  "timestamp": 1751235810,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "inprogress", "period": 2,
    "score": { "home": 54, "away": 49 },
    "start_timestamp": 1751234500
  },
  "data": {
    "incident_id": 987654321,
    "team":        "home",        // "home" | "away"
    "player":      "Jaylen Brown", // null if not available
    "player_out":  null,
    "game_time":   "4'",
    "score": { "home": 54, "away": 49 }
  }
}

{
  "event":     "basket.3pt",
  "timestamp": 1751235900,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "inprogress", "period": 3,
    "score": { "home": 87, "away": 79 },
    "start_timestamp": 1751234500
  },
  "data": {
    "incident_id": 987654399,
    "team":        "home",
    "player":      "Jayson Tatum",
    "player_out":  null,
    "game_time":   "7'",
    "score": { "home": 87, "away": 79 }
  }
}

{
  "event":     "basket.freethrow",
  "timestamp": 1751235950,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "inprogress", "period": 3,
    "score": { "home": 87, "away": 80 },
    "start_timestamp": 1751234500
  },
  "data": {
    "incident_id": 987654450,
    "team":        "away",
    "player":      "Stephen Curry",
    "player_out":  null,
    "game_time":   "9'",
    "score": { "home": 87, "away": 80 }
  }
}

{
  "event":     "foul",
  "timestamp": 1751235870,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "inprogress", "period": 3,
    "score": { "home": 87, "away": 79 },
    "start_timestamp": 1751234500
  },
  "data": {
    "incident_id": 987654200,
    "team":        "away",
    "player":      "Draymond Green",
    "player_out":  null,
    "game_time":   "6'"
  }
}

{
  "event":     "timeout",
  "timestamp": 1751235880,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "inprogress", "period": 3,
    "score": { "home": 87, "away": 79 },
    "start_timestamp": 1751234500
  },
  "data": {
    "incident_id": 987654210,
    "team":        "home",
    "player":      null,
    "player_out":  null,
    "game_time":   "8'"
  }
}

{
  "event":     "substitution",
  "timestamp": 1751236000,
  "match": {
    "id": 15395205, "competition_id": 132, "competition": "NBA",
    "home": { "id": 3428, "name": "Boston Celtics" },
    "away": { "id": 3412, "name": "Golden State Warriors" },
    "status": "inprogress", "period": 3,
    "score": { "home": 87, "away": 79 },
    "start_timestamp": 1751234500
  },
  "data": {
    "incident_id": 987654300,
    "team":        "away",
    "player":      "Andrew Wiggins",  // player coming IN
    "player_out":  "Klay Thompson",   // player going OUT
    "game_time":   "10'"
  }
}

GET /webhook/delete

Remove a registered webhook by its ID.

GET /api/v1/webhook/delete Free

Parameters

Parameter	docs_th_req	Description
api_key	✓	Your API key
webhook_id	✓	Numeric ID from `/webhook/register` or `/webhook/list`

Example request

https://live-basketball-api.com/api/v1/webhook/delete?api_key=YOUR_KEY&webhook_id=7

Response

{
  "status":       "success",
  "message":      "Webhook deleted successfully.",
  "webhook_id":   7,
  "url":          "https://yoursite.com/hook",
  "credits_used": 0
}

GET /webhook/list

List all active webhook registrations on your account. Also returns the full event catalogue.

GET /api/v1/webhook/list Free

Parameters

Parameter	docs_th_req	Description
api_key	✓	Your API key

Example request

https://live-basketball-api.com/api/v1/webhook/list?api_key=YOUR_KEY

Response

{
  "status":         "success",
  "webhook_count": 2,
  "limit":         10,
  "webhooks": [
    {
      "id":         7,
      "url":        "https://yoursite.com/hook",
      "events":     ["match.finish", "match.start", "score.update"],
      "has_secret": true,
      "created_at": "2026-07-02 14:30:00"
    }
  ],
  "available_events": [
    { "event": "match.start",      "description": "Match has kicked off (status changed to in-progress)" },
    { "event": "match.finish",     "description": "Match has ended — final score available" },
    { "event": "match.postponed",  "description": "Match has been postponed" },
    { "event": "match.cancelled",  "description": "Match has been cancelled" },
    { "event": "period.start",     "description": "New quarter/period started (Q1, Q2, Q3, Q4, OT)" },
    { "event": "period.end",       "description": "Quarter/period has ended (includes half-time)" },
    { "event": "score.update",     "description": "Score changed (any basket scored)" },
    { "event": "basket.2pt",       "description": "2-point field goal made" },
    { "event": "basket.3pt",       "description": "3-point field goal made" },
    { "event": "basket.freethrow", "description": "Free throw made" },
    { "event": "foul",             "description": "Foul committed (personal, technical, or flagrant)" },
    { "event": "timeout",          "description": "Timeout called" },
    { "event": "substitution",     "description": "Player substitution (in/out)" }
  ],
  "credits_used": 0
}