足球数据接口完整使用指南

发布时间： 2026-04-01

本文系统介绍 AnySport API 所提供的全部足球数据接口。文章将依次说明每个接口的用途、调用方式、请求参数，并配以 Python 代码示例及对应的 JSON 响应结构，供开发者在集成时参考。

准备工作

认证方式

所有请求均需在 HTTP 请求头中传入 API Key：

X-API-Key: YOUR_API_KEY

API Key 可在 Dashboard 中获取。

基础 URL

https://api.anysport.io/v1

多语言支持

多数接口支持 lang 参数，用于控制球队名称、联赛名称、球员姓名等字段的返回语言。

参数值	语言
`en`	英文（默认）
`zh`	中文
`ja`	日文
`ko`	韩文
`th`	泰文

Python 通用配置

以下代码片段将在本文各示例中复用：

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.anysport.io/v1'

HEADERS = {'X-API-Key': API_KEY}

接口一览

AnySport的足球API提供完整的足球数据，能满足绝大部分的应用场景：

接口	路径	所需套餐	说明
赛事	`GET /v1/matches`	Free	赛程与比赛结果
实时比分	`GET /v1/livescore`	Free	正在进行中的比赛实时数据
联赛	`GET /v1/leagues`	Free	全球 900+ 联赛列表
国家/地区	`GET /v1/countries`	Free	支持的国家/地区列表
积分榜	`GET /v1/standings`	Free	联赛积分榜（总榜/主场/客场）
历史交锋	`GET /v1/head2head`	Free	两队历史对阵记录
球队	`GET /v1/teams`	Basic	俱乐部详情与球员名单
球员	`GET /v1/players`	Basic	球员资料与本赛季数据
射手榜	`GET /v1/topscorers`	Basic	联赛进球排名
阵容	`GET /v1/lineups`	Basic	比赛首发与替补阵容
赔率	`GET /v1/odds`	Pro	赛前博彩赔率
实时赔率	`GET /v1/odds/live`	Pro	盘中实时赔率
胜负概率	`GET /v1/probabilities`	Pro	赛前胜/平/负及进球概率预测

1. 赛事接口（Matches）

路径： GET /v1/matches
所需套餐： Free 及以上

返回足球赛程与比赛结果，包含比分、进球、出牌、换人、比赛统计等完整信息。支持按日期、联赛、球队或比赛 ID 过滤。

查询参数

参数	类型	说明
`date`	string	指定日期（`YYYY-MM-DD`），默认为今天
`from` / `to`	string	日期范围查询
`league_id`	string	按联赛 ID 过滤
`team_id`	string	按球队 ID 过滤
`match_id`	string	查询单场比赛
`lang`	string	响应语言，默认 `en`
`page` / `limit`	integer	分页，`limit` 最大 200

Python 示例

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.anysport.io/v1'
HEADERS = {'X-API-Key': API_KEY}

def get_matches(date=None, from_date=None, to_date=None,
                league_id=None, team_id=None, match_id=None,
                lang='zh', page=1, limit=50):
    params = {'lang': lang, 'page': page, 'limit': limit}
    if date:      params['date'] = date
    if from_date: params['from'] = from_date
    if to_date:   params['to'] = to_date
    if league_id: params['league_id'] = league_id
    if team_id:   params['team_id'] = team_id
    if match_id:  params['match_id'] = match_id

    r = requests.get(f'{BASE_URL}/matches', params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# 获取英超指定日期比赛（中文名称）
result = get_matches(date='2026-03-22', league_id='152', lang='zh')
for match in result['data']:
    print(f"{match['home']} {match['score']} {match['away']} | {match['status']}")

JSON 响应示例

{
  "success": true,
  "data": [
    {
      "match_id": 1626442,
      "date": "2026-03-22",
      "time": "15:15",
      "home": "阿斯顿维拉",
      "home_id": 3088,
      "home_badge": "https://api.anysport.io/images/team/3088",
      "away": "西汉姆联",
      "away_id": 3081,
      "away_badge": "https://api.anysport.io/images/team/3081",
      "ht_score": "1-0",
      "score": "2-0",
      "status": "finished",
      "minute": null,
      "live": false,
      "league": "英超",
      "league_id": 152,
      "league_round": "第31轮",
      "league_season": "2025/2026",
      "league_logo": "https://api.anysport.io/images/league/152",
      "country": "英格兰",
      "country_id": 44,
      "stadium": "维拉公园",
      "referee": "P. Tierney",
      "home_formation": "4-2-3-1",
      "away_formation": "4-3-3",
      "vars": {
        "home_team": [],
        "away_team": []
      },
      "goals": [
        {
          "time": "15",
          "player": "J. McGinn",
          "player_id": 215174918,
          "type": "goal",
          "team": "home"
        }
      ],
      "cards": [
        {
          "time": "45",
          "player": "A. Wan-Bissaka",
          "player_id": 2462525831,
          "type": "yellow",
          "team": "away"
        }
      ],
      "subs": [
        {
          "time": "67",
          "player_in": "Y. Tielemans",
          "player_in_id": 828527899,
          "player_out": "J. McGinn",
          "player_out_id": 215174918,
          "team": "home"
        }
      ],
      "stats": [
        { "type": "Ball Possession", "home": "59%", "away": "41%" },
        { "type": "Shots Total", "home": "23", "away": "9" }
      ],
      "lineups": null
    }
  ],
  "meta": {
    "total": 14,
    "page": 1,
    "limit": 50,
    "total_pages": 1,
    "timestamp": "2026-03-22T16:00:00.000Z"
  }
}

比赛状态值说明

状态值	含义
`scheduled`	未开赛
`live`	比赛进行中
`ht`	中场休息
`extra_time`	加时赛
`penalties`	点球大战
`finished`	已结束
`postponed`	延期
`cancelled`	取消

2. 实时比分接口（Livescore）

路径： GET /v1/livescore
所需套餐： Free 及以上

返回当前所有正在进行中的比赛，包含实时比分、当前分钟数、进球记录及比赛统计。数据与赛事接口结构一致，仅返回 live: true 的比赛。

查询参数

参数	类型	说明
`league_id`	string	按联赛过滤
`country_id`	string	按国家过滤
`match_id`	string	查询指定比赛实时数据
`lang`	string	响应语言，默认 `en`
`page` / `limit`	integer	分页

Python 示例

def get_livescore(league_id=None, country_id=None, match_id=None, lang='zh'):
    params = {'lang': lang}
    if league_id:  params['league_id'] = league_id
    if country_id: params['country_id'] = country_id
    if match_id:   params['match_id'] = match_id

    r = requests.get(f'{BASE_URL}/livescore', params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# 获取英超正在进行中的比赛
result = get_livescore(league_id='152', lang='zh')
for match in result['data']:
    print(f"{match['home']} {match['score']} {match['away']}（第 {match['minute']} 分钟）")

JSON 响应示例

{
  "success": true,
  "data": [
    {
      "match_id": 1626442,
      "date": "2026-03-22",
      "time": "15:15",
      "home": "阿斯顿维拉",
      "home_id": 3088,
      "home_badge": "https://api.anysport.io/images/team/3088",
      "away": "西汉姆联",
      "away_id": 3081,
      "away_badge": "https://api.anysport.io/images/team/3081",
      "ht_score": "1-0",
      "score": "1-0",
      "status": "live",
      "minute": "67",
      "live": true,
      "league": "英超",
      "league_id": 152,
      "league_round": "第31轮",
      "league_season": "2025/2026",
      "league_logo": "https://api.anysport.io/images/league/152",
      "country": "英格兰",
      "country_id": 44,
      "goals": [
        { "time": "15", "player": "J. McGinn", "player_id": 215174918, "type": "goal", "team": "home" }
      ],
      "cards": [],
      "subs": [],
      "stats": [
        { "type": "Ball Possession", "home": "55%", "away": "45%" }
      ],
      "lineups": null
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "timestamp": "2026-03-22T15:45:00.000Z"
  }
}

提示： 若需要最低延迟的实时推送，建议升级至 ProMax 套餐并使用 WebSocket 接口，而非轮询此 REST 端点。

3. 联赛数据接口（Leagues）

路径： GET /v1/leagues
所需套餐： Free 及以上

返回全球 900 余个足球联赛列表。league_id 是其他接口（赛事、积分榜、球队等）过滤参数的基础，建议在集成初期先调用此接口建立本地映射表。

查询参数

参数	类型	说明
`league_id`	string	查询指定联赛
`country_id`	string	查询指定国家的联赛
`page` / `limit`	integer	分页，`limit` 最大 200

Python 示例

def get_leagues(league_id=None, country_id=None, page=1, limit=50):
    params = {'page': page, 'limit': limit}
    if league_id:  params['league_id'] = league_id
    if country_id: params['country_id'] = country_id

    r = requests.get(f'{BASE_URL}/leagues', params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# 获取英格兰所有联赛（country_id=44）
result = get_leagues(country_id='44')
for league in result['data']:
    print(f"[{league['league_id']}] {league['league_name']}")

JSON 响应示例

{
  "success": true,
  "data": [
    {
      "league_id": 152,
      "league_name": "Premier League",
      "country_id": 44,
      "country_name": "England",
      "league_season": "2025/2026",
      "league_logo": "https://api.anysport.io/images/league/152",
      "league_badge": "https://api.anysport.io/images/league/152"
    },
    {
      "league_id": 302,
      "league_name": "La Liga",
      "country_id": 6,
      "country_name": "Spain",
      "league_season": "2025/2026",
      "league_logo": "https://api.anysport.io/images/league/302",
      "league_badge": "https://api.anysport.io/images/league/302"
    }
  ],
  "meta": {
    "total": 976,
    "page": 1,
    "limit": 50,
    "total_pages": 20,
    "timestamp": "2026-03-31T05:00:00.000Z"
  }
}

4. 国家/地区资料接口（Countries）

路径： GET /v1/countries
所需套餐： Free 及以上

返回系统支持的所有国家/地区列表，共约 176 个。country_id 可用于过滤联赛、实时比分等接口。

查询参数

参数	类型	说明
`page` / `limit`	integer	分页，`limit` 最大 200

Python 示例

def get_all_countries():
    # 约 176 个国家，设置 limit=200 一次全部获取
    r = requests.get(
        f'{BASE_URL}/countries',
        params={'limit': 200},
        headers=HEADERS
    )
    r.raise_for_status()
    return r.json()['data']

countries = get_all_countries()
# 建立名称到 ID 的查找表
country_map = {c['country_name']: c['country_id'] for c in countries}
print('England ID:', country_map.get('England'))  # 44

JSON 响应示例

{
  "success": true,
  "data": [
    {
      "country_id": 44,
      "country_name": "England",
      "country_logo": "https://api.anysport.io/images/country/44"
    },
    {
      "country_id": 6,
      "country_name": "Spain",
      "country_logo": "https://api.anysport.io/images/country/6"
    },
    {
      "country_id": 7,
      "country_name": "Italy",
      "country_logo": "https://api.anysport.io/images/country/7"
    }
  ],
  "meta": {
    "total": 184,
    "page": 1,
    "limit": 200,
    "timestamp": "2026-03-31T05:00:00.000Z"
  }
}

5. 积分榜接口（Standings）

路径： GET /v1/standings
所需套餐： Free 及以上

返回指定联赛的当前积分榜。响应包含三张独立积分表：总积分榜（total）、主场积分榜（home）、客场积分榜（away）。

查询参数

参数	类型	必填	说明
`league_id`	string	是	联赛 ID
`lang`	string	否	响应语言，默认 `en`

Python 示例

def get_standings(league_id, lang='zh'):
    r = requests.get(
        f'{BASE_URL}/standings',
        params={'league_id': league_id, 'lang': lang},
        headers=HEADERS
    )
    r.raise_for_status()
    return r.json()

result = get_standings('152', lang='zh')
total_table = result['data']['total']

print("=== 英超总积分榜 ===")
for row in total_table[:5]:  # 前5名
    print(
        f"{row['position']}. {row['team']}"
        f"  {row['played']}场 {row['wins']}胜{row['draws']}平{row['losses']}负"
        f"  {row['goals_for']}:{row['goals_against']}"
        f"  {row['points']}分"
    )

JSON 响应示例

{
  "success": true,
  "data": {
    "total": [
      {
        "position": 1,
        "position_type": "Promotion - Champions League (League phase)",
        "team": "阿森纳",
        "team_id": 141,
        "team_badge": "https://api.anysport.io/images/team/141",
        "played": 31,
        "wins": 21,
        "draws": 7,
        "losses": 3,
        "goals_for": 61,
        "goals_against": 22,
        "goal_difference": 39,
        "points": 70,
        "form": null,
        "league_id": 152,
        "league": "英超",
        "league_season": "2025/2026",
        "country": "英格兰",
        "updated_at": "2026-03-30 07:32:17"
      }
    ],
    "home": [
      {
        "position": 1,
        "team": "阿森纳",
        "team_id": 141,
        "played": 15,
        "wins": 12,
        "draws": 2,
        "losses": 1,
        "goals_for": 35,
        "goals_against": 9,
        "goal_difference": 26,
        "points": 38
      }
    ],
    "away": [
      {
        "position": 1,
        "team": "阿森纳",
        "team_id": 141,
        "played": 16,
        "wins": 9,
        "draws": 5,
        "losses": 2,
        "goals_for": 26,
        "goals_against": 13,
        "goal_difference": 13,
        "points": 32
      }
    ]
  },
  "meta": {
    "total": 20,
    "timestamp": "2026-03-31T05:00:00.000Z"
  }
}

6. 历史交锋接口（Head-to-Head）

路径： GET /v1/head2head
所需套餐： Free 及以上

查询两支球队的历史对阵记录，以及各自的近期赛事数据。响应包含三个列表：history（双方历史交锋）、team1_matches（队伍1近期赛事）、team2_matches（队伍2近期赛事）。

历史交锋数据为比赛摘要，不含进球/出牌/统计等详细事件。如需完整详情，请以 match_id 调用 /v1/matches。

查询参数

参数	类型	必填	说明
`team1_id`	string	是	第一支球队 ID
`team2_id`	string	是	第二支球队 ID
`lang`	string	否	响应语言，默认 `en`

Python 示例

def get_head2head(team1_id, team2_id, lang='zh'):
    r = requests.get(
        f'{BASE_URL}/head2head',
        params={'team1_id': team1_id, 'team2_id': team2_id, 'lang': lang},
        headers=HEADERS
    )
    r.raise_for_status()
    return r.json()

# 阿森纳（141）vs 热刺（164）历史交锋
result = get_head2head('141', '164', lang='zh')
history = result['data']['history']

print(f"历史交锋共 {len(history)} 场：")
for match in history:
    print(f"  {match['date']}  {match['home']} {match['score']} {match['away']}")

JSON 响应示例

{
  "success": true,
  "data": {
    "history": [
      {
        "match_id": 1626402,
        "date": "2026-02-22",
        "time": "17:30",
        "home": "热刺",
        "home_id": 164,
        "home_badge": "https://api.anysport.io/images/team/164",
        "away": "阿森纳",
        "away_id": 141,
        "away_badge": "https://api.anysport.io/images/team/141",
        "ht_score": "1-1",
        "score": "1-4",
        "status": "finished",
        "league": "英超",
        "league_id": 152,
        "league_round": "27",
        "country": "英格兰",
        "country_id": 44
      }
    ],
    "team1_matches": [
      {
        "match_id": 1759199,
        "date": "2026-03-17",
        "time": "21:00",
        "home": "阿森纳",
        "home_id": 141,
        "away": "拜耳勒沃库森",
        "away_id": 143,
        "ht_score": "1-0",
        "score": "2-0",
        "status": "finished",
        "league": "欧冠",
        "league_id": 3
      }
    ],
    "team2_matches": [
      {
        "match_id": 1626439,
        "date": "2026-03-22",
        "home": "热刺",
        "home_id": 164,
        "away": "诺丁汉森林",
        "away_id": 3089,
        "score": "0-3",
        "status": "finished",
        "league": "英超",
        "league_id": 152
      }
    ]
  },
  "meta": {
    "total": 10,
    "timestamp": "2026-03-31T05:00:00.000Z"
  }
}

7. 球队资料接口（Teams）

路径： GET /v1/teams
所需套餐： Basic 及以上

返回球队详情，包含球员名单、场馆信息和教练团队。全球超过 15,000 支球队可查。

查询参数

参数	类型	说明
`team_id`	string	按 ID 查询指定球队
`league_id`	string	查询联赛内所有球队
`team_name`	string	按名称模糊搜索（不区分大小写）
`lang`	string	响应语言，默认 `en`

建议至少提供 team_id、league_id、team_name 其中一个参数，否则响应数据量可能非常大。

Python 示例

def get_teams(team_id=None, league_id=None, team_name=None, lang='zh'):
    params = {'lang': lang}
    if team_id:   params['team_id'] = team_id
    if league_id: params['league_id'] = league_id
    if team_name: params['team_name'] = team_name

    r = requests.get(f'{BASE_URL}/teams', params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# 查询阿森纳球队详情（team_id=141）
result = get_teams(team_id='141', lang='zh')
team = result['data'][0]
print(f"球队：{team['team_name']}  成立：{team.get('team_founded', 'N/A')}")
print(f"主场：{team.get('venue', {}).get('venue_name', 'N/A')}")
print(f"主教练：{team['coaches'][0]['coach_name'] if team['coaches'] else 'N/A'}")
print(f"注册球员：{len(team['players'])} 人")

JSON 响应示例

{
  "success": true,
  "data": [
    {
      "team_id": 141,
      "team_name": "阿森纳",
      "team_country": "英格兰",
      "team_founded": 1886,
      "team_badge": "https://api.anysport.io/images/team/141",
      "venue": {
        "venue_name": "酋长球场",
        "venue_address": "Highbury House, 75 Drayton Park",
        "venue_city": "London",
        "venue_capacity": 60704,
        "venue_surface": "grass"
      },
      "coaches": [
        { "coach_name": "Mikel Arteta", "coach_country": "Spain", "coach_age": 42 }
      ],
      "players": [
        {
          "player_id": 1058876140,
          "player_name": "本·怀特",
          "player_age": 28,
          "player_birthdate": "1997-10-08",
          "player_type": "后卫",
          "player_number": "4",
          "player_goals": "1",
          "player_assists": "3",
          "player_yellow_cards": "2",
          "player_red_cards": "0",
          "player_image": "https://api.anysport.io/images/player/1058876140"
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "total_pages": 1,
    "timestamp": "2026-03-31T05:00:00.000Z"
  }
}

8. 球员资料接口（Players）

路径： GET /v1/players
所需套餐： Basic 及以上

返回球员详细资料，包含基础信息、位置、本赛季进球/助攻/黄红牌等统计数据。

查询参数

参数	类型	说明
`player_id`	string	按 ID 查询指定球员
`team_id`	string	查询球队全部球员
`player_name`	string	按姓名模糊搜索（仅支持英文名）
`lang`	string	响应语言，默认 `en`

player_id、team_id、player_name 三者至少需要提供一个。

Python 示例

def get_players(player_id=None, team_id=None, player_name=None, lang='zh'):
    params = {'lang': lang}
    if player_id:   params['player_id'] = player_id
    if team_id:     params['team_id'] = team_id
    if player_name: params['player_name'] = player_name

    r = requests.get(f'{BASE_URL}/players', params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# 获取阿森纳全队球员（team_id=141）
result = get_players(team_id='141', lang='zh')
for player in result['data']:
    print(
        f"[{player['player_id']}] {player['player_name']}"
        f"  #{player['player_number']}"
        f"  {player.get('player_type', '')}"
        f"  评分 {player.get('player_match_rating', 'N/A')}"
    )

JSON 响应示例

{
  "success": true,
  "data": [
    {
      "player_id": 353204575,
      "player_name": "德克兰·赖斯",
      "player_age": 26,
      "player_birthdate": "1999-01-14",
      "player_type": "中场",
      "player_number": "41",
      "player_match_rating": 7.2,
      "player_goals": "5",
      "player_assists": "8",
      "player_yellow_cards": "4",
      "player_red_cards": "0",
      "player_minutes_played": "2340",
      "player_image": "https://api.anysport.io/images/player/353204575",
      "team_id": 141,
      "team_name": "阿森纳"
    },
    {
      "player_id": 1058876140,
      "player_name": "本·怀特",
      "player_age": 28,
      "player_birthdate": "1997-10-08",
      "player_type": "后卫",
      "player_number": "4",
      "player_match_rating": 6.85,
      "player_assists": 1,
      "player_yellow_cards": 0,
      "player_red_cards": 0,
      "player_image": "https://api.anysport.io/images/player/1058876140",
      "team_id": 141,
      "team_name": "阿森纳"
    }
  ],
  "meta": {
    "total": 27,
    "timestamp": "2026-03-31T05:00:00.000Z"
  }
}

9. 射手榜接口（Top Scorers）

路径： GET /v1/topscorers
所需套餐： Basic 及以上

返回指定联赛本赛季的进球排行榜，包含进球数、助攻数及点球数。

查询参数

参数	类型	必填	说明
`league_id`	string	是	联赛 ID
`lang`	string	否	响应语言，默认 `en`

Python 示例

def get_top_scorers(league_id, lang='zh'):
    r = requests.get(
        f'{BASE_URL}/topscorers',
        params={'league_id': league_id, 'lang': lang},
        headers=HEADERS
    )
    r.raise_for_status()
    return r.json()

# 英超射手榜
result = get_top_scorers('152', lang='zh')
print("=== 英超射手榜 ===")
for p in result['data']:
    assists = p['assists'] if p['assists'] is not None else 0
    penalty = p['penalty_goals']
    print(
        f"#{p['rank']} {p['player_name']}（{p['team_name']}）"
        f"  {p['goals']} 球（含点球 {penalty}）  {assists} 助攻"
    )

JSON 响应示例

{
  "success": true,
  "data": [
    {
      "rank": 1,
      "player_id": 302850,
      "player_name": "欧文·哈兰德",
      "team_name": "曼城",
      "team_id": 50,
      "goals": 27,
      "assists": 5,
      "penalty_goals": 4
    },
    {
      "rank": 2,
      "player_id": 289140,
      "player_name": "穆罕默德·萨拉赫",
      "team_name": "利物浦",
      "team_id": 40,
      "goals": 24,
      "assists": 13,
      "penalty_goals": 2
    },
    {
      "rank": 3,
      "player_id": 325952,
      "player_name": "科尔·帕尔默",
      "team_name": "切尔西",
      "team_id": 49,
      "goals": 20,
      "assists": 10,
      "penalty_goals": 5
    }
  ],
  "meta": {
    "total": 20,
    "timestamp": "2026-04-01T08:00:00.000Z"
  }
}

部分联赛不统计助攻数据，assists 字段可能返回 null。

10. 阵容接口（Lineups）

路径： GET /v1/lineups
所需套餐： Basic 及以上

返回指定比赛两支球队的首发阵容（11 人）、替补名单、教练团队及缺阵球员。阵容通常在开球前 60～30 分钟公布；未公布时 data 字段返回 null。

查询参数

参数	类型	必填	说明
`match_id`	string	是	比赛 ID
`lang`	string	否	响应语言，支持 `en`、`zh`、`ja`、`ko`、`th`

Python 示例

def get_lineups(match_id, lang='zh'):
    r = requests.get(
        f'{BASE_URL}/lineups',
        params={'match_id': match_id, 'lang': lang},
        headers=HEADERS
    )
    r.raise_for_status()
    return r.json()

result = get_lineups('1738679', lang='zh')

if result['data'] is None:
    print('阵容尚未公布')
else:
    home = result['data']['home']
    away = result['data']['away']

    print(f"主队首发（阵型：{home.get('formation', 'N/A')}）：")
    for p in home['starting_lineups']:
        captain_mark = '（C）' if p['player_captain'] else ''
        print(f"  {p['player_number']}. {p['player_name']}{captain_mark}")

    print(f"\n客队首发（阵型：{away.get('formation', 'N/A')}）：")
    for p in away['starting_lineups']:
        print(f"  {p['player_number']}. {p['player_name']}")

JSON 响应示例

{
  "success": true,
  "data": {
    "home": {
      "formation": "4-3-3",
      "starting_lineups": [
        {
          "player_id": 3446405013,
          "player_name": "大卫·拉亚",
          "player_number": 1,
          "player_position": 1,
          "player_captain": false,
          "player_substitute": false
        },
        {
          "player_id": 353204575,
          "player_name": "德克兰·赖斯",
          "player_number": 41,
          "player_position": 6,
          "player_captain": false,
          "player_substitute": false
        }
      ],
      "substitutes": [
        {
          "player_id": 1818970307,
          "player_name": "加布里埃尔·马蒂内利",
          "player_number": 11,
          "player_position": 0,
          "player_captain": false,
          "player_substitute": true
        }
      ],
      "coaches": [
        {
          "player_id": 0,
          "player_name": "Mikel Arteta",
          "player_country": null,
          "player_captain": false,
          "player_substitute": false
        }
      ],
      "missing_players": []
    },
    "away": {
      "formation": "4-4-2",
      "starting_lineups": [],
      "substitutes": [],
      "coaches": [],
      "missing_players": []
    }
  },
  "meta": {
    "timestamp": "2026-03-31T05:00:00.000Z"
  }
}

11. 赔率接口（Odds）

路径： GET /v1/odds
所需套餐： Pro 及以上

返回即将进行或已结束比赛的赛前博彩赔率，涵盖多家博彩公司、多个投注市场（独赢 1X2、大小球、亚盘、双方进球等）。

查询参数

参数	类型	说明
`match_id`	string	查询指定比赛赔率
`league_id`	string	查询联赛内所有比赛赔率
`from` / `to`	string	日期范围（`YYYY-MM-DD`）

Python 示例

def get_odds(match_id=None, league_id=None, from_date=None, to_date=None):
    params = {}
    if match_id:  params['match_id']  = match_id
    if league_id: params['league_id'] = league_id
    if from_date: params['from']       = from_date
    if to_date:   params['to']         = to_date

    r = requests.get(f'{BASE_URL}/odds', params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# 查询指定比赛的赔率
result = get_odds(match_id='1626433')
for match_odds in result['data']:
    print(f"比赛 ID: {match_odds['match_id']}")
    for bk in match_odds['bookmakers']:
        print(f"  {bk['bookmaker_name']}:")
        for market in bk['markets']:
            odds_str = ', '.join(
                f"{o['value']} @ {o['odd']}" for o in market['odds']
            )
            print(f"    [{market['market_name']}] {odds_str}")

JSON 响应示例

{
  "success": true,
  "data": [
    {
      "match_id": 1626433,
      "bookmakers": [
        {
          "bookmaker_id": 0,
          "bookmaker_name": "bet365",
          "markets": [
            {
              "market_name": "1X2",
              "odds": [
                { "value": "Home", "odd": 1.38 },
                { "value": "Draw", "odd": 4.75 },
                { "value": "Away", "odd": 8.0 }
              ]
            },
            {
              "market_name": "Over/Under",
              "odds": [
                { "value": "Over", "odd": 2.0, "handicap": "2.5" },
                { "value": "Under", "odd": 1.8, "handicap": "2.5" }
              ]
            },
            {
              "market_name": "Both Teams Score",
              "odds": [
                { "value": "Yes", "odd": 2.25 },
                { "value": "No", "odd": 1.57 }
              ]
            }
          ]
        },
        {
          "bookmaker_id": 0,
          "bookmaker_name": "WilliamHill",
          "markets": [
            {
              "market_name": "Asian Handicap",
              "odds": [
                { "value": "Home", "odd": 2.2, "handicap": "-1.5" },
                { "value": "Away", "odd": 1.65, "handicap": "-1.5" }
              ]
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "timestamp": "2026-03-31T05:00:00.000Z"
  }
}

12. 实时赔率接口（Live Odds）

路径： GET /v1/odds/live
所需套餐： Pro 及以上

返回正在进行中比赛的盘中实时赔率，随比赛进程持续更新。响应结构与赛前赔率接口相同。

查询参数

参数	类型	说明
`match_id`	string	查询指定比赛的实时赔率；不传则返回当前所有可用实时赔率

Python 示例

def get_live_odds(match_id=None):
    params = {}
    if match_id: params['match_id'] = match_id

    r = requests.get(f'{BASE_URL}/odds/live', params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# 轮询指定比赛的实时赔率（每 30 秒一次）
import time

match_id = '1626442'
while True:
    result = get_live_odds(match_id=match_id)
    for match_odds in result['data']:
        for bk in match_odds['bookmakers']:
            for market in bk['markets']:
                if market['market_name'] == '1X2':
                    odds = {o['value']: o['odd'] for o in market['odds']}
                    print(f"[{bk['bookmaker_name']}] 主胜 {odds.get('Home')} / 平 {odds.get('Draw')} / 客胜 {odds.get('Away')}")
    time.sleep(30)

JSON 响应示例

{
  "success": true,
  "data": [
    {
      "match_id": 1626442,
      "bookmakers": [
        {
          "bookmaker_id": 0,
          "bookmaker_name": "bet365",
          "markets": [
            {
              "market_name": "1X2",
              "odds": [
                { "value": "Home", "odd": 1.25 },
                { "value": "Draw", "odd": 5.5 },
                { "value": "Away", "odd": 11.0 }
              ]
            },
            {
              "market_name": "Over/Under",
              "odds": [
                { "value": "Over", "odd": 3.5, "handicap": "2.5" },
                { "value": "Under", "odd": 1.28, "handicap": "2.5" }
              ]
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "timestamp": "2026-03-31T05:00:00.000Z"
  }
}

实时赔率在比赛期间变动频繁，建议每 30～60 秒轮询一次。

13. 胜负概率接口（Probabilities）

路径： GET /v1/probabilities
所需套餐： Pro 及以上

返回比赛的赛前概率预测数据，涵盖胜/平/负概率、进球大小球概率、双方均进球概率，以及多个亚盘让球线下的获胜概率。

查询参数

参数	类型	说明
`match_id`	string	查询指定比赛
`league_id`	string	查询联赛内所有比赛（须配合 `from` / `to`）
`country_id`	string	查询国家内所有比赛（须配合 `from` / `to`）
`from` / `to`	string	日期范围（使用 `league_id` 或 `country_id` 时必填）

Python 示例

def get_probabilities(match_id=None, league_id=None, country_id=None,
                      from_date=None, to_date=None):
    params = {}
    if match_id:   params['match_id']   = match_id
    if league_id:  params['league_id']  = league_id
    if country_id: params['country_id'] = country_id
    if from_date:  params['from']        = from_date
    if to_date:    params['to']          = to_date

    r = requests.get(f'{BASE_URL}/probabilities', params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# 查询单场比赛概率
result = get_probabilities(match_id='1626433')
for m in result['data']:
    print(f"{m['home']} vs {m['away']}  ({m['date']})")
    print(f"  胜负：主胜 {m['home_win']}%  平 {m['draw']}%  客胜 {m['away_win']}%")
    print(f"  大小球：大2.5 {m['over_2_5']}%  小2.5 {m['under_2_5']}%")
    print(f"  双方进球：{m['bts']}%  仅一方进球：{m['ots']}%")

    print("  亚盘：")
    for ah in m.get('asian_handicap', []):
        sign = '+' if ah['home_handicap'] > 0 else ''
        print(f"    主队{sign}{ah['home_handicap']}  主 {ah['home']}% / 客 {ah['away']}%")

JSON 响应示例

{
  "success": true,
  "data": [
    {
      "match_id": 1626433,
      "date": "2026-03-22",
      "home": "Arsenal",
      "home_id": 141,
      "away": "Everton",
      "away_id": 48,
      "home_win": 62.5,
      "draw": 20.8,
      "away_win": 16.7,
      "home_win_or_draw": 83.3,
      "away_win_or_draw": 37.5,
      "home_or_away_win": 79.2,
      "over_1_5": 81.3,
      "under_1_5": 18.7,
      "over_2_5": 56.3,
      "under_2_5": 43.7,
      "over_3_5": 31.2,
      "under_3_5": 68.8,
      "bts": 46.9,
      "ots": 53.1,
      "asian_handicap": [
        { "home_handicap": -1.5, "home": 81.3, "away": 18.7 },
        { "home_handicap": -0.5, "home": 62.5, "away": 37.5 },
        { "home_handicap": 0.5,  "home": 43.8, "away": 56.2 },
        { "home_handicap": 1.5,  "home": 18.7, "away": 81.3 }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "timestamp": "2026-03-31T05:00:00.000Z"
  }
}

所有概率字段均为百分比（0–100）。null 表示该市场暂无数据。

错误处理

所有接口在请求失败时返回标准错误结构：

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

常见错误码：

HTTP 状态码	错误码	说明
401	`UNAUTHORIZED`	API Key 无效或缺失
403	`PLAN_REQUIRED`	当前套餐不支持此接口
429	`RATE_LIMIT_EXCEEDED`	请求频率超出套餐限制
400	`MISSING_PARAM`	缺少必要参数
400	`MISSING_DATE_RANGE`	使用 `league_id` / `country_id` 过滤概率数据时未传日期范围

Python 统一错误处理示例：

def safe_request(url, params=None):
    r = requests.get(url, params=params, headers=HEADERS)
    data = r.json()

    if not data.get('success'):
        error = data.get('error', {})
        raise RuntimeError(f"API Error [{error.get('code')}]: {error.get('message')}")

    return data

套餐与接口权限

接口	Free	Basic	Pro	ProMax
赛事、实时比分、联赛、国家、积分榜、历史交锋	✓	✓	✓	✓
球队、球员、射手榜、阵容	—	✓	✓	✓
赔率、实时赔率、胜负概率	—	—	✓	✓
WebSocket 实时推送	—	—	—	✓

套餐详情及价格请参阅定价方案。

常用 ID 速查

以下是部分主流联赛的 ID，可直接用于接口过滤参数：

联赛	`league_id`	国家
英超 Premier League	152	英格兰（44）
西甲 La Liga	302	西班牙（6）
德甲 Bundesliga	175	德国（3）
意甲 Serie A	207	意大利（7）
法甲 Ligue 1	168	法国（2）
欧冠 Champions League	3	—

完整联赛列表通过 /v1/leagues 接口获取。

如果您对AnySport API的足球数据接口仍有疑问，欢迎随时联系我们的客服：

联系客服Telegram：https://t.me/anysport_support

客服邮箱：[email protected]

实时足球数据接口

覆盖全球900+联赛
实时比分
实时赔率
球队/球员资料
多语言支持
专为开发者设计
WebSocket毫秒级推送

足球数据接口完整使用指南

话题目录

准备工作

认证方式

基础 URL

多语言支持

Python 通用配置

接口一览

1. 赛事接口（Matches）

查询参数

Python 示例

JSON 响应示例

比赛状态值说明

2. 实时比分接口（Livescore）

查询参数

Python 示例

JSON 响应示例

3. 联赛数据接口（Leagues）

查询参数

Python 示例

JSON 响应示例

4. 国家/地区资料接口（Countries）

查询参数

Python 示例

JSON 响应示例

5. 积分榜接口（Standings）

查询参数

Python 示例

JSON 响应示例

6. 历史交锋接口（Head-to-Head）

查询参数

Python 示例

JSON 响应示例

7. 球队资料接口（Teams）

查询参数

Python 示例

JSON 响应示例

8. 球员资料接口（Players）

查询参数

Python 示例

JSON 响应示例

9. 射手榜接口（Top Scorers）

查询参数

Python 示例

JSON 响应示例

10. 阵容接口（Lineups）

查询参数

Python 示例

JSON 响应示例

11. 赔率接口（Odds）

查询参数

Python 示例

JSON 响应示例

12. 实时赔率接口（Live Odds）

查询参数

Python 示例

JSON 响应示例

13. 胜负概率接口（Probabilities）

查询参数

Python 示例

JSON 响应示例

错误处理

套餐与接口权限

常用 ID 速查

实时足球数据接口