slickbet.api

Livescore API client for fetching soccer matches and statistics.

Provides dataclasses for teams, odds, fixtures, and historical matches, plus LivescoreClient for authenticated requests with optional file-based caching.

Exceptions

LivescoreAPIError

Custom exception for Livescore API errors.

Classes

APIEndpoint	Enumeration of Livescore API endpoints.
HistoricalMatch	A completed historical match with scores and outcomes.
LivescoreClient	Client for interacting with the Livescore API.
Match	Represents a soccer match.
MatchOutcome	Match outcomes (betting results) at different periods.
MatchScores	Match scores at different periods.
MatchStatistics	Match statistics from the API.
Odds	Represents betting odds for a match.
Team	Represents a soccer team.
TeamPerformanceStats	Detailed team performance statistics from recent matches.

Module Contents

class slickbet.api.APIEndpoint

Bases: str, enum.Enum

Enumeration of Livescore API endpoints.

COMPETITIONS_LIST = 'competitions/list.json'

COUNTRIES_LIST = 'countries/list.json'

FIXTURES_LIST = 'fixtures/list.json'

FIXTURES_MATCHES = 'fixtures/matches.json'

LEAGUES_TABLE = 'leagues/table.json'

MATCHES_HISTORY = 'matches/history.json'

MATCHES_STATS = 'matches/stats.json'

TEAMS_HEAD2HEAD = 'teams/head2head.json'

TEAMS_MATCHES = 'teams/matches.json'

class slickbet.api.HistoricalMatch

A completed historical match with scores and outcomes.

Per https://live-score-api.com/documentation/reference/15/football_data_history_matches

property away_score: int | None

Get away team final score.

away_team: Team

competition: str

competition_id: str

country: str | None

date: datetime.datetime

fixture_id: str | None

property home_score: int | None

Get home team final score.

home_team: Team

id: str

location: str | None = None

outcomes: MatchOutcome

pre_odds: Odds | None = None

property result: str | None

‘H’ (home win), ‘A’ (away win), ‘D’ (draw).

Type:

Get match result

round: str | None = None

scores: MatchScores

status: str

exception slickbet.api.LivescoreAPIError

Bases: Exception

Custom exception for Livescore API errors.

class slickbet.api.LivescoreClient(api_key: str | None = None, api_secret: str | None = None, cache_dir: str | pathlib.Path | None = None, cache_only: bool = False)

Client for interacting with the Livescore API.

Uses LIVESCORE_API_KEY and LIVESCORE_API_SECRET environment variables.

BASE_URL = 'https://livescore-api.com/api-client'

CUP_TO_LEAGUE_MAPPING

api_key

api_secret

cache: slickbet.cache.ApiCache | None

cache_only

enrich_match_with_stats(match: Match) → Match

Enrich a match object with additional statistics.

Parameters:

match (Match) – The match to enrich

Returns:

Match – Match with additional stats (form, standings, H2H, performance)

get_competitions(country_id: str | None = None) → list[dict[str, Any]]

Get list of available competitions.

Parameters:

country_id (str or None, optional) – Optional country ID to filter competitions

Returns:

list[dict[str, Any]] – List of competition dictionaries with id, name, country

get_countries() → list[dict[str, Any]]

Get list of available countries.

Returns:

list[dict[str, Any]] – List of country dictionaries with id and name

get_fixtures_by_date(date: datetime.datetime, competition_id: str | None = None, fetch_all_pages: bool = True) → list[Match]

Get all fixtures for a specific date.

Parameters:

• date (datetime) – The date to fetch fixtures for

• competition_id (str or None, optional) – Optional competition ID to filter by

• fetch_all_pages (bool, optional) – Whether to fetch all pages (default: True)

Returns:

list[Match] – List of Match objects

get_fixtures_list(date: datetime.datetime | None = None, competition_ids: list[str] | None = None, country_id: str | None = None, fetch_all_pages: bool = True) → list[Match]

Get fixtures using the list endpoint with competition_id and country_id filtering.

This endpoint is more efficient for filtering by competition/country as it provides these fields directly, avoiding the need for name-based heuristics.

Parameters:

• date (datetime or None, optional) – The date to fetch fixtures for (defaults to tomorrow)

• competition_ids (list[str] or None, optional) – List of competition IDs to filter by

• country_id (str or None, optional) – Country ID to filter by

• fetch_all_pages (bool, optional) – Whether to fetch all pages (default: True)

Returns:

list[Match] – List of Match objects

get_head_to_head(home_team_id: str, away_team_id: str, limit: int = 5) → dict

Get head-to-head statistics between two teams.

Parameters:

• home_team_id (str) – Home team ID

• away_team_id (str) – Away team ID

• limit (int, optional) – Number of recent H2H matches to consider

Returns:

dict – Dictionary with H2H statistics

get_history(competition_id: str | None = None, team_id: str | None = None, from_date: datetime.datetime | None = None, to_date: datetime.datetime | None = None, page: int = 1) → list[HistoricalMatch]

Get historical match data.

Per https://live-score-api.com/documentation/reference/15/football_data_history_matches

Parameters:

• competition_id (str or None, optional) – Filter by competition (comma-separated for multiple)

• team_id (str or None, optional) – Filter by team (comma-separated for multiple)

• from_date (datetime or None, optional) – Get matches from this date onwards

• to_date (datetime or None, optional) – Get matches until this date

• page (int, optional) – Page number for pagination

Returns:

list[HistoricalMatch] – List of HistoricalMatch objects

get_match_statistics(match_id: str) → MatchStatistics

Get statistics for a live or completed match.

Per https://live-score-api.com/documentation/reference/23/match-statistics Statistics are only available after the match has started.

Parameters:

match_id (str) – The match ID

Returns:

MatchStatistics – MatchStatistics object with available stats

get_team_form(team_id: str, limit: int = 5) → str

Get recent form for a team (last N matches).

Parameters:

• team_id (str) – The team ID

• limit (int, optional) – Number of recent matches to consider

Returns:

str – Form string like “WWDLW” (W=win, D=draw, L=loss)

get_team_history(team_id: str, limit: int = 10) → list[HistoricalMatch]

Get recent match history for a specific team.

Parameters:

• team_id (str) – The team ID

• limit (int, optional) – Maximum number of matches to return

Returns:

list[HistoricalMatch] – List of HistoricalMatch objects (most recent first)

get_team_performance_stats(team_id: str, num_matches: int = 10, verbose: bool = False) → TeamPerformanceStats

Calculate detailed performance statistics for a team from recent matches.

This provides goal-based metrics that improve prediction accuracy: - Goals scored/conceded per game (attack/defense strength) - Clean sheet rate (defensive solidity) - Home/Away specific win rates - Points per game - Match statistics averages (possession, corners, attacks, shots on target)

Parameters:

• team_id (str) – The team ID

• num_matches (int, optional) – Number of recent matches to analyze

• verbose (bool, optional) – Print debug info about match-statistics availability

Returns:

TeamPerformanceStats – TeamPerformanceStats with calculated metrics

get_team_standings(competition_id: str) → dict[str, int]

Get team standings/positions for a competition.

Parameters:

competition_id (str) – The competition/league ID

Returns:

dict[str, int] – Dictionary mapping team ID to position

get_tomorrow_fixtures() → list[Match]

Get all fixtures scheduled for tomorrow.

Returns:

list[Match] – List of Match objects for tomorrow’s games

session

class slickbet.api.Match

Represents a soccer match.

away_form: str | None = None

away_performance: TeamPerformanceStats | None = None

away_position: int | None = None

away_score: int | None = None

away_team: Team

competition: str

competition_id: str

country: str

head_to_head: dict | None = None

home_form: str | None = None

home_performance: TeamPerformanceStats | None = None

home_position: int | None = None

home_score: int | None = None

home_team: Team

id: str

kickoff_time: datetime.datetime

pre_odds: Odds | None = None

statistics: MatchStatistics | None = None

status: str

class slickbet.api.MatchOutcome

Match outcomes (betting results) at different periods.

Values are “1” (home win), “X” (draw), or “2” (away win).

extra_time: str | None = None

full_time: str | None = None

half_time: str | None = None

penalties: str | None = None

class slickbet.api.MatchScores

Match scores at different periods.

extra_time: str | None = None

final: str | None = None

property final_tuple: tuple[int, int] | None

Get final score as (home, away) tuple.

full_time: str | None = None

half_time: str | None = None

parse_score(score_str: str | None) → tuple[int, int] | None

Parse score string to (home, away) tuple.

Parameters:

score_str (str or None) – Score like "2 - 1".

Returns:

tuple[int, int] or None – (home, away) goals, or None if unparseable.

penalties: str | None = None

class slickbet.api.MatchStatistics

Match statistics from the API.

Per https://live-score-api.com/documentation/reference/23/match-statistics Statistics are only available for live/completed matches, not fixtures. Values are “home:away” format (e.g., “48:52” for possession).

attacks: tuple[int, int] | None = None

static calculate_xg_estimate(shots_on_target: int, shots_off_target: int, dangerous_attacks: int, attacks: int, possession: float | None = None) → float

Calculate estimated xG (Expected Goals) using a model-based approach.

Based on Expected Goals principles from: https://en.wikipedia.org/wiki/Expected_goals

The model assigns probabilities to goal-scoring opportunities based on: 1. Shot quality (on target vs off target) 2. Chance quality (dangerous attacks indicate high-probability chances) 3. Contextual factors (possession, total attacks)

Model inputs (as per Wikipedia): - Shot location/quality: inferred from shots on target (higher xG) - Phase of play: inferred from dangerous attacks (high-quality chances) - Contextual factors: possession and attack volume

Parameters:

• shots_on_target (int) – Number of shots on target (higher probability of goal)

• shots_off_target (int) – Number of shots off target (lower probability)

• dangerous_attacks (int) – Number of dangerous attacks (high-quality chances)

• attacks (int) – Total number of attacks (context factor)

• possession (float or None, optional) – Possession percentage (0-100), used to adjust shot quality

Returns:

float – Estimated xG value (sum of shot probabilities)

corners: tuple[int, int] | None = None

dangerous_attacks: tuple[int, int] | None = None

expected_goals: tuple[float, float] | None = None

fouls: tuple[int, int] | None = None

has_data() → bool

Check if this MatchStatistics object has any meaningful data.

Returns:

bool – True if at least one statistic field has data

offsides: tuple[int, int] | None = None

static parse_float_stat(value: str | None) → tuple[float, float] | None

Parse home:away format to a float tuple (for xG).

Parameters:

value (str or None) – Stat string like "1.2:0.8".

Returns:

tuple[float, float] or None – (home, away) values, or None if unparseable.

static parse_stat(value: str | None) → tuple[int, int] | None

Parse home:away format to an integer tuple.

Parameters:

value (str or None) – Stat string like "48:52".

Returns:

tuple[int, int] or None – (home, away) values, or None if unparseable.

possession: tuple[int, int] | None = None

red_cards: tuple[int, int] | None = None

saves: tuple[int, int] | None = None

shots_off_target: tuple[int, int] | None = None

shots_on_target: tuple[int, int] | None = None

yellow_cards: tuple[int, int] | None = None

class slickbet.api.Odds

Represents betting odds for a match.

away_win: float | None = None

draw: float | None = None

property has_odds: bool

Check if any odds are available.

home_win: float | None = None

implied_probability(outcome: str) → float | None

Calculate implied probability from odds.

Parameters:

outcome (str) – “home”, “draw”, or “away”

Returns:

float or None – Implied probability (0-1) or None if odds not available

class slickbet.api.Team

Represents a soccer team.

country: str | None = None

id: str

name: str

class slickbet.api.TeamPerformanceStats

Detailed team performance statistics from recent matches. Used to improve betting predictions with goal-based metrics.

Based on: https://live-score-api.com/documentation/reference/27/getting-teams-last-matches

avg_attacks: float = 0.0

avg_cards: float = 0.0

avg_corners: float = 0.0

avg_dangerous_attacks: float = 0.0

avg_expected_goal_difference: float = 0.0

avg_expected_goals: float = 0.0

avg_expected_goals_against: float = 0.0

avg_possession: float = 0.0

avg_red_cards: float = 0.0

avg_saves: float = 0.0

avg_shots_off_target: float = 0.0

avg_shots_on_target: float = 0.0

avg_yellow_cards: float = 0.0

away_games: int = 0

away_win_rate: float = 0.0

away_wins: int = 0

clean_sheet_rate: float = 0.0

clean_sheets: int = 0

collapses: int = 0

comeback_rate: float = 0.0

comebacks: int = 0

draws: int = 0

games_scored: int = 0

goal_conversion_rate: float = 0.0

goal_difference: int = 0

goals_conceded: int = 0

goals_conceded_per_game: float = 0.0

goals_per_game: float = 0.0

goals_scored: int = 0

home_games: int = 0

home_win_rate: float = 0.0

home_wins: int = 0

ht_draws: int = 0

ht_lead_rate: float = 0.0

ht_losses: int = 0

ht_wins: int = 0

losses: int = 0

matches_analyzed: int = 0

matches_with_attacks: int = 0

matches_with_dangerous_attacks: int = 0

matches_with_shots: int = 0

matches_with_stats: int = 0

points_per_game: float = 0.0

reliability_score: float = 1.0

scoring_rate: float = 0.0

shot_accuracy: float = 0.0

team_id: str

total_attacks: int = 0

total_cards: int = 0

total_corners: int = 0

total_dangerous_attacks: int = 0

total_expected_goals: float = 0.0

total_expected_goals_against: float = 0.0

total_points: int = 0

total_possession: float = 0.0

total_red_cards: int = 0

total_saves: int = 0

total_shots_off_target: int = 0

total_shots_on_target: int = 0

total_yellow_cards: int = 0

win_rate: float = 0.0

wins: int = 0