板球记分卡 API JSON 解析:保留局次、数值与比赛状态

发布于 2026年10月29日

scorecard 这个键下面是数组,不是对象。这件小事决定了整个解析层的形状:写成 data.scorecard.innings1 的代码,会在第一场多局次比赛上读到 undefined;按球队名建字典的代码,则会在同一支球队击球两次时覆盖前一局。

match-details-get-scorecard 经探测确认的顶层结构有五项:数组 scorecard、布尔 ismatchcomplete、字符串 status、整数 responselastupdated 和对象 appindex。下面用 JavaScript 为前四项各写一个小函数,再拼成一个适配器。嵌套的击球字段只使用接口文档里那份未经验证的示例出现过的名字,并逐处标明;投球数据、额外分、失门记录在示例里看不到,这里一概不假设。

先遍历 scorecard 数组,再决定如何标注局次

这个接口只有路径参数 matchId,没有局次、球队或球员过滤器,一次请求拿到的就是整场比赛的整个数组,筛选只能发生在解析之后。

探测只确认了 scorecard 是数组,没有确认“一个元素恰好对应一局”,也没有确认元素里带稳定的局次编号。稳妥的做法是用数组下标当内部键,保持接口给出的顺序;界面上的“第几局”“某队击球”,等你在自己的响应里核对过元素内容再生成。也不要从实时列表里借 inngs1、inngs2 这类命名,那是列表接口 matchScore 的结构,不是记分卡的路径。

下面的代码存为 scorecard.js(Node 18 以上,ESM)。

function readInnings(scorecard) {
  // Array position is the only innings key until a real response shows a stable id.
  if (!Array.isArray(scorecard)) {
    throw new TypeError("scorecard must be an array");
  }
  return scorecard.map((entry, position) => ({ position, entry }));
}

不要在局次循环中丢掉 ismatchcomplete 和 status

ismatchcomplete 和 status 挂在响应顶层,属于整场比赛,不属于任何一局。把它们塞进 scorecard.map(...) 里,要么每局重复一份,要么在数组为空时整个丢失,页面只好靠“最后一局看起来打完了”去猜比赛是否结束。

读取时按类型严格校验。JavaScript 里 "false" 是真值,Boolean("false") 得到 true;ismatchcomplete 只要不是布尔值就应当报错,而不是悄悄转换。status 是自由文本,现有证据没有列出它的取值,原样展示即可,不要映射成自己的枚举,也不要和实时列表 matchInfo 里的 state(探测中见过 In Progress、Complete 等)并成一套状态机,那是另一个接口的字段。

还有一层容易混淆:ismatchcomplete: false 是正常取值,表示比赛尚未结束;请求失败、业务码异常或结构校验不通过是另一类事件,应保留上一次的有效快照并提示数据可能已过期,而不是渲染成“未结束”。

function readMatchState(data) {
  if (typeof data.ismatchcomplete !== "boolean") {
    throw new TypeError("ismatchcomplete must be a boolean");
  }
  if (typeof data.status !== "string") {
    throw new TypeError("status must be a string");
  }
  return { complete: data.ismatchcomplete, statusText: data.status };
}

responselastupdated 的大小写与类型不能照搬实时比赛列表

同样表示“最后更新”,matches-live 返回的是驼峰的 responseLastUpdated,值是字符串;记分卡返回的是全小写的 responselastupdated,值是整数。两处的类型探测都核对过。迷你记分卡的接口说明还提到,键名以小写为主,个别球员键又是驼峰。所以每个操作都按自己的响应读键名,不要写一个忽略大小写的“别名”函数,把几个接口的字段揉成同一个。

记分卡里的整数,文档没有说明时间单位,也没有说明它与列表里的字符串是否同源。它只适合当变化标记:和缓存的记分卡一起存下来,下次轮询时比较是否变了。不要把它转成日期,也不要拿它和列表里的字符串比大小。用 Number.isSafeInteger 校验,是为了在数值超出 JavaScript 安全整数范围之前就发现问题,而不是让精度悄悄丢失。

function readUpdateMarker(data) {
  // Lowercase key, integer value, unit undocumented: a change marker only.
  if (!Number.isSafeInteger(data.responselastupdated)) {
    throw new TypeError("responselastupdated must be a safe integer");
  }
  return data.responselastupdated;
}

JavaScript 记分卡模型应保留 JSON 数值类型

JSON.parse 会把 12 解析成数字,把 "154.55" 保留为字符串。接口示例里,runs、balls、fours、sixes 是整数,strkrate 是 "154.55" 这样的字符串。这些名字都来自未经验证的示例,上线前要在自己的响应里再确认一遍。

模型里的存法:整数保持整数,缺失存 null,不要用 || 0 补零,因为真实的 0 分与字段缺失是两回事。strkrate 保留原文,另算一个数值字段,且只在文本能无歧义地转成数字时才生成:Number("") 是 0,parseInt("154.55") 是 154,两者都会悄悄出错。数字变字符串只发生在渲染那一刻,排序、累加和比较一律用数值,否则 "9" 会排在 "10" 后面。

const intOrNull = (value) => (Number.isInteger(value) ? value : null);

function parseRate(text) {
  if (typeof text !== "string" || text.trim() === "") return null;
  const value = Number(text);
  return Number.isFinite(value) ? value : null;
}

function readBatters(entry) {
  // Key names come from the endpoint's unverified source example.
  const rows = Array.isArray(entry?.batsman) ? entry.batsman : [];
  return rows.map((row) => ({
    id: row.id ?? null,
    name: row.name ?? null,
    runs: intOrNull(row.runs),
    balls: intOrNull(row.balls),
    fours: intOrNull(row.fours),
    sixes: intOrNull(row.sixes),
    strikeRateText: typeof row.strkrate === "string" ? row.strkrate : null,
    strikeRate: parseRate(row.strkrate),
    dismissal: row.outdec ?? null,
  }));
}

export function parseScorecard(data) {
  if (data === null || typeof data !== "object") {
    throw new TypeError("scorecard payload must be an object");
  }
  return {
    ...readMatchState(data),
    updateMarker: readUpdateMarker(data),
    innings: readInnings(data.scorecard).map(({ position, entry }) => ({
      position,
      batters: readBatters(entry),
    })),
  };
}

比赛级字段在返回对象的第一层,局次数组在 innings 里,两者互不嵌套。

把比赛列表中的 matchId 传给单场记分卡接口

记分卡接口自己不会列比赛,matchId 来自列表类操作:matches-live、matches-recent、matches-upcoming,或按 type 取视图的 matches-list;赛程、系列赛、球队和场馆的比赛列表也会返回。以实时列表为例,ID 在 typeMatches[].seriesMatches[].seriesAdWrapper.matches[].matchInfo.matchId。seriesMatches 里还夹着只有 name、layout、position 的广告占位对象,没有 seriesAdWrapper,遍历时要跳过。列表里的 matchId 原样交给 URLSearchParams 即可,不必先 parseInt。

平台 Key 在登录后的控制台获取,只放进服务端环境变量 OPENDATA_API_KEY,文中的 YOUR_API_KEY 只是占位。Key 走查询参数,可能进入访问日志,不要写进前端、截图或报错文本。请求模板如下,打开本页或复制它们都不会发出数据请求:

  • https://api.opendata-api.com/api/project/cricbuzz-cricket/matches-live?key=YOUR_API_KEY,不需要其他参数。
  • https://api.opendata-api.com/api/project/cricbuzz-cricket/match-details-get-scorecard?key=YOUR_API_KEY&matchId=<列表里的 matchId>。探测用的是文档默认值 40381,它不能替你要服务的比赛作保证。

下面的 call 把两层状态分开:HTTP 非 2xx 是传输或鉴权问题;HTTP 200 但外层 code 不是 200,是平台业务失败,数据在 data 里。项目中有的操作可能返回 204 无内容,既不是故障,也没有 JSON 可解析,所以单独返回 null。

import { parseScorecard } from "./scorecard.js";

const BASE = "https://api.opendata-api.com/api/project/cricbuzz-cricket";

async function call(operationId, params = {}) {
  const key = process.env.OPENDATA_API_KEY;
  if (!key) throw new Error("OPENDATA_API_KEY is not set");
  // Never put this URL in an error message: it carries the key.
  const url = `${BASE}/${operationId}?${new URLSearchParams({ ...params, key })}`;
  const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
  if (response.status === 204) return null; // no content, not a failure
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const envelope = await response.json();
  if (envelope?.code !== 200) throw new Error("Gateway business failure");
  return envelope.data;
}

function* matchIdsFrom(list) {
  for (const group of list?.typeMatches ?? []) {
    for (const item of group.seriesMatches ?? []) {
      // Placeholder ad objects have no seriesAdWrapper, so they yield nothing.
      for (const match of item.seriesAdWrapper?.matches ?? []) {
        if (match.matchInfo?.matchId !== undefined) yield match.matchInfo.matchId;
      }
    }
  }
}

const live = await call("matches-live");
const [matchId] = matchIdsFrom(live);
if (matchId !== undefined) {
  const payload = await call("match-details-get-scorecard", { matchId });
  if (payload) console.log(parseScorecard(payload));
}

用明确标注的合成数据测试空数组与多局次解析

文档没有给出已核实的空数组或多局次样本,所以这两类测试只能用合成夹具:名字和数值都是编的,只借用了示例里出现过的键名,目的是测试解析器,不是复现任何真实比赛。不要把它们当作接口返回贴进文档或截图。

三个用例足以守住前面的约定:空数组仍是合法的比赛级快照;多局次保持顺序且数值仍是数字;字符串形式的 "false" 会被拒绝。

import test from "node:test";
import assert from "node:assert/strict";
import { parseScorecard } from "./scorecard.js";

// SYNTHETIC fixtures: invented for parser tests, not observed API responses.
const base = { ismatchcomplete: false, status: "synthetic status", responselastupdated: 1 };

test("empty scorecard array stays a valid snapshot", () => {
  const card = parseScorecard({ ...base, scorecard: [] });
  assert.deepEqual(card.innings, []);
  assert.equal(card.complete, false);
});

test("multi-innings array keeps order and numeric types", () => {
  const card = parseScorecard({
    ...base,
    ismatchcomplete: true,
    scorecard: [
      { batsman: [{ id: 1, name: "Synthetic A", runs: 9, balls: 12, fours: 1, sixes: 0, strkrate: "75" }] },
      { batsman: [{ id: 2, name: "Synthetic B", runs: 17, balls: 11, fours: 2, sixes: 1, strkrate: "154.55" }] },
    ],
  });
  assert.deepEqual(card.innings.map((i) => i.position), [0, 1]);
  assert.equal(card.innings[1].batters[0].runs, 17);
  assert.equal(card.innings[1].batters[0].strikeRateText, "154.55");
  assert.equal(card.innings[1].batters[0].strikeRate, 154.55);
  assert.equal(card.complete, true);
});

test("string booleans are rejected", () => {
  assert.throws(() => parseScorecard({ ...base, ismatchcomplete: "false", scorecard: [] }), TypeError);
});

记分卡接口的边界:逐球解说、赛事覆盖与刷新频率

适配器到这里就该停手,下面这些需求各有自己的操作,别硬塞进记分卡模型:

  • 逐球解说不在记分卡里。 按局次取解说用 match-details-get-commentaries:iid 限定局次,tms 传上一条的毫秒时间戳翻页;按球员取则用 match-details-get-player-commentaries(playerId、type)。它们的响应键同样来自未验证示例。
  • The Hundred 走独立路由。 记分卡是 match-details-get-scorecard-hundred,解说、高亮等也都带 -hundred 后缀。文档称其字段未经探测确认,别直接套标准记分卡的解析器。
  • 精简与完整是不同操作。 列表里的 matchScore 够做比分卡片;match-details-get-miniscorecard 和 match-details-get-livescore 是紧凑的比分面板(文档示例,未验证);逐人击球表才用 match-details-get-scorecard。需要的字段越少,越不必拉完整记分卡。
  • 球员、排名、拍卖与新闻各有入口。 按姓名找球员用 players-search(plrN),拿到 playerId 再查击球、投球或生涯统计;联赛积分榜、ICC 排名和 ICC 赛事积分是三个不同操作;IPL、WPL 拍卖先用 auction-list-seasons 确认支持的赛事与年份;新闻可按球队、球员、系列赛采集。梦幻体育类接口是赛前研究资料,不等于梦幻平台的实时积分接口。

覆盖范围与刷新频率,文档都没有承诺。未开赛或中止的比赛,响应可能很稀疏;status 的取值、投球数据是否存在、responselastupdated 的单位,都要在你要服务的赛事上自己核对。轮询间隔由应用决定,接口没有给出更新周期,可以在 ismatchcomplete 为 true 后停止刷新,再考虑缓存。上线前还要确认目标赛事的覆盖范围、更新延迟,以及你展示这些数据所需的内容使用权限;一次请求成功,不等于你有权展示这份比分。