TheSportsDB Integration

The panel integrates with TheSportsDB (TSDB) to enrich EPG template variables with real-world sports data: venue information, live scores, broadcast networks, team badges, jerseys, banners, league standings, team records, and form streaks.

Overview

When enabled, resolveTemplateVars() calls tsdbEnrichEvent() at the end of variable resolution. This function:

1. Searches TSDB for both teams by name (fuzzy matching)
2. Looks up full team details (venue, badges, jerseys, banners)
3. Searches for matching events (scores, broadcast info)
4. Looks up league standings for records, position, points, and form
5. Merges all found data into the template variable set

All results are cached in the tsdb_cache database table to minimize API calls and stay within rate limits.

Requirements

• TheSportsDB Premium Account — Patreon subscription for V2 API access
• API Key — obtained from your TSDB Patreon dashboard
• Rate Limit — 100 requests/minute for premium accounts

Setup

1. Navigate to Global Config (/config_dazn)
2. Scroll to the TheSportsDB Integration section
3. Check Enable TheSportsDB
4. Enter your API Key
5. Click Update

The panel auto-creates the tsdb_cache table and settings columns on first access (no manual migration needed).

API Architecture

The integration uses both TSDB V2 (premium) and V1 (legacy) endpoints:

V2 API (Premium)

Endpoint	Purpose
GET /api/v2/json/search/team/{name}	Search team by name
GET /api/v2/json/lookup/team/{id}	Full team details

Authentication: X-API-KEY: <key> header.

V1 API (Legacy)

Endpoint	Purpose
GET /api/v1/json/{key}/searchteams.php?t={name}	Fallback team search
GET /api/v1/json/{key}/searchevents.php?e={query}&d={date}	Event search
GET /api/v1/json/{key}/lookuptable.php?l={id}&s={season}	League standings
GET /api/v1/json/{key}/eventstv.php?d={date}	TV schedule

Authentication: API key in URL path.

Fuzzy Team Matching

DAZN event titles don't always match TSDB team names exactly. The integration uses a multi-strategy approach:

1. V2 search — primary search via premium endpoint
2. V1 fallback — if V2 returns no results, falls back to V1 search
3. Normalized comparison — strips all non-alphanumeric characters and compares lowercase strings
4. Substring matching — checks if the search term appears within candidate names (or vice versa)
5. Levenshtein distance — for remaining candidates, calculates edit distance relative to string length, accepting matches below a configurable threshold

This handles cases like:

DAZN Title	TSDB Name	Match Method
Bayern Munich	Bayern München	Normalized
Man Utd	Manchester United	Substring
Internazionale	Inter Milan	Levenshtein

Caching

All API responses are cached in the tsdb_cache table:

Cache Type	Default TTL	Description
Team search	24 hours	Team search results by name
Team lookup	24 hours	Full team details by TSDB ID
League table	6 hours	Standings/records by league + season
Event search	6 hours	Event match results
TV schedule	6 hours	Broadcast info by date

Cache entries are stored as JSON with an expires_at Unix timestamp. Expired entries are refreshed on next access. The cache key is a combination of the endpoint and query parameters.

Variables Populated

When TSDB enrichment succeeds, these template variables are populated:

From Team Lookup

Variable	TSDB Field	Example
{venue}	strStadium	Signal Iduna Park
{venue_city}	strStadiumLocation	Dortmund
{venue_capacity}	intStadiumCapacity	81,365
{team1_badge}	strBadge	Badge image URL
{team2_badge}	strBadge	Badge image URL
{team1_jersey}	strJersey	Jersey image URL
{team2_jersey}	strJersey	Jersey image URL
{team1_banner}	strBanner	Banner image URL
{team2_banner}	strBanner	Banner image URL

From Event Search

Variable	TSDB Field	Example
{home_score}	intHomeScore	2
{away_score}	intAwayScore	1
{score}	computed	2-1

From TV Schedule

Variable	TSDB Field	Example
{broadcast}	strChannel	DAZN
{broadcast_country}	strCountry	Italy

From League Standings

Variable	TSDB Field	Example
{team1_record}	win-draw-loss	22-4-4
{team2_record}	win-draw-loss	20-5-5
{home_team_record}	(alias for team1)	22-4-4
{away_team_record}	(alias for team2)	20-5-5
{team1_streak}	strForm	W3
{team2_streak}	strForm	L1
{team1_position}	table index	1
{team2_position}	table index	4
{team1_points}	total	70
{team2_points}	total	65
{playoff_seed}	(home team position)	1
{games_back}	leader total − team total	5

Database Tables

tsdb_cache

Auto-created on first access:

Column	Type	Description
id	INT AUTO_INCREMENT	Primary key
cache_key	VARCHAR(255) UNIQUE	Cache lookup key
cache_value	MEDIUMTEXT	JSON-encoded response data
expires_at	INT	Unix timestamp expiry
created_at	TIMESTAMP	Creation time

Settings Columns

Added to the settings table:

Column	Type	Default	Description
tsdb_api_key	VARCHAR(255)	''	TheSportsDB API key
tsdb_enabled	TINYINT	0	Enable/disable enrichment

Functions Reference

Function	Description
tsdbEnrichEvent($ev)	Main orchestrator — takes a schedule event array, returns enriched variables
tsdbSearchTeam($name)	Search for a team by name with V2→V1 fallback
tsdbFindBestTeamMatch($candidates, $query)	Fuzzy match best team from candidates
tsdbLookupTeam($id)	Full team details by TSDB ID
tsdbSearchEvent($team1, $team2, $date)	Find matching event for scores
tsdbGetTvSchedule($date)	Get TV schedule for broadcast info
tsdbLookupTable($leagueId, $season)	League standings
tsdbFindTeamInTable($teamName, $teamData, $table)	Find team row in standings by ID or name
tsdbTablePosition($teamRow, $table)	Get 1-based position in standings
tsdbFormToStreak($form)	Convert form string (e.g. "WWDLW") to streak (e.g. "W1")
tsdbRequest($endpoint, $params, $version)	Low-level API request with caching
tsdbCacheGet($key)	Read from cache
tsdbCacheSet($key, $value, $ttl)	Write to cache
migrateTsdbCache()	Create tsdb_cache table if not exists
migrateTsdbSettings()	Add TSDB columns to settings if not exists