球队列表 - AnySport

返回球队基础资料（队名、国家、主场馆），支持三种查法：按 team_id 查单支球队详情、按名称模糊搜索、或按 league_id+season 查某届/某赛季的参赛球队名单。后一种用法适合”赛事参赛队列表”这类页面。同一联赛不同赛季的参赛队可能不同（如世界杯扩军后从 43 队增至 48 队），因此按联赛查询时必须带上 season 精确到届。球队基础资料本身是当前快照，不随赛季变化。

接口路径

GET /v1/soccer/teams

入参说明

参数	类型	必填	说明
`team_id`	string	否	按球队 ID 查（`ast_`）
`league_id`	string	否	按联赛查参赛球队（`asl_`）
`season`	string	条件必填	按 `league_id` 查时必填（联赛跨多届/多赛季，按赛季精确取参赛队；如世界杯 `2026`→48 支、`2022`→43 支）。按 team_id/team_name 查时不适用
`team_name`	string	否	按名称模糊查
`lang`	string	否	`en` / `zh-CN`，非法值静默回退默认语言，可选值以 `GET /languages`（19）为准
`page` / `limit`	int	否	分页，limit 范围 1~100

过滤条件可组合。按 league_id 查而未带 season 返回 400（INVALID_PARAMS）。球队的基础资料（队名/场馆等）为当前快照；league_id+season 组合返回的是该届/该赛季的参赛球队名单。

出参说明（data: 数组）

字段	类型	说明
`team_id`	string	球队 ID（`ast_` 前缀）
`name`	string	队名
`country`	string	所属国家/地区
`venue`	string	主场馆

入参示例

# 当前届（2026）参赛球队
GET /v1/soccer/teams?league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&season=2026&lang=en&limit=5

# 历史届（2022）参赛球队
GET /v1/soccer/teams?league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&season=2022&lang=en&limit=5

出参示例

{
  "success": true,
  "data": [
    {
      "team_id": "ast_f6090c8ded1f42e58226eedf59813890",
      "name": "Algeria",
      "country": "intl",
      "venue": "Stade Mohamed-Hamlaoui"
    },
    {
      "team_id": "ast_9137ee449e3b40a68149ca319373adaf",
      "name": "Argentina",
      "country": "intl",
      "venue": "Estadio Alberto José Armando"
    }
  ],
  "meta": {
    "total": 48,
    "page": 1,
    "limit": 5,
    "total_pages": 10,
    "timestamp": "2026-07-13T19:18:23.092928200Z"
  },
  "traceId": "7890e4ed-e2f7-435f-bb75-9dc795351100"
}

{
  "success": true,
  "data": [
    {
      "team_id": "ast_f6090c8ded1f42e58226eedf59813890",
      "name": "Algeria",
      "country": "intl",
      "venue": "Stade Mohamed-Hamlaoui"
    }
  ],
  "meta": {
    "total": 43,
    "page": 1,
    "limit": 5,
    "total_pages": 9,
    "timestamp": "2026-07-13T19:18:23.269297700Z"
  },
  "traceId": "8601ff66-85be-4680-838b-35e2fa8ed81c"
}

错误示例

按 league_id 查而缺 season → HTTP 400，error.code INVALID_PARAMS

GET /v1/soccer/teams?league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&limit=5