TheSportsDB

Implementation notes

When to use TheSportsDB

TheSportsDB is a crowd-sourced sports database covering leagues, teams, players, fixtures, and results across football, basketball, American football, motorsport, and dozens of smaller sports, together with a large library of team badges, jerseys, and stadium photography. The imagery is the real differentiator — free sports APIs that hand you a usable badge for every club in a mid-table European league basically do not exist otherwise. Use it for fixture widgets, fantasy-league side projects, sports trivia apps, and anything that needs broad multi-sport breadth rather than deep single-league precision. Access is a two-tier model: a shared test key for development, and a Patreon-backed key at a few dollars a month for anything real. Against football-data.org it trades accuracy and live-match rigour for breadth and assets; against paid commercial feeds it is not in the same category and should not carry anything with money attached to it.

Common pitfalls

• The test key 3 that appears in every tutorial is a single globally shared credential. Everyone's traffic lands in the same bucket, so latency swings wildly, 429s arrive at random times of day, and endpoints get disabled for the test key without notice. It is fine while you build; shipping it makes your uptime a function of how many strangers are using it that hour.
• v1 and v2 are different APIs, not versions of one design. v2 moved the key into an X-API-KEY header, renamed endpoints, and changed response envelopes. Search results still surface v1 examples heavily, so copy-pasted snippets fail in confusing ways against a v2 key. Pick a version and read only that version's documentation.
• Team and league naming is crowd-sourced and inconsistent across sports and countries. The same club shows up as Manchester United, Man United, and Manchester Utd depending on which league record you read, and there is no canonical alias table. Join on the numeric idTeam wherever possible, and normalize names once at ingest when you cannot.
• Image URLs point at contributor-uploaded assets that occasionally disappear. A badge URL that worked last month can 404 after a contributor replaces or removes the file, and there is no notification. Do not hotlink into production UI — mirror the images you actually display to your own storage and refresh them on a schedule.

Quick start (bash)

# test key 3 is shared globally and unstable - development only, never ship it
curl -s 'https://www.thesportsdb.com/api/v1/json/3/searchteams.php?t=Arsenal' | jq '.teams[0] | {idTeam, strTeam, strBadge}'
# join on idTeam, not on the name strings - naming is inconsistent across leagues
curl -s 'https://www.thesportsdb.com/api/v1/json/3/lookupteam.php?id=133604' | jq '.teams[0].strStadium'

Embed this badge

Add a live status badge to your README, docs, or website.

Markdown

[![TheSportsDB Status](https://api.freeapi.watch/badge/thesportsdb.svg)](https://freeapi.watch/thesportsdb)

HTML

<a href="https://freeapi.watch/thesportsdb"><img src="https://api.freeapi.watch/badge/thesportsdb.svg" alt="TheSportsDB Status"/></a>