{
  "openapi": "3.1.0",
  "info": {
    "title": "球云体育赛事数据 API",
    "version": "1.0.0",
    "summary": "比分、赛程赛果与球队资料的公开只读 JSON 接口",
    "description": "简体中文的体育赛事数据，时间为北京时间（UTC+8）。公开只读、无需鉴权、允许跨域。\n\n每条比赛与球队都带 url（本站对应页面的绝对地址），响应顶层带 source。引用数据时请注明来源「球云体育」并链接对应页面。\n\n另有 MCP 端点 https://jsnjlingdong.top/api/mcp（Streamable HTTP，JSON-RPC 2.0），站点说明见 https://jsnjlingdong.top/llms.txt。",
    "contact": {
      "name": "球云体育",
      "url": "https://jsnjlingdong.top",
      "email": ""
    }
  },
  "servers": [
    {
      "url": "https://jsnjlingdong.top"
    }
  ],
  "externalDocs": {
    "description": "llms.txt（接口、MCP 工具与引用要求）",
    "url": "https://jsnjlingdong.top/llms.txt"
  },
  "paths": {
    "/api/v1/matches": {
      "get": {
        "operationId": "listMatches",
        "summary": "按日期查询赛程与比分",
        "description": "date 省略时为今天（北京时间）。可查询今天往前 365 天至往后 7 天。status=live 且不带 date 时走实时数据源，会包含跨零点仍在进行的比赛，此时 meta.date 为 null。",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "日期 YYYY-MM-DD（北京时间自然日）",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "example": "2026-09-27"
          },
          {
            "name": "league",
            "in": "query",
            "required": false,
            "description": "联赛 id，例如 epl、laliga、seriea、bundesliga、ligue1、ucl、csl、nba；完整清单见 https://jsnjlingdong.top/llms-full.txt。不存在的 id 返回 400。",
            "schema": {
              "type": "string"
            },
            "example": "csl"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "live 含中场休息",
            "schema": {
              "type": "string",
              "enum": [
                "live",
                "scheduled",
                "finished"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "赛程列表",
            "headers": {
              "Cache-Control": {
                "description": "已过去的日期缓存 1 天，今天与实时查询缓存 15 秒",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchList"
                }
              }
            }
          },
          "400": {
            "description": "参数不合法（日期格式、超出范围、未知联赛或状态）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/teams/{teamId}": {
      "get": {
        "operationId": "getTeam",
        "summary": "球队资料：排名、战绩、近期赛果与未来赛程",
        "parameters": [
          {
            "name": "teamId",
            "in": "path",
            "required": true,
            "description": "球队数字 id，与 /team/{teamId} 相同，可从赛程的 home.id / away.id 取得",
            "schema": {
              "type": "string"
            },
            "example": "10462"
          }
        ],
        "responses": {
          "200": {
            "description": "球队资料",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamResponse"
                }
              }
            }
          },
          "404": {
            "description": "球队不存在",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamNotFound"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Source": {
        "type": "object",
        "description": "出处。引用数据时请注明 name 并链接 url 或对应条目的 url。",
        "required": [
          "name",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "examples": [
              "球云体育"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://jsnjlingdong.top"
            ]
          }
        }
      },
      "LeagueRef": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "联赛 id，可用于 ?league= 与 /data/{id}",
            "examples": [
              "csl"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "中超"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "本站联赛资料页",
            "examples": [
              "https://jsnjlingdong.top/data/csl"
            ]
          }
        }
      },
      "MatchStatus": {
        "type": "string",
        "enum": [
          "scheduled",
          "live",
          "halftime",
          "finished",
          "postponed"
        ],
        "description": "scheduled 未开赛 / live 进行中 / halftime 中场 / finished 已结束 / postponed 延期"
      },
      "MatchSide": {
        "type": "object",
        "required": [
          "id",
          "name",
          "score",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "球队 id，可用于 /api/v1/teams/{id}",
            "examples": [
              "1618"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "山东泰山"
            ]
          },
          "short": {
            "type": "string",
            "description": "简称"
          },
          "code": {
            "type": "string",
            "description": "队名缩写（后端数据为队名前三个汉字）"
          },
          "score": {
            "type": "integer",
            "description": "比分；未开赛为 0"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "本站球队页",
            "examples": [
              "https://jsnjlingdong.top/team/1618"
            ]
          }
        }
      },
      "MatchSideBrief": {
        "type": "object",
        "required": [
          "id",
          "name",
          "score",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "球队 id，可用于 /api/v1/teams/{id}",
            "examples": [
              "1618"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "山东泰山"
            ]
          },
          "score": {
            "type": "integer",
            "description": "比分；未开赛为 0"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "本站球队页",
            "examples": [
              "https://jsnjlingdong.top/team/1618"
            ]
          }
        }
      },
      "Match": {
        "type": "object",
        "required": [
          "id",
          "league",
          "status",
          "statusLabel",
          "minute",
          "kickoff",
          "venue",
          "round",
          "home",
          "away",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "13376006"
            ]
          },
          "league": {
            "$ref": "#/components/schemas/LeagueRef"
          },
          "sport": {
            "type": "string",
            "enum": [
              "football",
              "basketball",
              "tennis",
              "baseball",
              "esports"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/MatchStatus"
          },
          "statusLabel": {
            "type": "string",
            "description": "状态中文名",
            "examples": [
              "已结束"
            ]
          },
          "minute": {
            "type": [
              "integer",
              "null"
            ],
            "description": "进行中的分钟数（足球）；其余状态为 null"
          },
          "kickoff": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "2026-08-14T19:35:00+08:00"
            ]
          },
          "venue": {
            "type": "string",
            "description": "场地，上游未提供时为空串"
          },
          "round": {
            "type": "string",
            "description": "轮次，上游未提供时为空串"
          },
          "home": {
            "$ref": "#/components/schemas/MatchSide"
          },
          "away": {
            "$ref": "#/components/schemas/MatchSide"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "本站比赛页",
            "examples": [
              "https://jsnjlingdong.top/match/13376006"
            ]
          }
        }
      },
      "TeamMatch": {
        "type": "object",
        "required": [
          "id",
          "league",
          "status",
          "statusLabel",
          "minute",
          "kickoff",
          "venue",
          "round",
          "home",
          "away",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "13376006"
            ]
          },
          "league": {
            "$ref": "#/components/schemas/LeagueRef"
          },
          "status": {
            "$ref": "#/components/schemas/MatchStatus"
          },
          "statusLabel": {
            "type": "string",
            "description": "状态中文名",
            "examples": [
              "已结束"
            ]
          },
          "minute": {
            "type": [
              "integer",
              "null"
            ],
            "description": "进行中的分钟数（足球）；其余状态为 null"
          },
          "kickoff": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "2026-08-14T19:35:00+08:00"
            ]
          },
          "venue": {
            "type": "string",
            "description": "场地，上游未提供时为空串"
          },
          "round": {
            "type": "string",
            "description": "轮次，上游未提供时为空串"
          },
          "home": {
            "$ref": "#/components/schemas/MatchSideBrief"
          },
          "away": {
            "$ref": "#/components/schemas/MatchSideBrief"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "本站比赛页",
            "examples": [
              "https://jsnjlingdong.top/match/13376006"
            ]
          }
        }
      },
      "MatchList": {
        "type": "object",
        "required": [
          "source",
          "data",
          "meta"
        ],
        "properties": {
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Match"
            }
          },
          "meta": {
            "type": "object",
            "required": [
              "date",
              "league",
              "status",
              "count",
              "generatedAt"
            ],
            "properties": {
              "date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "查询日期；实时数据源时为 null"
              },
              "league": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "live",
                  "scheduled",
                  "finished",
                  null
                ]
              },
              "count": {
                "type": "integer"
              },
              "generatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "响应生成时间"
              }
            }
          }
        }
      },
      "Team": {
        "type": "object",
        "required": [
          "id",
          "name",
          "league",
          "sport",
          "rank",
          "record",
          "form",
          "recent",
          "upcoming",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "10462"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "成都蓉城"
            ]
          },
          "short": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "color": {
            "type": "string",
            "description": "主色，#RRGGBB"
          },
          "league": {
            "$ref": "#/components/schemas/LeagueRef"
          },
          "sport": {
            "type": "string",
            "enum": [
              "football",
              "basketball",
              "tennis",
              "baseball",
              "esports"
            ]
          },
          "rank": {
            "type": [
              "integer",
              "null"
            ],
            "description": "联赛排名；未上积分榜为 null"
          },
          "record": {
            "type": "object",
            "required": [
              "played",
              "won",
              "drawn",
              "lost",
              "points",
              "goalsFor",
              "goalsAgainst",
              "goalDifference"
            ],
            "properties": {
              "played": {
                "type": "integer"
              },
              "won": {
                "type": "integer"
              },
              "drawn": {
                "type": "integer"
              },
              "lost": {
                "type": "integer"
              },
              "points": {
                "type": "integer"
              },
              "goalsFor": {
                "type": "integer"
              },
              "goalsAgainst": {
                "type": "integer"
              },
              "goalDifference": {
                "type": "integer"
              }
            }
          },
          "form": {
            "type": "array",
            "description": "最近五场，最新在前",
            "items": {
              "type": "string",
              "enum": [
                "W",
                "D",
                "L"
              ]
            }
          },
          "recent": {
            "type": "array",
            "description": "最近已结束的比赛，最新在前",
            "items": {
              "$ref": "#/components/schemas/TeamMatch"
            }
          },
          "upcoming": {
            "type": "array",
            "description": "未开赛的比赛，最近的在前",
            "items": {
              "$ref": "#/components/schemas/TeamMatch"
            }
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "本站球队页",
            "examples": [
              "https://jsnjlingdong.top/team/10462"
            ]
          }
        }
      },
      "TeamResponse": {
        "type": "object",
        "required": [
          "source",
          "data",
          "meta"
        ],
        "properties": {
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "data": {
            "$ref": "#/components/schemas/Team"
          },
          "meta": {
            "type": "object",
            "required": [
              "generatedAt"
            ],
            "properties": {
              "generatedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "source": {
            "type": "object",
            "description": "出处。引用数据时请注明 name 并链接 url 或对应条目的 url。",
            "required": [
              "name",
              "url"
            ],
            "properties": {
              "name": {
                "type": "string",
                "examples": [
                  "球云体育"
                ]
              },
              "url": {
                "type": "string",
                "format": "uri",
                "examples": [
                  "https://jsnjlingdong.top"
                ]
              }
            }
          },
          "error": {
            "type": "object",
            "required": [
              "message"
            ],
            "properties": {
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string",
                "description": "怎样改参数"
              }
            }
          }
        }
      },
      "TeamNotFound": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "error": {
            "type": "object",
            "required": [
              "message",
              "hint",
              "availableTeams"
            ],
            "properties": {
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string"
              },
              "availableTeams": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "name"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}