← All guides

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.

Endpoints used

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",
  "opponent": "KC",
  "stats": { "games": 6, "avg_points": 24.8, "total_points": 148.6 }
}

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_points", 0)),
        "games": int(s.get("games", 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  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