Stream by Matchup History

Streaming a defense, kicker, or QB each week? Don't guess. Rank your free-agent candidates by how they've actually performed against the opponent they face this week — the matchup is half the points.

What you'll build: give the script a few streamer candidates and the opponent each one draws this week; it returns them ranked by historical points against that opponent.

Watch it run: the script below ranks three streaming defenses by their history against this week's opponent (0:55, with captions). Also on YouTube.

Endpoints used

GET/api/v1/matchups/{player_id}/{opponent} — a player's historical splits vs a specific team

1. Pull a head-to-head split

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/matchups/Josh%20Allen%23QB/KC"

{
  "player_id": "Josh Allen#QB",
  "player_name": "Josh Allen",
  "position": "QB",
  "team": "BUF",
  "opponent": "KC",
  "stats": {
    "games_played": 6,
    "avg_actual": 24.8,
    "total_actual": 148.6,
    "avg_projected": 22.1,
    "avg_deviation": 2.7,
    "by_season": { "2025": { "games_played": 2, "avg_actual": 26.3 } }
  }
}

avg_actual is average PPR fantasy points against that opponent, and games_played is how many meetings it covers; by_season splits both by year.

2. List candidates + this week's opponent

For a defense, the player_id is the full team name (e.g. Houston Texans#DST). Pair each candidate with the team they face this week — in-season you can read that from each team's weekly schedule.

# (candidate player_id, opponent they face this week)
CANDIDATES = [
    ("Houston Texans#DST", "TEN"),
    ("Minnesota Vikings#DST", "CHI"),
    ("Pittsburgh Steelers#DST", "CLE"),
]

3. The full script

import requests
from urllib.parse import quote

API = "https://api.gridirondata.com/api/v1"
H = {"x-api-key": "YOUR_KEY"}

ranked = []
for pid, opp in CANDIDATES:
    url = f"{API}/matchups/{quote(pid, safe='')}/{opp}"
    r = requests.get(url, headers=H)
    if r.status_code != 200:
        continue
    s = r.json().get("stats", {})
    ranked.append({
        "player": r.json()["player_name"],
        "opp": opp,
        "avg": float(s.get("avg_actual", 0)),
        "games": int(s.get("games_played", 0)),
    })

ranked.sort(key=lambda x: -x["avg"])
print("Best streamer this week, by history vs opponent:")
for r in ranked:
    note = "" if r["games"] >= 2 else "  (small sample)"
    print(f"  {r['avg']:5.1f} avg  {r['games']:2} gm  vs {r['opp']:3}  {r['player']}{note}")

💡 Combine signals: matchup history is strongest when paired with this week's projection (Start/Sit guide) and recent form (Deviation guide). A favorable matchup and a rising deviation is your green light.

Next steps