让开源，少一点语言距离。
npm包中文文档

@apicity/openligadb

中文文档
0.26.0发布于 2026/11/05MITTypeScriptES Module近 30 天下载 3586

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

原始使用文档
中文原文
文档目录27 节
  1. Installation
  2. Quick Start
  3. Matchdata Examples
  4. Next Match And Team Window Examples
  5. Standings And Scorers Examples
  6. Catalog Discovery Flow
  7. Errors And Scope
  8. API Reference
  9. getavailablegroups
  10. getavailableleagues
  11. getavailablesports
  12. getavailableteams
  13. getbltable
  14. getcurrentgroup
  15. getgoalgetters
  16. getgrouptable
  17. getlastchangedate
  18. getlastmatchbyleagueshortcut
  19. getlastmatchbyleagueteam
  20. getmatchdata
  21. getmatchesbyteam
  22. getmatchesbyteamid
  23. getnextmatchbyleagueshortcut
  24. getnextmatchbyleagueteam
  25. getresultinfos
  26. swagger
  27. License

@apicity/openligadb

npm dependencies TypeScript docs

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.6.6 — 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 openligadb.getavailablegroups

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

Cost tier: cheap

Upstream docs ↗

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

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

getavailableleagues

GET openligadb.getavailableleagues

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

Cost tier: cheap

Upstream docs ↗

const leagues = await openligadb.getavailableleagues();

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

GET openligadb.getavailableleagues.bySeason

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

Cost tier: cheap

Upstream docs ↗

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

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

getavailablesports

GET openligadb.getavailablesports

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

Cost tier: cheap

Upstream docs ↗

const sports = await openligadb.getavailablesports();

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

getavailableteams

GET openligadb.getavailableteams

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

Cost tier: cheap

Upstream docs ↗

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

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

getbltable

GET openligadb.getbltable

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

Cost tier: cheap

Upstream docs ↗

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

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

getcurrentgroup

GET openligadb.getcurrentgroup

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

Cost tier: cheap

Upstream docs ↗

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

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

getgoalgetters

GET openligadb.getgoalgetters

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

Cost tier: cheap

Upstream docs ↗

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

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

getgrouptable

GET openligadb.getgrouptable

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

Cost tier: cheap

Upstream docs ↗

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

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

getlastchangedate

GET openligadb.getlastchangedate

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

Cost tier: cheap

Upstream docs ↗

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

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

getlastmatchbyleagueshortcut

GET openligadb.getlastmatchbyleagueshortcut

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

Cost tier: cheap

Upstream docs ↗

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

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

getlastmatchbyleagueteam

GET openligadb.getlastmatchbyleagueteam

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

Cost tier: cheap

Upstream docs ↗

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

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

getmatchdata

GET openligadb.getmatchdata.byId

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

Cost tier: cheap

Upstream docs ↗

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

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

GET openligadb.getmatchdata.byLeagueSeason

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

Cost tier: cheap

Upstream docs ↗

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

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

GET openligadb.getmatchdata.byLeagueSeasonGroup

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

Cost tier: cheap

Upstream docs ↗

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

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

GET openligadb.getmatchdata.byLeagueSeasonTeam

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

Cost tier: cheap

Upstream docs ↗

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

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

GET openligadb.getmatchdata.byTeams

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

Cost tier: cheap

Upstream docs ↗

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

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

getmatchesbyteam

GET openligadb.getmatchesbyteam

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

Cost tier: cheap

Upstream docs ↗

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

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

getmatchesbyteamid

GET openligadb.getmatchesbyteamid

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

Cost tier: cheap

Upstream docs ↗

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

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

getnextmatchbyleagueshortcut

GET openligadb.getnextmatchbyleagueshortcut

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

Cost tier: cheap

Upstream docs ↗

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

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

getnextmatchbyleagueteam

GET openligadb.getnextmatchbyleagueteam

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

Cost tier: cheap

Upstream docs ↗

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

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

getresultinfos

GET openligadb.getresultinfos

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

Cost tier: cheap

Upstream docs ↗

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

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

swagger

GET openligadb.swagger.v1.swaggerJson

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

Cost tier: cheap

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.

版本与发布记录

@apicity/openligadb 共发布 59 个版本，首次发布于 2026/06/24；过去 12 个月发布了 59 个版本。

版本发布日期距今
0.26.0latest2026/11/051 天前
0.25.02026/11/033 天前
0.24.12026/11/024 天前
0.24.02026/11/014 天前
0.23.12026/11/015 天前
0.23.02026/11/015 天前

关于 @apicity/openligadb 的常见问题

@apicity/openligadb 是什么？

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

如何安装 @apicity/openligadb？

在项目目录运行 npm install @apicity/openligadb，或使用 pnpm add / yarn add / bun add。

@apicity/openligadb 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@apicity/openligadb 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@apicity/openligadb 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@apicity/openligadb 可以商用吗？

@apicity/openligadb 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@apicity/openligadb 的下载量有多少？

根据 npm 官方下载统计，@apicity/openligadb 在 2026/10/06 – 2026/11/04 这 30 天内被下载 3,586 次，日均约 120 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@apicity/openligadb 还在维护吗？

最新版本 0.26.0 发布于 2026/11/05（1 天前）；至今共发布 59 个版本，其中过去 12 个月发布了 59 个；首次发布于 2026/06/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。