LiveScoreJSON API — User Guide

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.)

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 / TypeScript

livescorejson.js — Node 18+ and browsers, uses fetch, includes a WebSocket helper.

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 SDK

import { LiveScoreJSON } from "./livescorejson.js";
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_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.

Response Structure

data → area[]

Field	Type	Description
area_id	int	Region ID
name	string	Region/country name (English)
countrycode	string	ISO country code (2 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)

Response Structure

data → competition[]

Field	Type	Description
competition_id	int	League/cup ID
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	Required	Season 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)

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

Response Structure

data → team[]

Field	Type	Description
team_id	int	Team ID
club_name	string	Team name
short_name	string	Short name
country	string	Country
founded	string	Founded year
website	string	Website
telephone	string	Telephone
venue_id	int	Stadium ID
soccertype	string	Soccer type
teamtype	string	Team type (club/national)

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

Response Structure

data → venue[]

Field	Type	Description
venue_id	int	Venue ID
name	string	Venue name
city	string	City
capacity	int	Capacity
maps_geocode_latitude	float	Latitude
maps_geocode_longitude	float	Longitude
country_code	string	Country code

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 value based on selected type
start_date	yyyy-mm-dd	Optional	Start date filter
end_date	yyyy-mm-dd	Optional	End date filter
detailed	string	Optional	`yes` (default) \| `no` — Include events
home_only	string	Optional	`yes` = home matches only (type=team)
away_only	string	Optional	`yes` = away matches only (type=team)
iddaa	string	Optional	`yes` = Include betting odds (Mackolik source)

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_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, team_id, minute, minute_extra, shirtnumber

iddaa object is added to matched matches. Source: Mackolik (arsiv.mackolik.com). Updated hourly.

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`
iddaa	string	Optional	`yes` = Include betting odds (Mackolik source)

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

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_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

Response Structure

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

Field	Type	Description
type	string	Statistic type (ball_possession, shots_on_target, corners...)
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	int	Player ID
position_x	int	Pitch X coordinate
position_y	int	Pitch Y coordinate
position_name	string	Position name (GK, DF, MF, FW)

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

Response Structure

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

Field	Type	Description
attendance	int	Attendance
weather_code	string	Weather code
weather_temp	string	Temperature
venue_id	int	Venue ID
venue_name	string	Venue name
referee_id	int	Referee ID

get_tables

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

GET /api/get_tables.php

Parameters

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

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_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	int	Player ID
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

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	int	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
team1_id	int	Required	First team ID (alternative: `team_A_id`)
team2_id	int	Required	Second team ID (alternative: `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

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?team1_id=362&team2_id=364

get_rankings

Returns FIFA/UEFA world rankings.

GET /api/get_rankings.php

Parameters

Parameter	Type	Required	Description
type	string	Optional	Rank type filter
year	int	Optional	Filter by year
month	int	Optional	Filter by month

Response Structure

data → ranking[]

Field	Type	Description
rank	int	Rank
area_id	int	Country ID
team_id	int	National team ID
points	float	Points
ranking_date	date	Rank date

Example Request

GET /api/get_rankings.php?year=2026&month=4

get_squads

Returns team squads. Season-based player list.

GET /api/get_squads.php

Parameters

Parameter	Type	Required	Description
type	string	Optional	`season` (default)
id	int	Required	season_id
team_id	int	Optional	Single team squad

Response Structure

data → team[] → person[]

Field	Type	Description
person_id	int	Player ID
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...)

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_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_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	`season` \| `team` \| `player`
id	int	Required	Related ID
limit	int	Optional	Record limit per page
offset	int	Optional	Starting point (pagination)

Response Structure

data → transfer[]

Field	Type	Description
person_id	int	Player ID
person_name	string	Player name
from_team_id	int	Old team ID
from_team_name	string	Old team name
to_team_id	int	New team ID
to_team_name	string	New team name
transfer_date	date	Transfer date
fee	string	Transfer fee

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
person_id	int	Player ID
team_id	int	Team ID
suspension_type	string	Type (red_card, too_many_yellow)
remaining_matches	int	Remaining matches suspended

get_players_abroad

Returns players from a country playing abroad.

GET /api/get_players_abroad.php

Parameters

Parameter	Type	Required	Description
id	int	Required	Country/region area_id (alternative: `area_id`)

Response Structure

data → player[]

Field	Type	Description
person_id	int	Player ID
name	string	Player name
nationality_area_id	int	Nationality
team_id	int	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 referee information. By season, round, match, or region.

GET /api/get_referees.php

Parameters

Parameter	Type	Required	Description
type	string	Required	`season` \| `round` \| `match` \| `referee` \| `area`
id	int	Required	ID based on selected type

Response Structure

data → referee[]

Field	Type	Description
person_id	int	Referee ID
name	string	Full name
first_name	string	First name
last_name	string	Last name
nationality	string	Nationality
date_of_birth	date	Date of birth

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
trophy_id	int	Trophy ID
season_id	int	Season
team_id	int	Team ID
person_id	int	Player ID (optional)
award_name	string	Award name
award_year	string	Year

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

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

SDKs & Tools

JavaScript SDK

Python SDK

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_match_statistics

Parameters

Response Structure

Example Request

get_match_formations

Parameters

Response Structure

get_match_extra

Parameters

Response Structure

get_tables

Parameters

Response Structure

Example Request

get_tables_live Live

Parameters

Response Structure

get_player_statistics Real-Time Calculation

Parameters

Statistic Types

Response Structure

Example Request

get_team_statistics

Parameters

Response Structure

Example Request