Guide

Rank fantasy playoff schedules with matchup history

Quick answer: Sweep /players for each position you roster (two to six requests each) and /schedule once for the Week 15–17 opponents, total what every defense allowed to that position this season, add each player's own vs_opponent history at half weight, and sum Weeks 15–17. Then use the score as a tiebreaker: in 2025, points allowed through Week 12 barely predicted the fantasy playoffs (correlation −0.17 to +0.23 by position).

Requests
2–6 per position + 1
Plan
Basic
Weeks scored
15–17
2025 RB correlation
−0.17
Watch it run: the script below scores two running backs on their real Week 15-17 opponents, with stats through Week 10 of the 2026 season (1:02, with captions). Also on YouTube.

What makes a fantasy playoff schedule "easy"?

Two things, and people usually blend them. The first is the defense: how many PPR points it has given up to your player's position per game this season. The second is the player's own history against that team, which the API keeps for every opponent on vs_opponent.

Both are real data. Both are also noisier than the tidy green-yellow-red schedule grids suggest, and we'll show exactly how noisy with 2025's numbers. The goal of this guide is a score you can compute in a minute and trust for what it is: a way to break a tie between two players you already like about equally.

Where do the Week 15–17 opponents come from?

From the API. /schedule returns the whole regular season, played and unplayed games alike, and one request covers all 18 weeks. Fantasy playoffs are Weeks 15, 16 and 17 in most leagues, so the script reads those three weeks into a (team, week) → opponent lookup. Each player's team comes from his /players row, so the only thing you type in is the list of players:

ROSTER = ["Jaylen Warren#RB", "Chase Brown#RB"]

If your league runs its playoffs in Weeks 14–16 or 16–18, change PLAYOFF_WEEKS. A team on bye in one of those weeks shows as a bye and scores nothing that week.

One data detail to know: team codes come in two spellings in older rows. The Rams appear as both LA and LAR, and Washington as both WAS and WSH. The script folds them together. Skip that and a player's history against the Rams is split into two half-sized samples.

How do I score a playoff schedule in Python?

The script reads the season's schedule once, then sweeps /players once per position on your roster. From those rows it builds points allowed per defense per game, then reads each rostered player's vs_opponent block, which is already in the same response, so history costs no extra requests.

import os
from collections import defaultdict
import requests

API = "https://api.gridirondata.com/api/v1"
H = {"x-api-key": os.environ.get("GRIDIRON_API_KEY", "YOUR_KEY")}
SEASON = "2026"
PLAYOFF_WEEKS = (15, 16, 17)
ALIASES = {"LA": "LAR", "WSH": "WAS", "JAC": "JAX"}   # one spelling per team
canon = lambda t: ALIASES.get((t or "").upper(), (t or "").upper())

# The players you're deciding between. Their teams and fantasy-playoff
# opponents come from the API.
ROSTER = ["Jaylen Warren#RB", "Chase Brown#RB"]

def get(path, **params):
    r = requests.get(f"{API}{path}", headers=H, params=params, timeout=60)
    r.raise_for_status()
    return r.json()

def sweep(position):
    out, cursor = [], None
    while True:
        body = get("/players", position=position, limit=100, **({"cursor": cursor} if cursor else {}))
        out += body["players"]
        cursor = body.get("next_cursor")
        if not cursor:
            return out

def ppr(row):
    for k in ("fantasy_points_ppr", "points", "fantasy_points"):
        if row and row.get(k) is not None:
            return float(row[k])
    return None

# 0) Who each team plays in Weeks 15-17: one /schedule request for the season.
opponent = {}                                       # (team, week) -> opponent
for g in get("/schedule", season=SEASON)["games"]:
    if g["week"] in PLAYOFF_WEEKS:
        home, away = canon(g["home"]), canon(g["away"])
        opponent[home, g["week"]], opponent[away, g["week"]] = away, home

positions = {pid.split("#")[1] for pid in ROSTER}
players = {p["player_id"]: p for pos in positions for p in sweep(pos)}   # 2-6 requests per position

# 1) Fantasy points allowed: what each defense gave up to this position, per game.
allowed = defaultdict(lambda: defaultdict(lambda: defaultdict(float)))  # pos -> def -> week -> pts
for p in players.values():
    for wk, row in (p["seasons"].get(SEASON, {}).get("weekly_stats") or {}).items():
        pts = ppr(row)
        if pts is not None and row.get("opponent"):
            allowed[p["position"]][canon(row["opponent"])][int(wk)] += pts
fpa = {pos: {d: sum(w.values()) / len(w) for d, w in defs.items()} for pos, defs in allowed.items()}
league = {pos: sum(v.values()) / len(v) for pos, v in fpa.items()}

# 2) The player's own history against each opponent (vs_opponent, merged
#    across spellings, 2+ games only), relative to his career average.
def history(p):
    merged = defaultdict(lambda: [0.0, 0.0])            # opp -> [games, total]
    for opp, s in (p.get("vs_opponent") or {}).items():
        merged[canon(opp)][0] += s.get("games_played") or 0
        merged[canon(opp)][1] += s.get("total_actual") or 0
    games = sum(g for g, _ in merged.values())
    career = sum(t for _, t in merged.values()) / games if games else None
    return {o: t / g - career for o, (g, t) in merged.items() if g >= 2 and career is not None}

for pid in ROSTER:
    p, pos = players[pid], pid.split("#")[1]
    team = canon(p["seasons"].get(SEASON, {}).get("team") or p.get("team"))
    hist = history(p)
    total = 0.0
    print(f"{p['player_name']} ({pos}, {team})")
    for wk in PLAYOFF_WEEKS:
        opp = opponent.get((team, wk))
        if not opp:
            print(f"  Wk {wk}: bye")
            continue
        d_edge = fpa[pos].get(opp, league[pos]) - league[pos]
        h_edge = hist.get(opp)
        total += d_edge + (h_edge or 0) / 2               # history counts half: small samples
        h_txt = "no history" if h_edge is None else f"history {h_edge:+.1f}"
        print(f"  Wk {wk} vs {opp}: defense {d_edge:+.1f} PPR vs avg, {h_txt}")
    print(f"  playoff schedule score {total:+.1f}\n")

The defense edge is "points allowed to this position per game, minus the league average". The history edge is "his average against this team, minus his average against everyone", and only when he has two or more games against them. History counts half, because a two-game sample is closer to an anecdote than a rate.

What does the output look like?

A real run on November 20, 2026, with stats through Week 10 plus Thursday night's Week 11 game. The Week 15–17 opponents are the actual 2026 schedule from /schedule, and every number next to them comes from the API:

Jaylen Warren (RB, PIT)
  Wk 15 vs BAL: defense -2.0 PPR vs avg, history -0.7
  Wk 16 vs CAR: defense +5.2 PPR vs avg, no history
  Wk 17 vs TEN: defense -0.5 PPR vs avg, no history
  playoff schedule score +2.4

Chase Brown (RB, CIN)
  Wk 15 vs CAR: defense +5.2 PPR vs avg, no history
  Wk 16 vs IND: defense +2.3 PPR vs avg, no history
  Wk 17 vs BAL: defense -2.0 PPR vs avg, history -0.4
  playoff schedule score +5.3

Read it like this: Carolina has given up about 5 more PPR points per game to running backs than the league average, and both backs draw the Panthers once. Brown adds Indianapolis (about 2 points soft); Warren gets Tennessee, close to average. Baltimore is about 2 points tougher than average for both, and neither back's history against the Ravens moves the needle. Brown's slate scores about 3 points better over three weeks, roughly one point a game. That is the size of edge this score usually finds, and as the next section shows, it's a tiebreaker, not a reason to trade.

Does playoff schedule strength actually predict anything?

We tested it on 2025, the way you'd have used it: points allowed per game through Week 12 (the usual trade deadline window) against what the same defenses allowed in Weeks 15–17.

import os, statistics
from collections import defaultdict
import requests

API = "https://api.gridirondata.com/api/v1"
H = {"x-api-key": os.environ.get("GRIDIRON_API_KEY", "YOUR_KEY")}
ALIASES = {"LA": "LAR", "WSH": "WAS", "JAC": "JAX"}
canon = lambda t: ALIASES.get((t or "").upper(), (t or "").upper())

def sweep(position):
    out, cursor = [], None
    while True:
        params = {"position": position, "limit": 100, **({"cursor": cursor} if cursor else {})}
        body = requests.get(f"{API}/players", headers=H, params=params, timeout=60).json()
        out += body["players"]
        cursor = body.get("next_cursor")
        if not cursor:
            return out

def ppr(row):
    for k in ("fantasy_points_ppr", "points", "fantasy_points"):
        if row and row.get(k) is not None:
            return float(row[k])
    return None

def allowed(players, season, weeks):
    per = defaultdict(lambda: defaultdict(float))            # def -> week -> pts
    for p in players:
        for wk, row in (p["seasons"].get(season, {}).get("weekly_stats") or {}).items():
            if int(wk) in weeks and row.get("opponent") and ppr(row) is not None:
                per[canon(row["opponent"])][int(wk)] += ppr(row)
    return {d: sum(w.values()) / len(w) for d, w in per.items()}

for pos in ("QB", "RB", "WR", "TE"):
    players = sweep(pos)
    before = allowed(players, "2025", range(1, 13))          # what you knew at the deadline
    during = allowed(players, "2025", range(15, 18))         # the fantasy playoffs
    teams = sorted(set(before) & set(during), key=lambda d: -before[d])
    r = statistics.correlation([before[d] for d in teams], [during[d] for d in teams])
    soft, tough = teams[:8], teams[-8:]
    print(f"{pos}: r = {r:+.2f}   8 softest defenses allowed "
          f"{statistics.mean(during[d] for d in soft):.1f}/game in weeks 15-17, "
          f"8 toughest {statistics.mean(during[d] for d in tough):.1f}")

The result, straight from the API:

QB: r = +0.23   8 softest defenses allowed 19.9/game in weeks 15-17, 8 toughest 16.8
RB: r = -0.17   8 softest defenses allowed 21.1/game in weeks 15-17, 8 toughest 26.0
WR: r = +0.01   8 softest defenses allowed 29.0/game in weeks 15-17, 8 toughest 30.7
TE: r = +0.07   8 softest defenses allowed 13.3/game in weeks 15-17, 8 toughest 13.1

That's close to nothing. At running back the relationship ran slightly backwards: the eight defenses that looked softest through Week 12 allowed 21.1 PPR per game to backs in the fantasy playoffs, and the eight toughest allowed 26.0. At wide receiver and tight end the soft and tough groups finished within two points of each other. Quarterback was the only position with a modest signal (+0.23), and the gap between the soft and tough groups there was 3.1 points a game.

Why so weak? Defenses change over a season: injuries in the secondary, a coordinator adjusting, a team that stops trying. Twelve weeks of points allowed also depend on which offenses a defense happened to face. By December, the schedule you're reading is partly a record of September.

So how should I use the score?

  • As a tiebreaker. When two players have similar roles (check their snap share first: the snap share guide shows how), take the one with the better score.
  • Not as a trade driver. Don't move a workhorse back for a lesser player because of three matchups. Role predicts playoff points far better than opponent does.
  • Weight QB matchups a little more. Quarterback was the one position with a positive 2025 signal, so a streaming QB decision is where schedule earns its keep. For weekly streaming by matchup, see stream by matchup history.
  • Re-run it before each playoff week. Stats land at about 11:00 am ET the day after games, so Tuesday's run has the latest points allowed.

How many requests does this cost?

Two to six per position you roster, plus one /schedule request for the season: quarterbacks fit in 2 pages of 100, running backs and tight ends take 4 each, and wide receivers 6. A running-back-only run is 5 requests, and all four skill positions for the backtest is 16. Both run on Basic ($9/month, 5,000 requests a month), and history costs no extra requests because it rides along on the /players rows. On the free plan /players returns profiles only, without the weekly rows or vs_opponent history. If you'd rather query one player against one team, /matchups/{player_id}/{opponent} returns that player-versus-team history as a single call. Its response also carries projection fields, so leave those out of anything you publish. More walkthroughs are in the guides, and every endpoint is in the API reference.

Frequently asked questions

Does the API include the NFL schedule?

Yes. /schedule returns every regular-season game for a season, played or not, with week, home and away teams and kickoff time (Basic and above). One request covers the whole season, so the script looks up Weeks 15 to 17 itself.

How predictive is fantasy points allowed?

Less than most rankings imply. In 2025, what a defense allowed through Week 12 correlated with what it allowed in Weeks 15 to 17 at between -0.17 and +0.23 depending on position. Use it as a tiebreaker.

Why does the script count matchup history at half weight?

Because the samples are tiny. Most player-versus-team histories are two to six games spread over several seasons, often with a different quarterback or coordinator on one side.

How many requests does it use?

Two to six per position you roster (quarterbacks fit in 2 pages of 100, wide receivers take 6), because each player row carries its own weekly stats and vs_opponent history, plus one /schedule request for the season. A running-back-only run is 5; the four-position backtest is 16.