@apicity/openligadb

OpenLigaDB API provider for public soccer match data, metadata, standings, and scorers.

OpenLigaDB is a public read-only API. createOpenLigaDB() does not take credentials, and the provider does not send auth headers.

Runtime dependencies:

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

Installation

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

Quick Start

import { createOpenLigaDB } from "@apicity/openligadb";

const openligadb = createOpenLigaDB();

Matchdata Examples

OpenLigaDB is public and does not require an API key.

import { createOpenLigaDB } from "@apicity/openligadb";

const openligadb = createOpenLigaDB();

const match = await openligadb.getmatchdata.byId({ matchId: 68720 });

const season = await openligadb.getmatchdata.byLeagueSeason({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
});

The overloaded upstream /getmatchdata paths are exposed as explicit by* methods so team, group, season, and match-id routes cannot collide.

Next Match And Team Window Examples

The next/last shortcuts return one match. Team windows return recent and upcoming matches around today, controlled by past/future week counts:

const nextMatch = await openligadb.getnextmatchbyleagueshortcut({
  leagueShortcut: "bl1",
});

const recentAndUpcoming = await openligadb.getmatchesbyteam({
  teamFilterstring: "Bayern",
  weekCountPast: 4,
  weekCountFuture: 2,
});

Standings And Scorers Examples

League standings, group tables, and top scorers share the same leagueShortcut and leagueSeason request shape:

const standings = await openligadb.getbltable({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
});

const groupTable = await openligadb.getgrouptable({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
});

const topScorers = await openligadb.getgoalgetters({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
});

Catalog Discovery Flow

OpenLigaDB's public catalog endpoints work without credentials. A common flow is sports -> leagues -> groups, teams, and result metadata:

import { createOpenLigaDB } from "@apicity/openligadb";

const openligadb = createOpenLigaDB();

const sports = await openligadb.getavailablesports();
const leagues = await openligadb.getavailableleagues.bySeason({
  season: 2024,
});

const league = leagues.find((item) => item.leagueShortcut === "bl1");
if (league) {
  const groups = await openligadb.getavailablegroups({
    leagueShortcut: league.leagueShortcut!,
    leagueSeason: Number(league.leagueSeason),
  });
  const teams = await openligadb.getavailableteams({
    leagueShortcut: league.leagueShortcut!,
    leagueSeason: Number(league.leagueSeason),
  });
  const resultInfo = await openligadb.getresultinfos({
    leagueId: league.leagueId,
  });
}

All path-parameter methods expose request schemas via .schema, for example openligadb.getavailablegroups.schema.safeParse(input).

Errors And Scope

• OpenLigaDB's documented public surface is read-only. This package exposes GET helpers only and never sends auth headers.
• The public upstream docs do not document pagination parameters, rate-limit headers, or credential requirements for these routes, so this provider does not add client-side helpers for them.
• Non-2xx responses throw OpenLigaDBError with status and body. JSON error bodies stay as parsed objects, while text/plain bodies are preserved as strings so missing-match messages are not lost.
• Empty success bodies resolve to null; endpoint helpers with schemas expose request validation through .schema.safeParse(input).

API Reference

23 endpoints across 18 groups. Each method mirrors an upstream URL path.

getavailablegroups

GET https://api.openligadb.de/getavailablegroups/{leagueShortcut}/{leagueSeason}

Upstream docs ↗

const groups = await openligadb.getavailablegroups({ leagueShortcut: "bl1", leagueSeason: 2024 });

Source: packages/provider/openligadb/src/openligadb.ts

getavailableleagues

GET https://api.openligadb.de/getavailableleagues

Upstream docs ↗

const leagues = await openligadb.getavailableleagues();

Source: packages/provider/openligadb/src/openligadb.ts

GET https://api.openligadb.de/getavailableleagues/{season}

Upstream docs ↗

const leagues = await openligadb.getavailableleagues.bySeason({ season: 2024 });

Source: packages/provider/openligadb/src/openligadb.ts

getavailablesports

GET https://api.openligadb.de/getavailablesports

Upstream docs ↗

const sports = await openligadb.getavailablesports();

Source: packages/provider/openligadb/src/openligadb.ts

getavailableteams

GET https://api.openligadb.de/getavailableteams/{leagueShortcut}/{leagueSeason}

Upstream docs ↗

const teams = await openligadb.getavailableteams({ leagueShortcut: "bl1", leagueSeason: 2024 });

Source: packages/provider/openligadb/src/openligadb.ts

getbltable

GET https://api.openligadb.de/getbltable/{leagueShortcut}/{leagueSeason}

Upstream docs ↗

const res = await openligadb.getbltable({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
});

Source: packages/provider/openligadb/src/openligadb.ts

getcurrentgroup

GET https://api.openligadb.de/getcurrentgroup/{leagueShortcut}

Upstream docs ↗

const group = await openligadb.getcurrentgroup({ leagueShortcut: "bl1" });

Source: packages/provider/openligadb/src/openligadb.ts

getgoalgetters

GET https://api.openligadb.de/getgoalgetters/{leagueShortcut}/{leagueSeason}

Upstream docs ↗

const res = await openligadb.getgoalgetters({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
});

Source: packages/provider/openligadb/src/openligadb.ts

getgrouptable

GET https://api.openligadb.de/getgrouptable/{leagueShortcut}/{leagueSeason}

Upstream docs ↗

const res = await openligadb.getgrouptable({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
});

Source: packages/provider/openligadb/src/openligadb.ts

getlastchangedate

GET https://api.openligadb.de/getlastchangedate/{leagueShortcut}/{leagueSeason}/{groupOrderId}

Upstream docs ↗

const changedAt = await openligadb.getlastchangedate({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
  groupOrderId: 1,
});

Source: packages/provider/openligadb/src/openligadb.ts

getlastmatchbyleagueshortcut

GET https://api.openligadb.de/getlastmatchbyleagueshortcut/{leagueShortcut}

Upstream docs ↗

const match = await openligadb.getlastmatchbyleagueshortcut({ leagueShortcut: "bl1" });

Source: packages/provider/openligadb/src/openligadb.ts

getlastmatchbyleagueteam

GET https://api.openligadb.de/getlastmatchbyleagueteam/{leagueId}/{teamId}

Upstream docs ↗

const match = await openligadb.getlastmatchbyleagueteam({
  leagueId: 4500,
  teamId: 40,
});

Source: packages/provider/openligadb/src/openligadb.ts

getmatchdata

GET https://api.openligadb.de/getmatchdata/{matchId}

Upstream docs ↗

const res = await openligadb.getmatchdata.byId({ matchId: 68720 });

Source: packages/provider/openligadb/src/openligadb.ts

GET https://api.openligadb.de/getmatchdata/{leagueShortcut}/{leagueSeason}

Upstream docs ↗

const res = await openligadb.getmatchdata.byLeagueSeason({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
});

Source: packages/provider/openligadb/src/openligadb.ts

GET https://api.openligadb.de/getmatchdata/{leagueShortcut}/{leagueSeason}/{groupOrderId}

Upstream docs ↗

const res = await openligadb.getmatchdata.byLeagueSeasonGroup({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
  groupOrderId: 1,
});

Source: packages/provider/openligadb/src/openligadb.ts

GET https://api.openligadb.de/getmatchdata/{leagueShortcut}/{leagueSeason}/{teamFilterstring}

Upstream docs ↗

const res = await openligadb.getmatchdata.byLeagueSeasonTeam({
  leagueShortcut: "bl1",
  leagueSeason: 2024,
  teamFilterstring: "Bayern",
});

Source: packages/provider/openligadb/src/openligadb.ts

GET https://api.openligadb.de/getmatchdata/{teamId1}/{teamId2}

Upstream docs ↗

const res = await openligadb.getmatchdata.byTeams({ teamId1: 16, teamId2: 40 });

Source: packages/provider/openligadb/src/openligadb.ts

getmatchesbyteam

GET https://api.openligadb.de/getmatchesbyteam/{teamFilterstring}/{weekCountPast}/{weekCountFuture}

Upstream docs ↗

const matches = await openligadb.getmatchesbyteam({
  teamFilterstring: "Bayern",
  weekCountPast: 4,
  weekCountFuture: 2,
});

Source: packages/provider/openligadb/src/openligadb.ts

getmatchesbyteamid

GET https://api.openligadb.de/getmatchesbyteamid/{teamId}/{weekCountPast}/{weekCountFuture}

Upstream docs ↗

const matches = await openligadb.getmatchesbyteamid({
  teamId: 40,
  weekCountPast: 4,
  weekCountFuture: 2,
});

Source: packages/provider/openligadb/src/openligadb.ts

getnextmatchbyleagueshortcut

GET https://api.openligadb.de/getnextmatchbyleagueshortcut/{leagueShortcut}

Upstream docs ↗

const match = await openligadb.getnextmatchbyleagueshortcut({ leagueShortcut: "bl1" });

Source: packages/provider/openligadb/src/openligadb.ts

getnextmatchbyleagueteam

GET https://api.openligadb.de/getnextmatchbyleagueteam/{leagueId}/{teamId}

Upstream docs ↗

const match = await openligadb.getnextmatchbyleagueteam({
  leagueId: 4500,
  teamId: 40,
});

Source: packages/provider/openligadb/src/openligadb.ts

getresultinfos

GET https://api.openligadb.de/getresultinfos/{leagueId}

Upstream docs ↗

const resultInfo = await openligadb.getresultinfos({ leagueId: 4500 });

Source: packages/provider/openligadb/src/openligadb.ts

swagger

GET https://api.openligadb.de/swagger/v1/swagger.json

Upstream docs ↗

const res = await openligadb.swagger.v1.swaggerJson();

Source: packages/provider/openligadb/src/openligadb.ts

Part of the apicity monorepo.

License

MIT — see LICENSE.