ESPN Fantasy API X-Fantasy-Filter头部嵌套字段过滤方法咨询

核心逻辑：ESPN Fantasy API的X-Fantasy-Filter请求头原生支持通过点分隔的嵌套路径定位深层JSON字段。顶层字段（比如status）可以省略field参数直接配置过滤规则，深层嵌套字段需要在过滤规则中显式指定field参数，值为点分隔的完整嵌套路径。

常用过滤场景配置示例 #

1. 过滤draftRanksByRankType.STANDARD.auctionValue字段 #

比如筛选标准排名下拍卖价值大于等于30的球员，新增的过滤规则如下：

"filterAuctionValue": {
    "value": 30,
    "operator": "gte",
    "field": "player.draftRanksByRankType.STANDARD.auctionValue"
}

2. 过滤statSplitTypeId字段 #

statSplitTypeId一般嵌套在player.stats路径下，用于筛选特定统计周期/类型的球员数据，比如筛选常规赛（statSplitTypeId=1）的统计数据：

"filterStatSplitType": {
    "value": [1],
    "field": "player.stats.statSplitTypeId"
}

完整请求配置示例 #

推荐用Python的json.dumps生成过滤规则字符串，避免手动转义字符出错：

import json
import requests

# 构造完整过滤规则
filter_rule = {
    "players": {
        # 原有状态过滤逻辑
        "filterStatus": {"value": ["FREEAGENT", "WAIVERS", "ONTEAM"]},
        # 新增：拍卖价值≥30过滤
        "filterAuctionValue": {
            "value": 30,
            "operator": "gte",
            "field": "player.draftRanksByRankType.STANDARD.auctionValue"
        },
        # 新增：统计类型过滤
        "filterStatSplitType": {
            "value": [1],
            "field": "player.stats.statSplitTypeId"
        },
        # 原有按持有率倒序排序
        "sortPercOwned": {"sortAsc": False, "sortPriority": 1}
    }
}

headers = {
    'X-Fantasy-Filter': json.dumps(filter_rule)
}

# 发起请求
url = "https://fantasy.espn.com/apis/v3/games/fba/seasons/2022/segments/0/leagues/1747675438?view=kona_player_info"
response = requests.get(url, headers=headers)

注意事项 #

• 支持的操作符包括：gte（大于等于）、lte（小于等于）、eq（等于）、ne（不等于）、in（匹配列表内任意值）
• 字段路径需要和接口返回的JSON结构完全对应，大小写敏感
• 多过滤条件默认取交集，即返回同时满足所有规则的球员数据

内容的提问来源于stack exchange，提问作者Colin S.