Api V2 Migration

EPGOAT Documentation - AI Reference (Educational)

TheSportsDB API v2 Migration Guide

Status: Reference Last Updated: 2025-11-02 Related Docs: API Integration, EPG Generation Guide Code Location: backend/epgoat/services/tv_schedule_client.py, backend/epgoat/services/league_cache.py, backend/epgoat/refresh_event_db_v2.py

Overview

This migration dramatically improves API efficiency by using TheSportsDB's v2 endpoints:

API Call Reduction

  • OLD Approach: 30+ API calls (10 leagues × 3 days)
  • NEW Approach: 3 API calls (1 per day)
  • Savings: ~90% reduction in API usage

New API Endpoints

1. All Leagues (/api/v2/json/all/leagues)

Returns comprehensive list of ALL leagues with IDs.

Usage: Cache weekly, use for league ID lookups

Example:

curl https://www.thesportsdb.com/api/v2/json/all/leagues

2. TV Schedule (/api/v2/json/filter/tv/day/{date})

Returns ALL televised events for a specific date.

Key Benefits: - Single call gets all events across all sports - Includes channel information (strChannel, idChannel) - Channel logos included - Precise timestamps

Example:

curl https://www.thesportsdb.com/api/v2/json/filter/tv/day/2025-10-24

Response Fields:

{
  "filter": [
    {
      "id": "821504",
      "idEvent": "2140080",
      "strSport": "Basketball",
      "strEvent": "Dallas Mavericks vs San Antonio Spurs",
      "strChannel": "NBA League Pass",
      "idChannel": "4894",
      "strLogo": "https://r2.thesportsdb.com/images/media/channel/logo/NBA_League_Pass.png",
      "strSeason": "2024-2025",
      "strTime": "23:30:00",
      "dateEvent": "2024-10-24",
      "strTimeStamp": "2024-10-24 23:30:00"
    }
  ]
}

3. Event Details (/api/v2/json/lookup/event/{idEvent})

Returns comprehensive event details using idEvent from TV schedule.

Example:

curl https://www.thesportsdb.com/api/v2/json/lookup/event/2140080

Response Fields:

{
  "lookup": [
    {
      "idEvent": "2140080",
      "strEvent": "Dallas Mavericks vs San Antonio Spurs",
      "strHomeTeam": "Dallas Mavericks",
      "strAwayTeam": "San Antonio Spurs",
      "strHomeTeamBadge": "https://r2.thesportsdb.com/images/media/team/badge/...",
      "strAwayTeamBadge": "https://r2.thesportsdb.com/images/media/team/badge/...",
      "strVenue": "American Airlines Center",
      "strTimestamp": "2024-10-24T23:30:00",
      "strTimeLocal": "18:30:00",
      "intHomeScore": "120",
      "intAwayScore": "109",
      "strPoster": "https://...",
      "strThumb": "https://...",
      "strVideo": "https://www.youtube.com/watch?v=...",
      "strStatus": "FT"
    }
  ]
}

New Modules

1. league_cache.py

Caches all league data for fast ID lookups.

Usage:

from league_cache import LeagueCache

cache = LeagueCache()
league_id = cache.get_league_id("NBA")  # Returns "4387"

Refresh:

python refresh_leagues.py --api-key YOUR_KEY

Schedule: Weekly refresh (Sunday 3 AM)

0 3 * * 0 cd /path/to/epgoat && python backend/epgoat/refresh_leagues.py

2. tv_schedule_client.py

Client for TV schedule and event detail APIs.

Usage:

from tv_schedule_client import TVScheduleClient

client = TVScheduleClient(api_key="YOUR_KEY")

# Get all TV events for a date
tv_events = client.get_tv_schedule("2025-10-24")

# Get detailed event info
details = client.get_event_details("2140080")

# Match event by channel and teams
event = client.match_event_by_channel(
    target_date="2025-10-24",
    channel_name="NBA League Pass",
    team1="Lakers",
    team2="Celtics"
)

3. backend/epgoat/utilities/refresh_event_db_v2.py

Improved event database refresh using TV schedule API.

Usage:

# Basic refresh (3 days, minimal API calls)
python refresh_event_db_v2.py

# With detailed event info (more API calls, richer data)
python refresh_event_db_v2.py --fetch-details

# Custom days ahead
python refresh_event_db_v2.py --days 5

Schedule: Twice daily

0 6 * * * python /path/to/refresh_event_db_v2.py
0 18 * * * python /path/to/refresh_event_db_v2.py

Migration Steps

1. Refresh League Cache

python backend/epgoat/refresh_leagues.py --verbose

This downloads ALL league IDs (one-time, then weekly).

2. Refresh Event Database

python backend/epgoat/refresh_event_db_v2.py --verbose

This downloads TV schedules (3 API calls for 3 days).

3. Update EPG Generation

The existing backend/epgoat/application/epg_generator.py can use the new database automatically.

4. Schedule Cron Jobs

# Edit crontab
crontab -e

# Add these lines:
# Refresh leagues weekly (Sunday 3 AM)
0 3 * * 0 cd /path/to/epgoat && python backend/epgoat/refresh_leagues.py >> /var/log/epgoat-leagues.log 2>&1

# Refresh events twice daily (6 AM and 6 PM)
0 6,18 * * * cd /path/to/epgoat && python backend/epgoat/refresh_event_db_v2.py >> /var/log/epgoat-events.log 2>&1

API Call Comparison

OLD Approach (v1 API)

For 3 days with 10 leagues:

3 days × 10 leagues = 30 API calls
Plus individual event lookups = 30+ total

NEW Approach (v2 API)

For 3 days:

3 days × 1 call per day = 3 API calls
Plus 1 weekly league cache refresh = ~0.14 calls/day
Total: ~3.14 calls/day

Efficiency Gain: 90% reduction

Benefits

  1. Fewer API Calls: 90% reduction in API usage
  2. Better Data: TV schedule includes channel information
  3. More Reliable: Single source of truth for TV events
  4. Faster: Local database eliminates API calls during EPG generation
  5. Comprehensive: Gets ALL TV events, not just specific leagues

Backwards Compatibility

The old api_client.py and refresh_event_db.py remain available for: - Non-TV events - Fallback scenarios - Testing and comparison

Testing

# Test league cache
python backend/epgoat/refresh_leagues.py --verbose

# Test TV schedule (without details - minimal API calls)
python backend/epgoat/refresh_event_db_v2.py --days 1 --verbose

# Test with details (more API calls, richer data)
python backend/epgoat/refresh_event_db_v2.py --days 1 --fetch-details --verbose

Monitoring

Check API usage:

# View logs
tail -f /var/log/epgoat-events.log

# Count API calls in logs
grep "API request" /var/log/epgoat-events.log | wc -l

Troubleshooting

No events found

  • Check if API key is set: echo $THESPORTSDB_API_KEY
  • Try with --verbose to see detailed errors
  • Verify date format: YYYY-MM-DD

Database not refreshing

  • Check file permissions on dist/events_db.json
  • Verify cron job is running: crontab -l
  • Check logs for errors

Rate limiting

  • Free tier: 30 requests/minute
  • Paid tier: 100 requests/minute
  • V2 approach stays well under limits

Questions?

See also: - TheSportsDB API Documentation - API Integration