API docs by Redocly

TheSportsDB API (v1 · measured 5 Oct 2026)

Download OpenAPI specification:

Terms of Service

TheSportsDB is an open, crowd-sourced database of sports data and artwork. v1 works with the free keys and with premium keys.

GET https://www.thesportsdb.com/api/v1/json/{apiKey}/{endpoint}.php?{parameters}
  • Keys: 123 is the free key for development and testing; the older 3 also works, with the same limits. Premium keys get full results. The key is part of the URL, so treat v1 URLs as secrets.
  • Free limits: each endpoint's description gives the records returned to the free and premium keys, measured on 5 Oct 2026, next to the documented limits.
  • Responses: one JSON object with one key holding an array of records. The key depends on the endpoint, and each endpoint lists its key. The records' values are strings or null.
  • No results: the key with null, or an empty body. A rejected parameter comes back as text in place of the records, e.g. {"seasons":"Invalid League ID passed"}.
  • Times: dateEvent, strTime and strTimestamp are UTC.
  • Rate limit: 30 requests a minute on the free keys, 100 premium, 120 business. Over the limit: HTTP 429; wait a minute.

The guides cover these in detail, with recipes for common tasks.

Search

Find records by name.

Search teams by name

The free keys only find the exact team (1 record).

Records measured 5 Oct 2026: free key 1, premium key 15.

Documented limit: 1 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
t
required
string
Example: t=Arsenal

Team name. Spaces as %20 or _.

Responses

Response samples

Content type
application/json
{
  • "teams": [
    ]
}

Search events by name

Pass at most one of s and d.

Records measured 5 Oct 2026: free key 1, premium key 10.

Documented limit: 1 / 10 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
e
required
string
Example: e=Arsenal_vs_Chelsea

Event name, Home vs Away.

s
string
Example: s=2016-2017

Narrow to a season.

d
string <date>
Example: d=2015-04-26

Narrow to a date, YYYY-MM-DD.

f
string
Example: f=English_Premier_League_2015-04-26_Arsenal_vs_Chelsea

Alternatively, an event filename (same as searchfilename.php).

Responses

Response samples

Content type
application/json
{}

Search events by filename

Records measured 5 Oct 2026: free key 1, premium key 1.

Documented limit: 1 / 10 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
e
required
string
Example: e=English_Premier_League_2015-04-26_Arsenal_vs_Chelsea

Event filename: {League} {YYYY-MM-DD} {Home} vs {Away}.

s
string
Example: s=2014-2015

Narrow to a season.

Responses

Response samples

Content type
application/json
{}

Search players by name

Returns summary fields plus a relevance score.

Records measured 5 Oct 2026: free key 1, premium key 1.

Documented limit: 1 / 10 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
p
required
string
Example: p=Danny_Welbeck

Player name.

Responses

Response samples

Content type
application/json
{}

Search venues by name

Records measured 5 Oct 2026: free key 1, premium key 2.

Documented limit: 1 / 10 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
v
required
string
Example: v=Wembley

Venue name.

Responses

Response samples

Content type
application/json
{}

Lookup

Fetch records by id, and the details attached to a team, player or event.

Look up a league

Records measured 5 Oct 2026: free key 1, premium key 1.

Documented limit: 1 / 1 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=4328

The league id.

Responses

Response samples

Content type
application/json
{
  • "leagues": [
    ]
}

League table (standings)

Only some leagues have tables, mostly featured soccer leagues. Omit s for the current season. There is no v2 equivalent: use this endpoint with a premium key.

Records measured 5 Oct 2026: free key 5, premium key 20.

Documented limit: 5 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
l
required
integer
Example: l=4328

The league id.

s
string
Example: s=2026-2027

A season name, e.g. 2026-2027 (or 2026 for single-year leagues).

Responses

Response samples

Content type
application/json
{
  • "table": [
    ]
}

Look up a team

Records measured 5 Oct 2026: free key 1, premium key 1.

Documented limit: 1 / 1 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=133604

The team id.

Responses

Response samples

Content type
application/json
{
  • "teams": [
    ]
}

A team's kits

Records measured 5 Oct 2026: free key 2, premium key 18.

Documented limit: 2 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=133597

The team id.

Responses

Response samples

Content type
application/json
{}

Look up a player

Records measured 5 Oct 2026: free key 1, premium key 1.

Documented limit: 1 / 1 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=34145937

The player id.

Responses

Response samples

Content type
application/json
{}

A player's honours

Records measured 5 Oct 2026: free key 5, premium key 5.

Documented limit: 5 / 500 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=34147178

The player id.

Responses

Response samples

Content type
application/json
{}

A player's former teams

Records measured 5 Oct 2026: free key 5, premium key 6.

Documented limit: 5 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=34147178

The player id.

Responses

Response samples

Content type
application/json
{}

A player's milestones

Records measured 5 Oct 2026: free key 3, premium key 3.

Documented limit: 5 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=34161397

The player id.

Responses

Response samples

Content type
application/json
{}

A player's contracts

Records measured 5 Oct 2026: free key 1, premium key 1.

Documented limit: 1 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=34147178

The player id.

Responses

Response samples

Content type
application/json
{}

A player's results (individual sports)

For races, golf, fights and similar.

Records measured 5 Oct 2026: free key 5, premium key 24.

Documented limit: 5 / 500 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=34160573

The player id.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

A player's season statistics

One record per statistic per season.

Records measured 5 Oct 2026: free key 10, premium key 315.

Documented limit: 10 / 10000 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=34146304

The player id.

Responses

Response samples

Content type
application/json
{}

Look up an event

Records measured 5 Oct 2026: free key 1, premium key 1.

Documented limit: 1 / 1 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=441613

The event id.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ]
}

An event's results (individual sports)

Records measured 5 Oct 2026: free key 5, premium key 22.

Documented limit: 5 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=652890

The event id.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

An event's lineups

The old name lookuplineups.php returns 404.

Records measured 5 Oct 2026: free key 5, premium key 22.

Documented limit: 5 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=1032723

The event id.

Responses

Response samples

Content type
application/json
{}

An event's timeline

Goals, cards and substitutions.

Records measured 5 Oct 2026: free key 5, premium key 10.

Documented limit: 5 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=1032718

The event id.

Responses

Response samples

Content type
application/json
{
  • "timeline": [
    ]
}

An event's team statistics

Records measured 5 Oct 2026: free key 5, premium key 16.

Documented limit: 5 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=1032723

The event id.

Responses

Response samples

Content type
application/json
{
  • "eventstats": [
    ]
}

The channels showing an event

Records measured 5 Oct 2026: free key 2, premium key 13.

Documented limit: 2 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=2494052

The event id.

Responses

Response samples

Content type
application/json
{}

Look up a venue

Records measured 5 Oct 2026: free key 1, premium key 1.

Documented limit: 1 / 1 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=16163

The venue id.

Responses

Response samples

Content type
application/json
{}

Lists

Lists of leagues, seasons, teams and players.

All sports

Records measured 5 Oct 2026: free key 2, premium key 37.

Documented limit: 2 / 50 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

Responses

Response samples

Content type
application/json
{}

All countries

Name and 32 px flag only; v2 all/countries adds codes and more flag sizes.

Records measured 5 Oct 2026: free key 50, premium key 256.

Documented limit: 50 / 500 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

Responses

Response samples

Content type
application/json
{}

All leagues

Id, name and sport. strLeagueAlternate is included only with a premium key.

Records measured 5 Oct 2026: free key 5, premium key 1547.

Documented limit: 10 / 3000 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

Responses

Response samples

Content type
application/json
{
  • "leagues": [
    ]
}

Leagues in a country

Full league records. The record key really is countries.

Records measured 5 Oct 2026: free key 5, premium key 25.

Documented limit: 10 / 100 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
c
required
string
Example: c=England

Country name, as in all_countries.php.

s
string
Example: s=Soccer

Sport name.

Responses

Response samples

Content type
application/json
{}

A league's seasons

Season names only unless one of badge, poster or description is set. The parameter is id; l= returns {"seasons":"Invalid League ID passed"}.

Records measured 5 Oct 2026: free key 5, premium key 35.

Documented limit: 5 / 500 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=4328

The league id.

badge
integer
Example: badge=1

1 to add strBadge.

poster
integer
Example: poster=1

1 to add strPoster.

description
integer
Example: description=1

1 to add strDescriptionEN.

Responses

Response samples

Content type
application/json
{
  • "seasons": [
    ]
}

Teams in a league, or of a sport in a country

Pass l, or s and c.

Records measured 5 Oct 2026: free key 10, premium key 20.

Documented limit: 10 / 3000 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
l
string
Example: l=English_Premier_League

League name (not id).

s
string
Example: s=Soccer

Sport name (with c).

c
string
Example: c=Spain

Country name (with s).

Responses

Response samples

Content type
application/json
{
  • "teams": [
    ]
}

A team's squad

Records measured 5 Oct 2026: free key 10, premium key 27.

Documented limit: 10 / 3000 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=133604

The team id.

Responses

Response samples

Content type
application/json
{
  • "player": [
    ]
}

Schedules

Fixtures and results. Times are UTC.

A team's next events

Free keys: home games only.

Records measured 5 Oct 2026: free key 1, premium key 10.

Documented limit: 1 / 10 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=133602

The team id.

Responses

Response samples

Content type
application/json
{}

A team's last results

Free keys: home games only. The record key is results, but the records are events.

Records measured 5 Oct 2026: free key 1, premium key 5.

Documented limit: 1 / 10 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=133602

The team id.

Responses

Response samples

Content type
application/json
{}

A league's next events

Records measured 5 Oct 2026: free key 1, premium key 20.

Documented limit: 1 / 20 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=4328

The league id.

Responses

Response samples

Content type
application/json
{}

A league's latest results

Records measured 5 Oct 2026: free key 1, premium key 15.

Documented limit: 1 / 20 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=4328

The league id.

Responses

Response samples

Content type
application/json
{}

Every event on a day

The day is a UTC date: evening games in the Americas appear on the next day. A day with no matching events returns {"events":null}.

Records measured 5 Oct 2026: free key 3, premium key 901.

Documented limit: 3 / 1500 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
d
required
string <date>
Example: d=2026-10-04

A day, YYYY-MM-DD. Events are filed under their UTC date.

s
string
Example: s=Ice_Hockey

Sport name.

l
string
Example: l=4328

League id or name.

Responses

Response samples

Content type
application/json
{}

A league's whole season

Fewer fields than a lookup (no descriptions, officials or spectators).

Records measured 5 Oct 2026: free key 5, premium key 380.

Documented limit: 15 / 3000 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=4328

The league id.

s
required
string
Example: s=2026-2027

Season name, from strCurrentSeason.

Responses

Response samples

Content type
application/json
{}

One round of a season

Returns the whole round. l= instead of id= returns {"events":"Invalid League ID or no round passed"}. With a premium key, filter v2 schedule/league/{id}/{season} by intRound instead.

Not in the official documentation. Answers the free keys; premium keys get HTTP 404.

Records measured 5 Oct 2026: free key 10, premium key HTTP 404.

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
id
required
integer
Example: id=4328

The league id.

r
required
integer
Example: r=1

Round (matchday) number.

s
required
string
Example: s=2026-2027

Season name.

Responses

Response samples

Content type
application/json
{}

TV

TV listings: which channels show which events.

TV listings

Use one form: d (optionally with s, or s and a), c, or id. a without s returns an empty body. For an event's channels use lookuptv.php.

Records measured 5 Oct 2026: free key 1, premium key 287.

Documented limit: 1 / 1500 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
d
string <date>
Example: d=2026-10-05

A day, YYYY-MM-DD.

s
string
Example: s=Ice_Hockey

Sport name (with d).

a
string
Example: a=Canada

Country of the channel (with d and s).

c
string
Example: c=TSN_1

Channel name (alone), e.g. TSN_1.

id
integer
Example: id=8631

Channel id, idChannel (alone). Not an event id.

Responses

Response samples

Content type
application/json
{}

Video

Highlight videos.

Events with highlight videos

The video URL is in strVideo. Premium results stop at the documented 50.

Records measured 5 Oct 2026: free key 2, premium key 50.

Documented limit: 2 / 50 (free / premium).

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
d
required
string <date>
Example: d=2026-10-04

A day, YYYY-MM-DD. Events are filed under their UTC date.

l
integer
Example: l=4328

League id.

s
string
Example: s=Soccer

Sport name.

Responses

Response samples

Content type
application/json
{}

Live scores

Games in progress.

Games in progress

The free keys get the full feed. l= (league) is ignored: every live game is returned. Entries can be stale; check updated. v2 livescore/... is the documented equivalent.

Not in the official documentation.

Records measured 5 Oct 2026: free key 19, premium key 19.

path Parameters
apiKey
required
string
Example: 123

Your API key. 123 is the free key for development and testing (3 also works, with the same limits). The key is in the URL, so treat v1 URLs as secrets and don't log them.

query Parameters
s
required
string
Example: s=Soccer

Sport name.

Responses

Response samples

Content type
application/json
{}