LiveScoreJSON API — User Guide

health_public

A lightweight, public-facing health check endpoint used to monitor if the API database connection is alive. Recommended for UptimeRobot, Pingdom, or Load Balancers.

GET /api/health_public.php

Example Request

GET /api/health_public.php

Success Response (200 OK)

{
  "ok": true,
  "status": "healthy",
  "time": "2026-07-24T18:00:00+03:00"
}

Overview

The API operates via HTTP GET requests. All responses are in JSON format and returned in a hierarchical structure.

Base URL

https://livescorejson.com/api/

Protocol

HTTPS GET — All parameters are sent via query string

Response Format

JSON (UTF-8), standard envelope structure (meta + data)

Authentication

Authorization: Bearer or X-API-Key is required in every request

Soccer data is organized in the following hierarchical structure:

Area (Region/Country)
 └─ Competition (League/Cup)
     └─ Season (Season)
         └─ Round (Round/Week)
             └─ Group (Subgroup — optional)
                 └─ Match (Match)
                     ├─ Events (Goals, Cards, Substitutions...)
                     ├─ Statistics (Possession, Shots...)
                     └─ Formations (Formation)

Match endpoints return this hierarchy as nested JSON: competition → season → round → match

GET /api/{endpoint}.php?param1=val1&param2=val2
Authorization: Bearer ljson_live_...

All endpoint parameters are sent via query string. Authentication is performed with the Authorization: Bearer or X-API-Key header.

Username/password flow via query string is not supported for commercial client integrations.

Commercial SaaS integrations use Authorization: Bearer ljson_live_... or X-API-Key headers.

Quota response headers: X-Plan-Code, X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Reset, X-Usage-Unit-Cost, X-Usage-Units-Current-Period. 429 and Retry-After are returned on limit exceeded.

Authentication

A commercial API key must be sent as a header in every API request. Username/password flow via query string is not supported for external customer integrations.

Header	Example	Description
`Authorization`	`Bearer ljson_live_...`	Recommended authentication method
`X-API-Key`	`ljson_live_...`	Alternative for clients where adding headers is easy

API key is a secret value; do not embed it in frontend code. If usage from the browser is required, use origin/IP allowlist and restricted scope.

Quick Start

Make your first call in any language. Replace ljson_live_... with your API key. The same pattern works for all endpoints — only the endpoint name and query parameters change.

cURL

curl -s "https://livescorejson.com/api/get_matches_live.php?lang=en" \
  -H "Authorization: Bearer ljson_live_..."

JavaScript (fetch)

const res = await fetch(
  "https://livescorejson.com/api/get_matches_live.php?lang=en",
  { headers: { Authorization: "Bearer ljson_live_..." } }
);
const json = await res.json();
console.log(json.data);

Python (requests)

import requests
r = requests.get(
    "https://livescorejson.com/api/get_matches_live.php",
    params={"lang": "en"},
    headers={"Authorization": "Bearer ljson_live_..."},
)
print(r.json()["data"])

PHP (cURL)

$ch = curl_init("https://livescorejson.com/api/get_matches_live.php?lang=en");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer ljson_live_..."]);
$data = json_decode(curl_exec($ch), true);
print_r($data["data"]);

Prefer our official SDKs and Postman collection (see SDKs & Tools) — they handle auth, the base URL and the WebSocket token flow for you.

Response Format

All responses are returned in the following envelope structure:

{
  "version": "3.0",
  "sport": "soccer",
  "lang": "en",
  "last_generated": "2026-04-16 12:34:56",
  "method": {
    "method_id": "2",
    "name": "get_matches",
    "parameter": [
      { "name": "type", "value": "season" },
      { "name": "id", "value": "24922" }
    ]
  },
  "data": {
    "competition": [ ... data ... ]
  }
}

Field	Description
`version`	API version (3.0)
`sport`	Always `soccer`
`last_generated`	Time the response was generated (Europe/Istanbul, +03:00, `YYYY-MM-DD HH:MM:SS`)
`method`	Called method info and sent parameters
`data`	Data object changing according to the endpoint (competition, area, team etc.)

Measuring data freshness: live endpoints (get_matches_live, get_matches_live_updates) return an X-Data-Event-Time response header — the UTC time the underlying data was last updated at source. Measure true staleness as your current UTC time − X-Data-Event-Time. (last_generated is the response build time in Europe/Istanbul, +03:00.)

Error Codes

The API uses standard HTTP status codes.

Code	Status	Description
200	OK	Request successful, data returned
400	Bad Request	Missing or invalid parameter
401	Unauthorized	Missing or invalid API key
403	Forbidden	Account disabled or subscription expired
500	Server Error	Server-side error

Response in case of error:

{ "error": "Missing parameter: type" }

Entity ID Stability

Player, team, competition and season IDs are globally stable and persistent — they do not change across teams, seasons or competitions. You never have to build a mapping or normalization layer: one ID identifies the same entity everywhere in the API, so you can safely store it as a foreign key in your own database.

ID	Stable across	Use it as
`player_id`	every club, season and competition the player appears in	a single key for a player's full career, stats and transfers
`team_id`	league, cup and all seasons	a permanent key for a club in any context
`competition_id`	all of its seasons	a permanent key for a league/cup
`season_id`	matches, tables, squads and every related endpoint	a permanent key for a single season

Proof: one player_id, the whole career

A single player_id passed to get_career returns every club, competition and season the player has played in — the same ID, never re-scoped per team or season:

GET /api/get_career.php?type=player&id={player_id}
→ data.person.career[] — many rows spanning multiple
  team_id / competition_id / season_id, all under the same player_id

The same player_id also works directly in get_player_statistics, get_transfers and get_squads — independently of any team or season filter.

IDs are persistent and safe to use as foreign keys. (Rare entity merges in deep historical data are handled on a best-effort basis.)

Asset URL Fields

Team, player, venue, and competition assets are added to supported canonical API objects as public HTTPS URLs.

Field	Related ID	Content
`team_logo_url`	`team_id`	Team logo
`player_photo_url`	`person_id` / `player_id`	Player photo
`venue_photo_url`	`venue_id`	Venue photo
`competition_logo_url`	`competition_id`	League or cup logo

Asset fields are string|null. The field is null when no related asset is available. Raw detail components and technical staff are excluded from player photo fields. Matches use team_A_logo_url/team_B_logo_url; transfers use from_team_logo_url/to_team_logo_url. The venue's legacy photo field contains source/credit text and is not an image URL.

SDKs & Tools

Official thin SDKs (zero dependencies) and a ready-to-import Postman collection covering every endpoint.

Postman Collection

Download .json — import into Postman, set baseUrl and bearerToken, call every endpoint.

JavaScript (ESM)

Browser: livescorejson.v3.0.5.js · Node: livescorejson.v3.0.5.mjs — REST calls work in modern browsers and Node 18+; the WebSocket helper needs a browser or Node 22+.

Python

livescorejson.py — Python 3.7+, standard library only (no pip install).

OpenAPI Spec

openapi.json — OpenAPI 3.0.3; generate a client in any language with openapi-generator.

Embeddable Widgets

Widget builder — drop-in live standings & scores via <iframe>, no API key in the page. Light/dark, multi-language.

JavaScript (ESM) SDK

import { LiveScoreJSON } from "./livescorejson.v3.0.2.mjs";
const api = new LiveScoreJSON({ apiKey: "ljson_live_..." });
const live = await api.getMatchesLive({ lang: "en" });
console.log(live.data);

Python SDK

from livescorejson import LiveScoreJSON
api = LiveScoreJSON(api_key="ljson_live_...")
print(api.get_matches_live(lang="en")["data"])

get_search

Searches teams, competitions, countries, and football players in one call. There is no request-side type parameter; all four catalogs are searched automatically.

GET /api/get_search.php

Parameters

Parameter	Type	Required	Description
q	string	Required	Search text; 2-80 characters.
limit	int	Optional	1-100; default 20.
lang	string	Optional	Two-letter language code; default `en`.

Response Structure

data → search[]

Field	Type	Description
entity	string	`team`, `competition`, `country`, or `player`
name	string	Display name
secondary_name	string\|null	Official, original, or alternative full name
area_id / area_name	int / string	Country/area information for the team, competition, or player
countrycode	string\|null	Three-letter country code
subtype	string\|null	Entity subtype
team_logo_url / competition_logo_url / player_photo_url	string\|null	Public asset URL matching the result type

Example Request

GET /api/get_search.php?q=fener&limit=20&lang=tr

get_areas

Returns the list of regions and countries. Geographical regions that matches, teams, and leagues are connected to.

GET /api/get_areas.php

Parameters

Parameter	Type	Required	Description
area_id	int	Optional	A specific region. If not provided, all regions are returned.
lang	string	Optional	Language code

Response Structure

data → area[]

Field	Type	Description
area_id	int	Region ID
name	string	Region/country name (English)
parent_area_id	int\|null	Parent region/continent ID (e.g. Europe, Asia)
countrycode	string	ISO country code (2/3 letters)

Example Request

GET /api/get_areas.php?area_id=221

get_competitions

Returns the list of leagues and cups. Can be filtered by region or type.

GET /api/get_competitions.php

Parameters

Parameter	Type	Required	Description
area_id	int	Optional	Filter by region
type	string	Optional	Type filter (e.g., league, cup)
lang	string	Optional	Language code

Response Structure

data → competition[]

Field	Type	Description
competition_id	int	League/cup ID
competition_logo_url	string\|null	Public HTTPS URL of the league/cup logo
name	string	League name
soccertype	string	Soccer type
teamtype	string	Team type (club/national)
display_order	int	Display order
type	string	Type (league, cup, ...)
format	string	Format
area_id	int	Connected region ID
area_name	string	Region name

Example Request

GET /api/get_competitions.php?area_id=221

get_seasons

Returns the seasons of a competition. Comes wrapped nested with competition info.

GET /api/get_seasons.php

Parameters

Parameter	Type	Required	Description
competition_id	int	Optional	Filter by competition. If not provided, all seasons.
active	string	Optional	`yes` = only active seasons (end_date ≥ today)

Response Structure

data → competition[] → season[]

Field	Type	Description
season_id	int	Season ID
name	string	Season name (e.g.: "2025/2026")
start_date	date	Start date
end_date	date	End date
service_level	string	Data service level

Example Request

GET /api/get_seasons.php?competition_id=8&active=yes

get_rounds

Returns the rounds of a season (week, elimination round etc.).

GET /api/get_rounds.php

Parameters

Parameter	Type	Required	Description
season_id	int	Optional	Season ID
type	string	Optional	Filter type
id	int	Optional	Filter ID

Send round_id or season_id. Alternatively, send type=round|season together with id.

Response Structure

data → competition[] → season[] → round[]

Field	Type	Description
round_id	int	Round ID
name	string	Round name
start_date	date	Start date
end_date	date	End date
type	string	Round type
ordermethod	string	Rank method
groups	string	Group info
has_outgroup_matches	boolean	Any non-group matches

Example Request

GET /api/get_rounds.php?season_id=24922

get_groups

Returns the subgroups in a round or season (like Champions League groups).

GET /api/get_groups.php

Parameters

Parameter	Type	Required	Description
round_id	int	Optional	Filter by round
season_id	int	Optional	Filter by season (covers all rounds)
type	string	Optional	Filter type
id	int	Optional	Filter ID

Response Structure

data → group[]

Field	Type	Description
group_id	int	Group ID
name	string	Group name (e.g.: "Group A")
round_id	int	Connected round ID

get_teams

Returns team information. Can be filtered by region, season, or competition.

GET /api/get_teams.php

Parameters

Parameter	Type	Required	Description
type	string	Optional	`area` \| `season` \| `competition`
id	int	Optional	Filter ID according to type
team_id	int	Optional	Get a single team by ID
area_id	int	Optional	Filter teams directly by area/country ID
status	string	Optional	`active` \| `inactive`
soccertype	string	Optional	`default` \| `women`
teamtype	string	Optional	`default` \| `u21` \| `u19`
city	string	Optional	Filter by city name

Response Structure

data → team[]

Field	Type	Description
team_id	int	Team ID
team_logo_url	string\|null	Public HTTPS URL of the team badge/logo
club_name	string	Club name
short_name	string	Short name
country	string	Country name
city	string\|null	City where the club is based
founded	string\|null	Foundation year
url	string\|null	Official website URL
telephone	string\|null	Phone number
venue_id	int\|null	Home stadium venue ID
venue_name	string\|null	Home stadium name
venue_city	string\|null	Home stadium city
venue_capacity	string\|null	Home stadium spectator capacity
venue_surface	string\|null	Home stadium pitch surface (grass, artificial, etc.)
venue_address	string\|null	Home stadium street address
venue_photo_url	string\|null	Public HTTPS URL of the stadium photo
status	string	Club status (active, etc.)
soccertype	string	Soccer type (default, women, etc.)
teamtype	string	Team type (default, u21, etc.)

Example Request

GET /api/get_teams.php?type=season&id=24922

get_venues

Returns stadium information.

GET /api/get_venues.php

Parameters

Parameter	Type	Required	Description
type	string	Optional	`area` \| `season`
id	int	Optional	Filter ID according to type
venue_id	int	Optional	Single stadium by venue ID
team_id	int	Optional	Home stadium of a specific team
area_id	int	Optional	Filter stadiums by area/country ID
city	string	Optional	Filter by city
surface	string	Optional	Filter by pitch surface (e.g. grass, artificial)

Response Structure

data → venue[]

Field	Type	Description
venue_id	int	Venue ID
venue_photo_url	string\|null	Public HTTPS URL of the venue photo
name	string	Venue name
city	string\|null	City
capacity	int\|null	Spectator capacity
surface	string\|null	Pitch surface (grass, artificial, etc.)
address	string\|null	Street address
opened	string\|null	Year opened
latitude / maps_geocode_latitude	float\|null	Geographic latitude
longitude / maps_geocode_longitude	float\|null	Geographic longitude
country_code / area_name	string\|null	Country code / region name

get_matches

Returns matches in a hierarchical structure. Most commonly used endpoint. Offers various filtering options.

GET /api/get_matches.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`area` \| `season` \| `round` \| `group` \| `match` \| `team`
id	int	Required	ID based on selected type
start_date	date	Optional	Start date (YYYY-MM-DD)
end_date	date	Optional	End date (YYYY-MM-DD)
status	string	Optional	Match status: `Played` \| `Playing` \| `Fixture` \| `Postponed` \| `Cancelled`
gameweek	int	Optional	Gameweek / matchday number
round_id	int	Optional	Filter by round within season/team
group_id	int	Optional	Filter by group within tournament
winner	string	Optional	Filter by outcome: `team_A` \| `team_B` \| `draw`
detailed	string	Optional	`yes` (default, includes events) \| `no`
home_only / away_only	string	Optional	`yes` (when type=team)
iddaa	string	Optional	`yes` to attach betting odds

Response Structure

data → competition[] → season[] → round[] → match[]

Field	Type	Description
match_id	int	Match ID
date_utc	date	Match date (UTC)
time_utc	time	Match time (UTC)
status	string	`Fixture` \| `Playing` \| `Played` \| `Postponed` \| `Cancelled` \| `Suspended`
team_A_id	int	Home team ID
team_B_id	int	Away team ID
team_A_logo_url / team_B_logo_url	string\|null	Home and away team logo URLs
team_A_name	string	Home team name
team_B_name	string	Away team name
fs_A / fs_B	int	Full time score
hts_A / hts_B	int	Half time score
ets_A / ets_B	int	Extra time score
ps_A / ps_B	int	Penalty score

There can be 6 event groups under each match:

Group	Codes	Description
lineups	L	Starting 11 lineup
lineups_bench	SUB	Substitute players
goals	G, PG, OG	Goals (normal, penalty, own goal)
substitutions	SI, SO	Player substitutions (in/out)
bookings	YC, Y2C, RC	Cards (yellow, double yellow, red)
penalty_shootout	PSG, PSM	Penalty shootouts (goal/missed)

Each event: event_id, code, person, person_id, player_photo_url, team_id, team_logo_url, minute, minute_extra, shirtnumber

An iddaa object is added when odds are available. Odds are refreshed periodically.

Field	Type	Description
iddaa.mbs	int	Minimum Bet Count (1–5)
iddaa.fetched_at	datetime	Last update time (UTC)
iddaa.markets[]	array	List of bet markets (~50 markets)

Each market object:

Field	Type	Description
MarketType.Id	int	Market type ID
MarketType.Name	string	Market name (e.g.: Match Result, Double Chance, 2.5 Goal Under/Over)
MBS	int	MBS for this market
Outcomes[]	array	Outcome options
Outcomes[].OutcomeName	string	Option name (e.g.: 1, X, 2, Under, Over)
Outcomes[].Odd	float	Odd value

Common market types: Match Result, Double Chance, First Half/Match Result, 2.5 Goal Under/Over, Both Teams to Score, Handicap Match Result, Corner Under/Over, Card Under/Over, Odd/Even, 1st Half Result etc.

The iddaa field is not returned for matches without betting odds. Betting odds are only available for matches in the official betting program.

Example Requests

// All Premier League 2025/2026 matches
GET /api/get_matches.php?type=season&id=24922

// Manchester United home matches (January-March)
GET /api/get_matches.php?type=team&id=362&home_only=yes&start_date=2026-01-01&end_date=2026-03-31

// Single match (without events)
GET /api/get_matches.php?type=match&id=3456789&detailed=no

// Single match + Betting odds
GET /api/get_matches.php?type=match&id=4948913&iddaa=yes

get_matches_live Live

Returns matches of a specific day with live scores. Updated at 30-second intervals.

GET /api/get_matches_live.php

Parameters

Parameter	Type	Required	Description
date	yyyy-mm-dd	Optional	Date. Default: today.
detailed	string	Optional	`yes` (default) \| `no`
now_playing	string	Optional	`yes` = only currently playing
matchtype	string	Optional	`live` \| `fixture` \| `all`
sort	string	Optional	`custom` = move leagues to the top in `competition_order` order
competition_order	string	Optional	Comma-separated `competition_id` list. The first 50 valid unique IDs are used; unspecified leagues retain their existing order.
iddaa	string	Optional	`yes` = include available betting odds

Response Structure

data → competition[] → season[] → round[] → match[]

Response structure is the same as get_matches.

Live scores are updated at 30-second intervals. Be careful not to exceed this interval when polling.

For betting odds structure, see the Betting Odds Structure accordion in the get_matches section.

Example Requests

// All currently playing live matches for today
GET /api/get_matches_live.php?date=2026-04-16&now_playing=yes

// Today's matches + Betting odds
GET /api/get_matches_live.php?date=2026-04-16&iddaa=yes

// Move Süper Lig, Bundesliga and Premier League to the top in this order
GET /api/get_matches_live.php?sort=custom&competition_order=19,9,8

get_matches_live_updates Delta

Returns matches updated after the specified time. Ideal for bandwidth saving.

GET /api/get_matches_live_updates.php

Parameters

Parameter	Type	Required	Description
last_updated	yyyy-mm-dd hh:mm:ss	Required	Last update time. Matches that changed after this time are returned.

Response Structure

data → next_since + data → competition[] → season[] → round[] → match[]

Field	Type	Description
data.next_since	yyyy-mm-dd hh:mm:ss	Server-authoritative cursor. Pass this exact value as `last_updated` on your next poll — no client-side clock math, no skipped or double-fetched updates. Also returned as the `X-Next-Since` header.

Polling Loop

First request: send the start of the day (or any past time). Then keep passing the next_since the server returns:

# 1) first poll
GET /api/get_matches_live_updates.php?last_updated=2026-04-16 00:00:00
→ data.next_since = "2026-04-16 15:30:12"

# 2) next poll — reuse next_since, no clock math on your side
GET /api/get_matches_live_updates.php?last_updated=2026-04-16 15:30:12

Bandwidth Saving (conditional requests)

Every response carries an ETag. Send it back as If-None-Match; when nothing changed since your last poll the API returns 304 Not Modified with an empty body — so idle polls cost almost nothing.

GET /api/get_matches_live_updates.php?last_updated=2026-04-16 15:30:12
If-None-Match: "<etag-from-previous-response>"

← 304 Not Modified   (no body)

Combine next_since + If-None-Match for the cheapest possible live polling. For true real-time push (no polling at all), use the WebSocket channel.

get_aggregates

Returns the verified winner of a knockout round or multi-match tie. This is separate from a single match's winner field.

GET /api/get_aggregates.php

Parameters

Parameter	Type	Required	Description
id	int	Required	Match ID. The result contains at most one aggregate record.

Response Structure

data → aggregate[]

Field	Type	Description
match_id	string	The match linked to the aggregate record.
round_id	string\|null	The match's round ID.
aggregate_winner_status	known \| draw \| unknown	`known` is a verified team; `draw` is a tie; `unknown` is unresolved or unverifiable.
aggregate_winner_team_id	string\|null	Canonical team ID only when the verified winner is one of the match participants.
aggregate_winner_team_name	string\|null	Canonical team name only when status is `known`.

Raw winner text is never exposed. Invalid, orphaned or non-participant team IDs return unknown with both team fields set to null.

Example Request

GET /api/get_aggregates.php?id=5060309

get_runningball_matches Live

Returns matches that are currently in Playing status.

GET /api/get_runningball_matches.php

Parameters

Parameter	Type	Required	Description
date	yyyy-mm-dd	Optional	Deprecated; accepted for backward compatibility but does not filter the result.

Response Structure

data → competition[] → season[] → round[] → match[]

The match structure is the same as get_matches_live; only matches currently being played are included.

Example Request

GET /api/get_runningball_matches.php

get_match_statistics

Returns detailed statistics of a match (possession, shots, corners etc.).

GET /api/get_match_statistics.php

Parameters

Parameter	Type	Required	Description
id	int	Required	Match ID
detailed	string	Optional	Detailed statistics (yes/no)
components	string	Optional	Comma separated components

Response Structure

data → competition[] → ... → match → data[]

Field	Type	Description
type	string	Statistic type (possession, shots_on_target, corners... Exact 36-key schema is guaranteed)
value_team_A	string	Home value
value_team_B	string	Away value

Example Request

GET /api/get_match_statistics.php?id=3456789

get_match_formations

Returns the formations and match info (referee, venue, manager).

GET /api/get_match_formations.php

Parameters

Parameter	Type	Required	Description
id	int	Required	Match ID

Response Structure

data → competition[] → ... → match → formation[] + matchinfo[]

Field	Type	Description
team_id	int	Team ID
person_id	string	Player ID
player_photo_url	string\|null	Public HTTPS URL of the player photo
position_x	int	Pitch X coordinate
position_y	int	Pitch Y coordinate
position_name	string	Position name (GK, DF, MF, FW)

get_match_commentary

Returns the timeline commentary for a match.

GET /api/get_match_commentary.php

Parameters

Parameter	Type	Required	Description
id	int	Required	Match ID

Response Structure

data → competition[] → season[] → round[] → match[] → commentary[]

Field	Type	Description
minute / minute_extra / second	string\|null	Match time of the commentary
period	string\|null	Match period
comment	string	Commentary text
type	string\|null	Commentary type
goal / important / is_old	string\|null	Commentary flags
last_updated	string\|null	Last update time

Example Request

GET /api/get_match_commentary.php?id=4891367

get_match_extra

Returns extra info about the match: venue, attendance, weather, referee.

GET /api/get_match_extra.php

Parameters

Parameter	Type	Required	Description
id	int	Required	Match ID
include	string	Optional	Include extra data (e.g. commentary)
components	string	Optional	Comma separated components

Response Structure

data → competition[] → ... → match → matchinfo

Field	Type	Description
match_id	int	Match ID
venue_id	int\|null	Venue ID
venue_name	string\|null	Venue name
venue_city	string\|null	Venue city
venue_capacity	string\|null	Venue capacity
venue_address	string\|null	Venue street address
venue_surface	string\|null	Venue pitch surface (grass, artificial, etc.)
venue_opened	string\|null	Venue opening year
venue_photo	string\|null	Venue photo asset / reference
referee_person_id / referee_name	int / string	Main referee info
coach_a_id / coach_a_name	int / string	Team A coach info
coach_b_id / coach_b_name	int / string	Team B coach info
attendance	int\|null	Official spectator attendance
formation_a / formation_b	string\|null	Tactical formations (e.g. 4-2-3-1)

get_match_editorials

Returns available editorial content for a match.

GET /api/get_match_editorials.php

Parameters

Parameter	Type	Required	Description
id	int	Required	Match ID
lang	string	Optional	Language code for the response envelope; default `en`

Response Structure

data → editorial[]

Records are returned as stored. The editorial list is empty when no content is available.

Example Request

GET /api/get_match_editorials.php?id=4891367&lang=en

get_tables

Returns the standings/league table. By season or round.

GET /api/get_tables.php

Parameters

Parameter	Type	Required	Description
id	int	Required	Season ID or Round ID
type	string	Optional	`season` (default) \| `round`
round_id	int	Optional	Filter by round within season
group_id	int	Optional	Filter by tournament group
team_id	int	Optional	Filter standing for a specific team

Response Structure

data → competition[] → season[] → round[] → resultstable → ranking[]

Field	Type	Description
rank	int	Rank
team_id	int	Team ID
club_name	string	Team name
matches_total	int	Matches played
matches_won	int	Wins
matches_draw	int	Draws
matches_lost	int	Losses
goals_pro	int	Goals for
goals_against	int	Goals against
points	int	Points

Example Request

GET /api/get_tables.php?type=season&id=24922

get_tables_live Live

Live standings. Takes ongoing matches into account to calculate how the table would look if matches ended with current scores.

GET /api/get_tables_live.php

Parameters

Parameter	Type	Required	Description
type	string	Optional	`season` (default) \| `round`
id	int	Required	season_id or round_id

Response Structure

The response structure is the same as get_tables.

Rankings are finalized automatically when matches finish. If no live matches, it returns the same result as get_tables.

get_tables_cumulative

Returns a season's accumulated standings across rounds.

GET /api/get_tables_cumulative.php

Parameters

Parameter	Type	Required	Description
id	int	Required	Season ID
type	string	Optional	Deprecated; accepted but does not change the result.

Response Structure

data → competition[] → season[] → round[] → resultstable[] → ranking[]

id is always treated as a season ID. Ranking fields are the same as get_tables.

Example Request

GET /api/get_tables_cumulative.php?id=27218

get_betting_statistics

Returns aggregate betting trends for a season or competition; this is not a match-odds endpoint.

GET /api/get_betting_statistics.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`season` \| `competition`
id	int	Required	Season or competition ID
market	string	Optional	Market-code filter

Response Structure

data → betting_statistic[]

Field	Type	Description
season_id	string	Season ID
market	string	Market code
category_code / subcategory_code	string\|null	Category codes
outcome_code	string\|null	Outcome code
outcome_value / outcome_percentage	string\|null	Aggregate outcome value and percentage
last_updated	string\|null	LiveScoreJSON record-update time, not the source event time

Example Request

GET /api/get_betting_statistics.php?type=season&id=25828

get_player_statistics Real-Time Calculation

Player statistics (goals, assists, cards). Calculated in real-time from match events, no caching.

GET /api/get_player_statistics.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`season` \| `round`
id	int	Required	season_id or round_id
team_id	int	Optional	Filter by team
player_id	int	Optional	Single player
limit	int	Optional	Top N players (e.g. 10)

Statistic Types

stat_type	Scope	Description
goals	G + PG	Normal + penalty goals (excluding own goals)
assists	AS	Assists
yellow_cards	YC + Y2C	Yellow + double yellow cards
red_cards	RC	Red cards

Response Structure

data → competition[] → season[] → player_statistic[]

Field	Type	Description
person_id	string	Player ID
player_photo_url	string\|null	Public HTTPS URL of the player photo
person	string	Player name
team_id	int	Team ID
team_name	string	Team name
stat_type	string	Statistic type
count	int	Count
rank	int	Rank

In case of transfer, the player is assigned to the team where they have the most events.

Example Request

// Premier League top scorers (Top 10)
GET /api/get_player_statistics.php?type=season&id=24922&limit=10

get_team_statistics

Returns detailed season-based statistics of a team.

GET /api/get_team_statistics.php

Parameters

Parameter	Type	Required	Description
team_id	int	Required	Team ID
season_id	int	Optional	Filter by season
form	string	Optional	`yes`: only `form-*`; `no`: only regular types. Omit for all.

Response Structure

data → team → team_statistic[]

Field	Type	Description
stat_type	string	Statistic type (total_matches, home_won_percent, avg_goals...)
stat_value	string	Value
season_id	string\|null	Season ID

Example Request

GET /api/get_team_statistics.php?team_id=362&season_id=24922

get_head2head Real-Time Calculation

Calculates head-to-head match statistics between two teams. Calculated in real-time from match data.

GET /api/get_head2head.php

Parameters

Parameter	Type	Required	Description
team_A_id	int	Conditional	Canonical parameter for the first team
team_B_id	int	Conditional	Canonical parameter for the second team
team1_id	int	Conditional	Backward-compatible alternative to `team_A_id`
team2_id	int	Conditional	Backward-compatible alternative to `team_B_id`
competition_id	int	Optional	Filter by competition
start_date	yyyy-mm-dd	Optional	Start date filter
end_date	yyyy-mm-dd	Optional	End date filter

One parameter is required for each team: team_A_id or team1_id; team_B_id or team2_id. When both forms are sent, the canonical parameter wins.

Response Structure

data → head_2_head[]

Matches played, win/draw distribution, home/away performance, goal statistics.

Example Request

// Manchester United vs Liverpool
GET /api/get_head2head.php?team_A_id=362&team_B_id=364

get_predictions Statistical Model

Match outcome probabilities (1X2), over/under 2.5, both-teams-to-score and the most likely scorelines, computed by our own statistical model (Poisson on recent team form + league home/away averages). An informational forecast, not betting advice.

This is a statistical model (recent form, Poisson) — not an xG/ML product and not sourced predictions. Backtested on 210K matches (51.7% 1X2 accuracy, beating the home-bias baseline). Use it as a probabilistic signal, not a guarantee.

GET /api/get_predictions.php

Parameters

Parameter	Type	Required	Description
match_id	int	Required	The match to predict. Both teams need at least 6 prior played matches.

Response Structure

data → prediction

Field	Type	Description
result	object	`home_win` / `draw` / `away_win` probabilities (sum to 1)
over_under_2_5	object	`over` / `under` 2.5 goals probabilities
btts	object	Both teams to score `yes` / `no` probabilities
projected_goals	object	Model goal expectation per side (Poisson λ — not xG)
likely_scores	array	Top 5 most likely scorelines with probabilities
disclaimer	string	Model + not-betting-advice note

Example Request

GET /api/get_predictions.php?match_id=4350869

get_rankings

Returns team rankings filtered by type and publication date.

GET /api/get_rankings.php

Parameters

Parameter	Type	Required	Description
type	string	Optional	`ranking_type` filter; currently available type: `fifa`
year	int	Optional	Filter by year
month	int	Optional	Filter by month

Response Structure

data → ranking[]

Field	Type	Description
rank	string	Rank
area_id	string\|null	Country ID
team_id	string\|null	National team ID
points	string\|null	Points
ranking_type	string	Ranking type
ranking_date	string	Ranking publication date

Example Request

GET /api/get_rankings.php?type=fifa&year=2026&month=1

get_squads

Returns team squads. Season-based player list.

GET /api/get_squads.php

Parameters

Parameter	Type	Required	Description
id	int	Optional	Season ID (e.g. 27549)
team_id	int	Optional	Team ID (e.g. 10471)
position	string	Optional	`Goalkeeper` \| `Defender` \| `Midfielder` \| `Attacker`
role	string	Optional	`Player` \| `Coach`
type	string	Optional	`season` (default)

Response Structure

data → team[] → person[]

Field	Type	Description
person_id	int	Player ID
player_photo_url	string\|null	Public HTTPS URL of the player photo
name	string	Full name
first_name	string	First name
last_name	string	Last name
nationality_id	int	Nationality (area_id)
date_of_birth	date	Date of birth
height	int	Height (cm)
weight	int	Weight (kg)
foot	string	Foot (left/right/both)
shirtnumber	int	Shirt number
role	string	Position (Goalkeeper, Defender, Midfielder, Attacker)
status	string	Squad status (active, on_loan...)
appearances / goals / assists	string\|null	Season appearance, goal and assist totals
minutes_played / substituted_in	string\|null	Minutes played and substituted-in totals
yellow_cards / red_cards	string\|null	Yellow- and red-card totals

Example Request

GET /api/get_squads.php?id=24922&team_id=362

get_squads_changes Delta

Returns squad changes. Records updated after the specified time.

GET /api/get_squads_changes.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`match` \| `season`
id	int	Required	match_id or season_id
last_updated	yyyy-mm-dd hh:mm:ss	Optional	Delta time

Response Structure

The response structure is the same as get_squads. Only updated records are returned.

get_career

Returns player or team career statistics.

GET /api/get_career.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`player` \| `team`
id	int	Required	person_id or team_id

Response Structure

data → person|team → career[]

Field	Type	Description
season_id	int	Season ID
competition_id	int	Competition ID
team_id	int	Team ID
appearances	int	Appearances
goals	int	Goals
assists	int	Assists

Example Request

// Career statistics of Mohamed Salah
GET /api/get_career.php?type=player&id=174352

get_transfers

Returns transfer records. Can be filtered by season, team, or player. Supports pagination.

GET /api/get_transfers.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`team` \| `player` \| `season`
id	int	Required	ID based on selected type
start_date	date	Optional	Filter transfers after date (YYYY-MM-DD)
end_date	date	Optional	Filter transfers before date (YYYY-MM-DD)
year	int	Optional	Filter transfers by year (e.g. 2024)
transfer_type	string	Optional	`Loan` \| `Transfer` \| `Free transfer`
limit	int	Optional	Number of records (default 20, max 100)
offset	int	Optional	Starting point (pagination)

Response Structure

data → transfer[]

Field	Type	Description
id	int	Transfer record ID
person_id	int	Player ID
person_name	string	Player name
from_team_id	int\|null	Old team ID
from_team_name	string\|null	Old team name
to_team_id	int\|null	New team ID
to_team_name	string\|null	New team name
transfer_date	date	Transfer date
transfer_type / type	string\|null	Transfer type (Loan, Free transfer, Transfer, etc.)
amount	string\|null	Transfer fee / compensation amount
proceeded	string\|null	Transfer status / confirmation

get_players

Returns profiles whose type is exactly player. Staff and internal fields are not included in the response.

GET /api/get_players.php

Parameters

Parameter	Type	Required	Description
id	int	Optional	Single player ID
cursor	int	Optional	Keyset pagination cursor (last seen person_id)
limit	int	Optional	Page size (1-500, default 100)
area_id / country_id	int	Optional	Filter players by nationality/country ID
team_id	int	Optional	Filter players currently/historically at team

Response Structure

data → player[] + pagination

Field	Type	Description
person_id	int	Player ID
type	string	Always `player`
first_name	string\|null	First name
middle_name	string\|null	Middle name
last_name	string\|null	Last name
name	string\|null	Display name
nationality_area_id	string\|null	Nationality area ID
nationality	string\|null	Nationality
date_of_birth	date\|null	Date of birth
place_of_birth	string\|null	Place of birth
country_of_birth_id	string\|null	Birth country ID
country_of_birth	string\|null	Birth country
foot	string\|null	Preferred foot
status	string\|null	Player status
height	string\|null	Height (cm)
weight	string\|null	Weight (kg)
international_caps	string\|null	International appearances
international_goals	string\|null	International goals
player_photo_url	string\|null	Player photo URL

Pagination

Field	Type	Description
limit	int	Applied page limit
has_more	bool	`true` when another page is available
next_cursor	string\|null	Cursor for the next request

Example Requests

// Single player profile by ID
GET /api/get_players.php?id=119

// Next player catalog page using the cursor
GET /api/get_players.php?cursor=119&limit=100

get_injuries

Returns injury records. 6 different filter types.

GET /api/get_injuries.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`season` \| `round` \| `competition` \| `player` \| `team` \| `match`
id	int	Required	ID based on selected type

Response Structure

data → injury[]

Field	Type	Description
person_id	int	Player ID
person_full_name	string	Player full name
team_id	int	Team ID
expected_end_date	date	Expected end date
status	string	Status
injury_type	string	Injury type

get_suspensions

Returns suspended players (red card or card accumulation).

GET /api/get_suspensions.php

Parameters

Parameter	Type	Required	Description
id	int	Required	Filter ID
type	string	Optional	`season` \| `team` \| `match` \| `player`

Response Structure

data → suspension[]

Field	Type	Description
id	int	Suspension record ID
person_id / person_name / person_full_name	int / string	Suspended player/coach info
team_id / team_name / team_full_name	int / string	Associated team info
season_id / round_id / match_id	int\|null	Associated season, round and match ID
suspended_matches	int\|null	Number of suspended matches
suspension_type	string\|null	Type of suspension (matches, period, etc.)
start_date / end_date	date\|null	Suspension date range
description	string\|null	Official reason / description of suspension

get_players_abroad

Returns players from a country playing abroad.

GET /api/get_players_abroad.php

Parameters

Parameter	Type	Required	Description
id	int	Conditional	Country/area ID; canonical parameter
area_id	int	Conditional	Backward-compatible alternative to `id`

Send id or area_id. When both are sent, id wins.

Response Structure

data → player[]

Field	Type	Description
person_id	int	Player ID
player_photo_url	string\|null	Public HTTPS URL of the player photo
name	string	Player name
nationality_area_id	int	Nationality
team_id	string	Current team ID
team_name	string	Current team name
team_area_id	int	Team country ID
team_area_name	string	Team country name

Example Request

// Turkish players abroad
GET /api/get_players_abroad.php?id=221

get_referees

Returns main-referee assignments by match, round, or season, with one row per match. This endpoint does not provide person profiles or nationality; assistant officials remain available from match-detail endpoints.

GET /api/get_referees.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`match` \| `round` \| `season`
id	int	Required	Positive ID for the selected type (maximum 2147483647)

Response Structure

data → referee[]

Field	Type	Description
match_id	string	Match ID for this assignment
round_id	string	Round ID
season_id	string	Season ID
referee_person_id	string	Main-referee identifier
referee_name	string\|null	Main-referee name; null when unknown

Each row is one match's main-referee assignment. When no assignment exists, referee is an empty array. The referee and area filters are not supported.

Example Request

GET /api/get_referees.php?type=match&id=4661321

get_trophies

Returns trophy and award records.

GET /api/get_trophies.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`competition` \| `season` \| `team` \| `player`
id	int	Required	ID based on selected type

Response Structure

data → trophy[]

Field	Type	Description
id	int	Trophy record ID
competition_id / competition_name	int / string	Competition / tournament details
season_id / season_name	int / string	Season details
team_id / team_name	int / string	Club / team details
person_id / person_name	int / string\|null	Player details (for individual awards)
trophy_type	string\|null	Trophy / achievement category
position	int\|null	Rank / achievement position (1: Winner, 2: Runner-up)

get_season_coverage

Per-season coverage map: which data capabilities (live scores, lineups, cards, transfers, injuries…) are available for a given season, their timing (before/after the match, live) and update cadence. Check coverage before you integrate — no more guessing whether a long-tail season has lineups.

GET /api/get_season_coverage.php

Parameters

Parameter	Type	Required	Description
season_id	int	Required	The season to inspect (from `get_seasons`).

Response Structure

data → season_coverage → capabilities[]

Field	Type	Description
capability	string	Data type, e.g. `live_scores`, `lineups`, `cards`, `transfers`, `injuries`
available	bool	Whether this capability is provided for the season
timing	string	`Live` / `Before the match` / `After the match` / `Not available`
update_interval_minutes	int	Refresh cadence in minutes (where applicable)

Example Request

GET /api/get_season_coverage.php?season_id=27218

get_deleted

Returns records deleted after the specified time.

GET /api/get_deleted.php

Parameters

Parameter	Type	Required	Description
start_date	string	Optional	Start time; defaults to the previous 24 hours
type	string	Optional	Filter on response `item_type`: area, competition, season, round, group, match, event, team, or person

Response Structure

data → deleted_item[]

Records deleted at or after start_date are returned newest first.

Example Request

GET /api/get_deleted.php?start_date=2026-08-12%2000:00:00&type=match

get_hashtags

Returns hashtags associated with a competition, team, or match.

GET /api/get_hashtags.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`competition` \| `team` \| `match`
id	int	Required	ID of the selected type

Response Structure

data → hashtag[]

Example Request

GET /api/get_hashtags.php?type=team&id=2212

get_ws_token

Issues a short-lived WebSocket connection token. It returns the JSON object below directly, not the standard API envelope.

GET /api/get_ws_token.php

Response Structure

direct JSON object

Field	Type	Description
token	string	Short-lived connection token
token_jti	string	Token session identifier
expires_at	date-time string	UTC expiration time
ws_url	URI string	WebSocket connection address

Do not send API credentials over WebSocket. Use the short-lived token obtained over HTTPS when connecting to ws_url.

Example Request

GET /api/get_ws_token.php

health_public

Example Request

Success Response (200 OK)

LiveScoreJSON API Guide

Overview

Authentication

Quick Start

cURL

JavaScript (fetch)

Python (requests)

PHP (cURL)

Response Format

Error Codes

Entity ID Stability

Proof: one player_id, the whole career

Asset URL Fields

SDKs & Tools

JavaScript (ESM) SDK

Python SDK

get_search

Parameters

Response Structure

Example Request

get_areas

Parameters

Response Structure

Example Request

get_competitions

Parameters

Response Structure

Example Request

get_seasons

Parameters

Response Structure

Example Request

get_rounds

Parameters

Response Structure

Example Request

get_groups

Parameters

Response Structure

get_teams

Parameters

Response Structure

Example Request

get_venues

Parameters

Response Structure

get_matches

Parameters

Response Structure

Example Requests

get_matches_live Live

Parameters

Response Structure

Example Requests

get_matches_live_updates Delta

Parameters

Response Structure

Polling Loop

Bandwidth Saving (conditional requests)

get_aggregates

Parameters

Response Structure

Example Request

get_runningball_matches Live

Parameters

Response Structure

Example Request

get_match_statistics

Parameters

Response Structure

Example Request

get_match_formations

Parameters

Response Structure

get_match_commentary

Parameters

Response Structure