<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API
provided by 极数本源 (https://apizero.cn). Prefer Authorization: Bearer.
Success is business code === 0 (do not treat HTTP 200 as success).
Generate working backend code; never put the API Key in a frontend or app.
API Key: https://apizero.cn/account/keys
Human docs: https://apizero.cn/aidocs/football -->

# 足球赛事

按日期查询足球赛程与比分，覆盖英格兰、西班牙、意大利、德国、法国足球甲级联赛，以及欧洲冠军联赛、欧洲联赛、中国足球协会超级联赛、英格兰足球协会挑战杯、国际足联世界杯。返回开赛时间、比分、比赛状态与场馆，不含赔率或门票。

调用说明：
1）默认 POST /api/football，查询北京时间当日主流联赛；
2）按子接口分别查询进行中、未开赛、已结束，或指定联赛；
3）联赛列表子接口返回联赛代码与名称，不请求上游数据源。

时间均为北京时间。赛程缓存约 45 秒。登录每日 20 次；黄金 4000、钻石 8000；企业走额度。单用户 QPS 与条码查询同档。

## 平台约定

- 网关：`https://v1.apizero.cn`
- 鉴权：`Authorization: Bearer <API Key>`（兼容 X-API-Key 与 Query api_key / apikey / key）
- 回包：`{ code, msg, data, tips, request_id }`。成功看 `code === 0`

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `football` |
| 接口名称 | 足球赛事 |
| 接口地址 | `https://v1.apizero.cn/api/football` |
| 请求方法 | `POST` |
| 分类 | 生活服务 |
| 提供方 | 极数本源 |
| 计费模式 | 按次付费 · 点数包 · VIP |
| QPS 限制 | 2 req/s |
| 登录免费额度 | 20 次 |
| 匿名每日额度 | 5 次 |

### 会员每日额度

| 会员档位 | 每日免费 | QPS |
| --- | --- | --- |
| 黄金会员 | 4,000 次/日 | QPS 80 |
| 钻石会员 | 8,000 次/日 | QPS 30 |
| 企业会员 | 企业接口额度 | QPS 120 |

## 2. 认证

请求地址为 POST /api/football。请按子接口分别传入对应参数。返回时间均为北京时间。

获取 API Key：https://apizero.cn/account/keys

## 3. 子能力

### 今日赛程 (`today`)

查询北京时间当日英格兰、西班牙、意大利、德国、法国足球甲级联赛，以及欧洲冠军联赛、中国足球协会超级联赛的赛程、比分及比赛状态。可通过 date 指定比赛日，通过 limit 控制返回条数。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 进行中 (`live`)

查询指定日期处于进行中状态的比赛的赛程、比分及比赛状态。可通过 league 限定单一联赛。无符合条件的比赛时，matches 返回空数组。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `status` | `string` | 否 | 比赛状态。本子接口取值为 live（进行中）。 | `live` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `league` | `string` | 否 | 联赛代码。用于限定单一联赛；缺省为全部已覆盖联赛。 | `epl` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "live",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 未开赛 (`upcoming`)

查询指定日期处于尚未开赛状态的比赛的赛程、比分及比赛状态。可通过 league 限定单一联赛。无符合条件的比赛时，matches 返回空数组。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `status` | `string` | 否 | 比赛状态。本子接口取值为 upcoming（尚未开赛）。 | `upcoming` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `league` | `string` | 否 | 联赛代码。用于限定单一联赛；缺省为全部已覆盖联赛。 | `epl` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "upcoming",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 已结束 (`finished`)

查询指定日期处于已结束状态的比赛的赛程、比分及比赛状态。可通过 league 限定单一联赛。无符合条件的比赛时，matches 返回空数组。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `status` | `string` | 否 | 比赛状态。本子接口取值为 finished（已结束）。 | `finished` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `league` | `string` | 否 | 联赛代码。用于限定单一联赛；缺省为全部已覆盖联赛。 | `epl` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "finished",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 英超 (`epl`)

查询英格兰足球超级联赛指定日期的赛程、比分及比赛状态。时间均为北京时间。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `league` | `string` | 否 | 联赛代码。本子接口取值为 epl（英格兰足球超级联赛）。 | `epl` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `status` | `string` | 否 | 比赛状态。取值 all（全部）、live（进行中）、upcoming（未开赛）、finished（已结束）。 | `all` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 西甲 (`laliga`)

查询西班牙足球甲级联赛指定日期的赛程、比分及比赛状态。时间均为北京时间。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `league` | `string` | 否 | 联赛代码。本子接口取值为 laliga（西班牙足球甲级联赛）。 | `laliga` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `status` | `string` | 否 | 比赛状态。取值 all（全部）、live（进行中）、upcoming（未开赛）、finished（已结束）。 | `all` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 意甲 (`seriea`)

查询意大利足球甲级联赛指定日期的赛程、比分及比赛状态。时间均为北京时间。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `league` | `string` | 否 | 联赛代码。本子接口取值为 seriea（意大利足球甲级联赛）。 | `seriea` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `status` | `string` | 否 | 比赛状态。取值 all（全部）、live（进行中）、upcoming（未开赛）、finished（已结束）。 | `all` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 德甲 (`bundesliga`)

查询德国足球甲级联赛指定日期的赛程、比分及比赛状态。时间均为北京时间。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `league` | `string` | 否 | 联赛代码。本子接口取值为 bundesliga（德国足球甲级联赛）。 | `bundesliga` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `status` | `string` | 否 | 比赛状态。取值 all（全部）、live（进行中）、upcoming（未开赛）、finished（已结束）。 | `all` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 法甲 (`ligue1`)

查询法国足球甲级联赛指定日期的赛程、比分及比赛状态。时间均为北京时间。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `league` | `string` | 否 | 联赛代码。本子接口取值为 ligue1（法国足球甲级联赛）。 | `ligue1` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `status` | `string` | 否 | 比赛状态。取值 all（全部）、live（进行中）、upcoming（未开赛）、finished（已结束）。 | `all` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 欧冠 (`ucl`)

查询欧洲冠军联赛指定日期的赛程、比分及比赛状态。时间均为北京时间。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `league` | `string` | 否 | 联赛代码。本子接口取值为 ucl（欧洲冠军联赛）。 | `ucl` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `status` | `string` | 否 | 比赛状态。取值 all（全部）、live（进行中）、upcoming（未开赛）、finished（已结束）。 | `all` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 欧联 (`uel`)

查询欧洲联赛指定日期的赛程、比分及比赛状态。时间均为北京时间。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `league` | `string` | 否 | 联赛代码。本子接口取值为 uel（欧洲联赛）。 | `uel` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `status` | `string` | 否 | 比赛状态。取值 all（全部）、live（进行中）、upcoming（未开赛）、finished（已结束）。 | `all` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 中超 (`csl`)

查询中国足球协会超级联赛指定日期的赛程、比分及比赛状态。时间均为北京时间。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `league` | `string` | 否 | 联赛代码。本子接口取值为 csl（中国足球协会超级联赛）。 | `csl` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `status` | `string` | 否 | 比赛状态。取值 all（全部）、live（进行中）、upcoming（未开赛）、finished（已结束）。 | `all` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 足总杯 (`facup`)

查询英格兰足球协会挑战杯指定日期的赛程、比分及比赛状态。时间均为北京时间。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `league` | `string` | 否 | 联赛代码。本子接口取值为 facup（英格兰足球协会挑战杯）。 | `facup` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `status` | `string` | 否 | 比赛状态。取值 all（全部）、live（进行中）、upcoming（未开赛）、finished（已结束）。 | `all` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 世界杯 (`worldcup`)

查询国际足联世界杯指定日期的赛程、比分及比赛状态。时间均为北京时间。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `league` | `string` | 否 | 联赛代码。本子接口取值为 worldcup（国际足联世界杯）。 | `worldcup` |
| `date` | `string` | 否 | 比赛日期。格式 YYYY-MM-DD 或 YYYYMMDD，缺省为北京时间当日。 | `2026-09-12` |
| `status` | `string` | 否 | 比赛状态。取值 all（全部）、live（进行中）、upcoming（未开赛）、finished（已结束）。 | `all` |
| `limit` | `int` | 否 | 返回条数。取值范围 1–200，缺省 80。 | `80` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `summary.sport` | `string` | 运动：football / basketball |
| `summary.date` | `string` | 查询的比赛日（北京日期） |
| `summary.league` | `string` | 联赛代码或 all |
| `summary.count` | `number` | 本次返回场次数 |
| `summary.generated_at` | `string` | 生成时间（北京时间） |
| `summary.live` | `number` | 本次返回中进行中的场次数 |
| `summary.total` | `number` | 当日该范围未截断前的场次总数 |
| `summary.status` | `string` | 筛选状态：all / live / upcoming / finished |
| `matches` | `array` | 赛程：进行中 → 未开赛按时间 → 已结束 |
| `matches[].id` | `string` | 场次 ID |
| `matches[].league_name` | `string` | 联赛中文名 |
| `matches[].start_at` | `string` | 开赛时间（北京时间） |
| `matches[].status` | `string` | live / upcoming / finished |
| `matches[].home` | `object` | 主队 name / short / logo / score |
| `matches[].home.name` | `string` | 名称 |
| `matches[].home.short` | `string` | short |
| `matches[].home.score` | `number` | score |
| `matches[].away` | `object` | 客队 name / short / logo / score |
| `matches[].away.name` | `string` | 名称 |
| `matches[].away.short` | `string` | short |
| `matches[].away.score` | `number` | score |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "summary": {
      "sport": "football",
      "date": "2026-09-12",
      "league": "all",
      "status": "all",
      "count": 1,
      "total": 7,
      "live": 0,
      "generated_at": "2026-09-11 17:40:00"
    },
    "matches": [
      {
        "id": "401879285",
        "league": "epl",
        "league_name": "英超",
        "start_at": "2026-09-12 22:00:00",
        "status": "upcoming",
        "status_text": "未开赛",
        "venue": "Vitality Stadium",
        "home": {
          "name": "AFC Bournemouth",
          "short": "BOU",
          "score": 0
        },
        "away": {
          "name": "Brentford",
          "short": "BRE",
          "score": 0
        }
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

### 联赛列表 (`leagues`)

返回本接口支持的联赛代码与名称，不请求上游数据源。

- 方法：`POST`
- 路径：`/api/football`

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `action` | `string` | 否 | 操作类型。本子接口取值为 leagues（返回联赛目录）。 | `leagues` |

**响应字段**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `sport` | `string` | football |
| `count` | `number` | 联赛数量 |
| `leagues` | `array` | id / code / name |
| `leagues[].id` | `string` | id |
| `leagues[].code` | `string` | code |
| `leagues[].name` | `string` | 名称 |
| `tips` | `string` | 品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn |


```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "sport": "football",
    "count": 10,
    "leagues": [
      {
        "id": "epl",
        "code": "epl",
        "name": "英超"
      },
      {
        "id": "laliga",
        "code": "laliga",
        "name": "西甲"
      },
      {
        "id": "seriea",
        "code": "seriea",
        "name": "意甲"
      },
      {
        "id": "bundesliga",
        "code": "bundesliga",
        "name": "德甲"
      },
      {
        "id": "ligue1",
        "code": "ligue1",
        "name": "法甲"
      },
      {
        "id": "ucl",
        "code": "ucl",
        "name": "欧冠"
      },
      {
        "id": "uel",
        "code": "uel",
        "name": "欧联"
      },
      {
        "id": "csl",
        "code": "csl",
        "name": "中超"
      },
      {
        "id": "facup",
        "code": "facup",
        "name": "足总杯"
      },
      {
        "id": "worldcup",
        "code": "worldcup",
        "name": "世界杯"
      }
    ]
  },
  "tips": "极数本源 · https://apizero.cn"
}
```


## 5. 请求示例

示例都是服务端写法。Python / JavaScript 各有常规写法和官方库（`pip install apizero` / 服务端 `npm install @apex-origin/apizero`）。把 Key 放在环境变量 `APIZERO_KEY`，不要写进浏览器、小程序或前端打包。成功后先判断 `code == 0` 再读 `data`。

### cURL

```bash
# 服务端执行：export APIZERO_KEY=...
# 密钥：https://apizero.cn/account/keys
curl -sS -X POST "https://v1.apizero.cn/api/football" \
  -H "Authorization: Bearer $APIZERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Python

```python
# 服务端常规写法：标准库 urllib，不用 pip
# 设置环境变量 APIZERO_KEY 后运行，不要把 Key 写进前端
# 密钥：https://apizero.cn/account/keys
import json
import os
import ssl
import urllib.error
import urllib.request

key = os.environ.get("APIZERO_KEY") or ""
if not key:
    raise SystemExit("请在服务端设置环境变量 APIZERO_KEY，不要把 Key 写进前端")

url = "https://v1.apizero.cn/api/football"
payload = {}
req = urllib.request.Request(
    url,
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + key,
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(
        req, timeout=20, context=ssl.create_default_context()
    ) as resp:
        raw = resp.read().decode("utf-8")
except urllib.error.HTTPError as e:
    raw = e.read().decode("utf-8", "replace")
body = json.loads(raw)
print(json.dumps(body, ensure_ascii=False, indent=2))
if body.get("code") == 0:
    print(body.get("data"))
```

### Python 官方库

```python
# 官方库（服务端）：先执行一次 pip install apizero
# 设置环境变量 APIZERO_KEY 后运行，不要把 Key 写进前端
# https://apizero.cn/account/keys
import os
import apizero

key = os.environ.get("APIZERO_KEY") or ""
if not key:
    raise SystemExit("请在服务端设置环境变量 APIZERO_KEY，不要把 Key 写进前端")
client = apizero.key(key)
r = client.football()
if not r.ok:
    raise RuntimeError(r.msg)
print(r.ok, r.code)
print(r.json)
```

### JavaScript

```javascript
// 服务端 Node 18+ fetch，不要把 Key 写进浏览器 / 小程序 / 前端打包
// 设置环境变量 APIZERO_KEY 后运行
// 密钥：https://apizero.cn/account/keys
const key = process.env.APIZERO_KEY;
if (!key) throw new Error("请在服务端设置环境变量 APIZERO_KEY，不要把 Key 写进前端");
const url = "https://v1.apizero.cn/api/football";
const res = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const body = await res.json();
console.log(body);
if (body.code === 0) console.log(body.data);
```

### JavaScript 官方库（Node）

```javascript
// 官方库（服务端 Node）：先执行一次 npm install @apex-origin/apizero
// 设置环境变量 APIZERO_KEY 后运行
// 不要把 Key 写进浏览器 / Vue / React / 小程序
// https://apizero.cn/account/keys
const { key } = require("@apex-origin/apizero");
// ESM: import { key } from "@apex-origin/apizero";

const apiKey = process.env.APIZERO_KEY;
if (!apiKey) throw new Error("请在服务端设置环境变量 APIZERO_KEY，不要把 Key 写进前端");
const client = key(apiKey);
const r = await client.football();
if (!r.ok) throw new Error(r.msg);
console.log(r.ok, r.code);
console.log(r.json);
```

### Go

```go
// 服务端常规写法：net/http
// 设置环境变量 APIZERO_KEY 后运行，不要把 Key 写进前端
// 密钥：https://apizero.cn/account/keys
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	key := os.Getenv("APIZERO_KEY")
	if key == "" {
		panic("请在服务端设置环境变量 APIZERO_KEY，不要把 Key 写进前端")
	}

	url := "https://v1.apizero.cn/api/football"
	payload, err := json.Marshal(map[string]any{})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+key)
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	raw, _ := io.ReadAll(resp.Body)
	fmt.Println(string(raw))
}
```

### Java

```java
// 服务端常规写法：Java 11+ HttpClient
// Jackson：com.fasterxml.jackson.databind.ObjectMapper
// 设置环境变量 APIZERO_KEY 后运行，不要把 Key 写进前端
// 密钥：https://apizero.cn/account/keys
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.util.LinkedHashMap;
import java.util.Map;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
    public static void main(String[] args) throws Exception {
        String key = System.getenv("APIZERO_KEY");
        if (key == null || key.isBlank()) {
            throw new IllegalStateException("请在服务端设置环境变量 APIZERO_KEY，不要把 Key 写进前端");
        }
        ObjectMapper mapper = new ObjectMapper();
        String url = "https://v1.apizero.cn/api/football";

        Map<String, Object> payload = new LinkedHashMap<>();
        String json = mapper.writeValueAsString(payload);

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();
        HttpRequest req = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "Bearer " + key)
                .timeout(Duration.ofSeconds(20))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
        JsonNode body = mapper.readTree(resp.body());
        System.out.println(resp.body());
        if (body.path("code").asInt() == 0) {
            System.out.println(body.path("data"));
        }
    }
}
```

### PHP

```php
<?php
// 服务端常规写法：curl，强制 TLS 1.2
// 设置环境变量 APIZERO_KEY 后运行，不要把 Key 写进前端
// 密钥：https://apizero.cn/account/keys
$key = getenv('APIZERO_KEY') ?: '';
if ($key === '') {
    fwrite(STDERR, "请在服务端设置环境变量 APIZERO_KEY，不要把 Key 写进前端" . PHP_EOL);
    exit(1);
}

$ch = curl_init("https://v1.apizero.cn/api/football");
$opts = [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.$key,
        'Content-Type: application/json',
    ],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([], JSON_UNESCAPED_UNICODE),
];
if (defined('CURL_SSLVERSION_TLSv1_2')) {
    $opts[CURLOPT_SSLVERSION] = CURL_SSLVERSION_TLSv1_2;
}
curl_setopt_array($ch, $opts);
$raw = curl_exec($ch);
if ($raw === false) {
    fwrite(STDERR, 'cURL Error: '.curl_error($ch).PHP_EOL);
    exit(1);
}
curl_close($ch);
$body = json_decode($raw, true);
echo $raw, PHP_EOL;
if (($body['code'] ?? null) === 0) {
    echo json_encode($body['data'] ?? null, JSON_UNESCAPED_UNICODE), PHP_EOL;
}
```

### Rust

```rust
// 服务端常规写法
// cargo add reqwest --features json,blocking ; cargo add serde_json
// 设置环境变量 APIZERO_KEY 后运行，不要把 Key 写进前端
// 密钥：https://apizero.cn/account/keys
use reqwest::blocking::Client;
use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION};
use serde_json::Value;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("APIZERO_KEY").expect("请在服务端设置环境变量 APIZERO_KEY，不要把 Key 写进前端");

    let url = "https://v1.apizero.cn/api/football";
    let mut headers = HeaderMap::new();
    headers.insert(
        AUTHORIZATION,
        HeaderValue::from_str(&format!("Bearer {key}"))?,
    );
    headers.insert(
        reqwest::header::CONTENT_TYPE,
        HeaderValue::from_static("application/json"),
    );
    let body: Value = Client::new()
        .post(url)
        .json(&serde_json::json!({}))
        .headers(headers)
        .timeout(std::time::Duration::from_secs(20))
        .send()?
        .json()?;
    println!("{}", serde_json::to_string_pretty(&body)?);
    Ok(())
}
```

## 8. 错误码

先看业务 code。HTTP 也可能不是 200。

| 业务码 | HTTP | 说明 |
| --- | --- | --- |
| 0 | 200 | 成功 |
| 4000 | 400 | 参数错误 |
| 4011 | 401 | API Key 无效 |
| 4013 | 403 | API Key 已暂停 |
| 4014 | 403 | 当前 IP 不在 Key 白名单 |
| 4015 | 401 | 此接口需要 API Key |
| 4022 | 402 | 余额不足 |
| 4029 | 429 | 调用过快（QPS） |
| 4030 | 429 | 今日免费额度已用完 |
| 4040 | 503 | 接口已下线 |
| 4041 | 404 | 接口不存在 |
| 5000 | 500 | 服务器内部错误 |
| 5020 | 502 | 上游暂时不可用 |
| 5021 | 502 | 上游返回格式异常 |
| 5030 | 502 | 暂无可用节点 |


## 9. 变更日志

- **1.0.0** (2026-09-11): 上架按日期查询赛程与比分
支持联赛过滤与进行中筛选