@apicity/thesportsdb

v0.6.2

Published

a day ago

TheSportsDB V1 and V2 sports data API provider.

0High
0Medium
0Low

justintanner

thesportsdb sports scores leagues api sports-data apicity

@apicity/thesportsdb

TheSportsDB V1 and V2 sports data API provider.

Runtime dependencies:

zod@^4.4.3 — request schemas attached to endpoint methods as .schema; response schemas exported

Installation

npm install @apicity/thesportsdb
# or
pnpm add @apicity/thesportsdb

Quick Start

import { createTheSportsDB } from "@apicity/thesportsdb";

const thesportsdb = createTheSportsDB({ apiKey: process.env.THESPORTSDB_API_KEY });

V2 Authentication

V1 calls default to TheSportsDB's free 123 key in the URL path when apiKey is omitted. V2 is premium-only and sends the same apiKey in the X-API-KEY header; V2 methods throw locally if no key is configured.

const thesportsdb = createTheSportsDB({
  apiKey: process.env.THESPORTSDB_API_KEY!,
});

const teams = await thesportsdb.v2.search.team({
  teamName: "Manchester United",
});

For V1 premium calls, the same apiKey option is encoded into the path segment instead of a header:

const premiumV1 = createTheSportsDB({
  apiKey: process.env.THESPORTSDB_API_KEY!,
});

const broadcasts = await premiumV1.v1.eventstv({
  channel: "Peacock_Premium",
});

Operational Notes

All implemented TheSportsDB endpoints are read-only GET calls. The provider does not expose mutating endpoints.

The implemented API surface has no pagination parameters. Upstream responses use endpoint-specific wrapper arrays and documented result limits; empty and no-result wrappers remain representable as null or empty arrays.

Non-2xx responses throw TheSportsDBError with status and parsed body where possible. Rate-limit responses keep their upstream 429 status and body. V2 methods throw a local 401 before fetch when no apiKey is configured for X-API-KEY authentication.

Search Examples

TheSportsDB V1 uses the free 123 key by default. Pass apiKey only when you have a premium key.

import { createTheSportsDB } from "@apicity/thesportsdb";

const thesportsdb = createTheSportsDB();

const teams = await thesportsdb.v1.searchTeams({
  team: "Arsenal",
});

const events = await thesportsdb.v1.searchEvents({
  event: "Arsenal_vs_Chelsea",
  season: "2016-2017",
  date: "2015-04-26",
});

const filename = await thesportsdb.v1.searchFilename({
  filename: "English_Premier_League_2015-04-26_Arsenal_vs_Chelsea",
});

const players = await thesportsdb.v1.searchPlayers({
  player: "Danny Welbeck",
});

const venues = await thesportsdb.v1.searchVenues({
  venue: "Wembley",
});

No-result V1 searches preserve TheSportsDB's nullable wrapper arrays, such as { teams: null } or { player: null }.

Player Lookup Examples

Player lookup, honours, former-team, milestone, contract, result, and statistics routes use TheSportsDB's numeric player id.

import { createTheSportsDB } from "@apicity/thesportsdb";

const thesportsdb = createTheSportsDB({
  apiKey: process.env.THESPORTSDB_API_KEY,
});

const player = await thesportsdb.v1.lookupplayer({ idPlayer: 34145937 });
const honours = await thesportsdb.v1.lookuphonours({ idPlayer: 34147178 });
const stats = await thesportsdb.v1.lookupplayerstats({ idPlayer: 34146304 });

No-result responses preserve TheSportsDB's wrapper key with a null value, for example { players: null }.

V1 uses an API key in the URL path. The provider defaults to the public free key 123; pass apiKey to use your own key. V2 uses the same apiKey option as an X-API-KEY header and is available under thesportsdb.v2.

const league = await thesportsdb.v1.lookup.league({ idLeague: 4328 });
const table = await thesportsdb.v1.lookup.table({
  idLeague: 4328,
  season: "2020-2021",
});
const team = await thesportsdb.v1.lookup.team({ idTeam: 133604 });

const nextLeagueEvents = await thesportsdb.v2.schedule.next.league({
  idLeague: 4328,
});
const liveSoccer = await thesportsdb.v2.livescore.bySport({
  sport: "soccer",
});

V2 is premium-only and sends the same apiKey as an X-API-KEY header. V2 lookup method names mirror the path segments:

const player = await thesportsdb.v2.lookup.player({ idPlayer: 34172575 });
const lineup = await thesportsdb.v2.lookup.eventLineup({
  idEvent: 1937584,
});
const highlights = await thesportsdb.v2.lookup.eventHighlights({
  idEvent: 2044892,
});

API Reference

84 endpoints across 40 groups. Each method mirrors an upstream URL path.

all

GET https://www.thesportsdb.com/api/v2/json/all/countries

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@apicity/thesportsdb

Installation

Quick Start

V2 Authentication

Operational Notes

Search Examples

Player Lookup Examples

API Reference

all

allCountries

allLeagues

allSports

eventResults

eventsday

eventshighlights

eventslast

eventsnext

eventsnextleague

eventspastleague

eventsseason

eventstv

filter

list

livescore

lookup

lookupAllPlayers

lookupcontracts

lookupEvent

lookupEventStats

lookupformerteams

lookuphonours

lookupLineup

lookupmilestones

lookupplayer

lookupplayerstats

lookupTimeline

lookupTv

playerresults

schedule

search

searchAllLeagues

searchAllSeasons

searchAllTeams

searchEvents

searchFilename

searchPlayers

searchTeams

searchVenues

License