API Documentation

Player Profile with Historical Data

Each player includes historical stats from 2020 through the current 2026 season and matchup history against every team. Weekly actuals and season totals carry all three scoring formats: the base fantasy_points / MISC_FPTS is standard, with _ppr / _half (weekly) and _PPR / _HALF (totals) variants alongside. Use ?scoring= on /stats to have the API resolve them for you (default ppr).

{
  "player_id": "Jared Goff#QB",
  "player_name": "Jared Goff",
  "position": "QB",
  "team": "DET",
  "seasons": {
    "2024": {
      "weekly_stats": {
        "1": {
          "opponent": "LA",
          "fantasy_points": 18.56,       // standard
          "fantasy_points_ppr": 18.56,   // QBs rarely catch passes, so equal here
          "fantasy_points_half": 18.56
        },
        "2": {
          "opponent": "TB",
          "fantasy_points": 29.08,
          "fantasy_points_ppr": 29.08,
          "fantasy_points_half": 29.08
        }
        // ... weeks 3-17
      },
      "season_totals": {
        "MISC_FPTS": 372.5,              // standard
        "MISC_FPTS_PPR": 372.5,
        "MISC_FPTS_HALF": 372.5,
        "Rank": 5, "Rank_PPR": 6, "Rank_HALF": 6
        // ... passing/rushing counting stats
      }
    },
    "2023": { /* Full season data */ },
    "2022": { /* Full season data */ },
    "2021": { /* Full season data */ },
    "2020": { /* Full season data */ }
  },
  "vs_opponent": {
    "GB": {
      "games": 8,
      "avg_points": 19.42,
      "total_points": 155.36,
      "high": 28.64,
      "low": 8.12
    },
    "CHI": {
      "games": 8,
      "avg_points": 22.87,
      "total_points": 182.96,
      "high": 31.24,
      "low": 14.56
    },
    "MIN": {
      "games": 8,
      "avg_points": 17.65,
      "total_points": 141.2,
      "high": 26.88,
      "low": 9.44
    },
    "DAL": {
      "games": 3,
      "avg_points": 24.12,
      "total_points": 72.36,
      "high": 30.48,
      "low": 18.24
    }
    // ... all 32 teams
  }
}

Matchup Analysis

Get historical performance data when a player faces a specific opponent. Perfect for start/sit decisions.

GET /matchups/Amon-Ra%20St.%20Brown%23WR/GB

{
  "player_id": "Amon-Ra St. Brown#WR",
  "player_name": "Amon-Ra St. Brown",
  "position": "WR",
  "opponent": "GB",
  "stats": {
    "games": 6,
    "avg_points": 21.45,
    "total_points": 128.7,
    "high": 32.4,
    "low": 11.2
  }
}

// Use case: Amon-Ra averages 21.4 pts vs GB (6 games)
// but only 15.8 pts vs MIN (6 games) - start him vs GB!

Snap Share Trend

Catch a role change before the box score shows it. Compare a player’s recent snap share to his season average.

GET /snaps/Bucky%20Irving%23RB?season=2024&trend=4

{
  "player_id": "Bucky Irving#RB",
  "season": "2024",
  "season_snap_pct_avg": 44.4,
  "recent_snap_pct_avg": 57.0,
  "trend_delta": 12.6
}

// Use case: +12.6 over the last 4 weeks means Irving is taking over
// the Tampa Bay backfield. Buy before the points catch up.

Projection Deviation Analysis

Identify boom/bust candidates by seeing how players perform vs their projections.

GET /deviations/Jahmyr%20Gibbs%23RB

{
  "player_id": "Jahmyr Gibbs#RB",
  "player_name": "Jahmyr Gibbs",
  "position": "RB",
  "season": "2024",
  "avg_deviation": 3.2,
  "weeks_analyzed": 16,
  "weekly_deviations": [
    {
      "week": 1,
      "actual_points": 22.4,
      "projected_points": 14.5,
      "deviation": 7.9,
      "deviation_percentage": 54.5,
      "opponent": "LA"
    },
    {
      "week": 2,
      "actual_points": 8.6,
      "projected_points": 15.2,
      "deviation": -6.6,
      "deviation_percentage": -43.4,
      "opponent": "TB"
    }
  ]
}

// Use case: Moderate deviation = consistent player
// Gibbs ranges from 8.6 to 22.4 pts - reliable floor

Weekly Projections

Get fantasy point projections for all players, sorted by projected points.

GET /projections/12?position=TE

{
  "week": "12",
  "season": "2025",
  "projections": [
    {
      "player_id": "Sam LaPorta#TE",
      "player_name": "Sam LaPorta",
      "position": "TE",
      "team": "DET",
      "week": "12",
      "projected_points": 12.8,
      "injury_status": "Healthy"
    },
    {
      "player_id": "Travis Kelce#TE",
      "player_name": "Travis Kelce",
      "position": "TE",
      "team": "KC",
      "week": "12",
      "projected_points": 11.4,
      "injury_status": "Healthy"
    },
    {
      "player_id": "George Kittle#TE",
      "player_name": "George Kittle",
      "position": "TE",
      "team": "SF",
      "week": "12",
      "projected_points": 10.9,
      "injury_status": "Questionable"
    }
  ],
  "count": 64
}

Example: how sticky is points per game from one season to the next?

Pull a player's weekly actuals for consecutive seasons and compare two forecasts of next season: last season as-is, and last season pulled 30% of the way back toward the position average. A dozen players over 2021–2025 is about 60 requests, more than the free plan's 50 a month: try it with about eight players on the free plan, or run the full set on Basic.

import os, statistics, requests
from urllib.parse import quote

API = "https://api.gridirondata.com/api/v1"
H = {"x-api-key": os.environ["GRIDIRON_API_KEY"]}

def ppg(player_id, season):
    r = requests.get(f"{API}/stats/{quote(player_id, safe='')}/{season}", headers=H)
    if r.status_code == 404:
        return None                      # no data for that season
    weeks = [w["points"] for w in r.json()["weekly_stats"].values()
             if isinstance(w, dict) and w.get("points") is not None]
    return sum(weeks) / len(weeks) if len(weeks) >= 8 else None

roster = ["Justin Jefferson#WR", "CeeDee Lamb#WR", "Davante Adams#WR", "Mike Evans#WR"]
seasons = range(2021, 2026)
table = {(p, s): ppg(p, s) for p in roster for s in seasons}

naive, shrunk = [], []
for s in seasons[:-1]:
    this = {p: table[(p, s)] for p in roster if table[(p, s)] and table.get((p, s + 1))}
    if not this:
        continue
    mean = statistics.mean(this.values())
    for p, v in this.items():
        nxt = table[(p, s + 1)]
        naive.append(abs(v - nxt))
        shrunk.append(abs(0.7 * v + 0.3 * mean - nxt))
print(f"naive MAE {statistics.mean(naive):.2f}  shrunk MAE {statistics.mean(shrunk):.2f}")

On a 12-player roster across positions, 2021–2025, shrinking cut the average miss from 3.05 to 2.75 PPR points per game, most of it at RB and WR. The fuller script, with per-position results, the biggest year-over-year moves and a /deviations check of whether projection-beaters keep beating projections, is backtest.py in our examples.

To grade weekly projections against actuals across the whole league, see the Backtest Fantasy Projections Against Actuals guide.

GET Get Player by ID

Retrieve detailed information for a specific player.

Path Parameters

Query Parameters

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

GET Search Players

Search for players by name, position, or team.

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/players/search?name=Allen&position=QB"

GET Get Player (Exact Match)

Get a specific player by exact name and position match.

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/players?name=Josh%20Allen&position=QB"

GET List Players

List all players with pagination.

Query Parameters

GET Get Weekly Projections

Get fantasy point projections for all players for a specific week. Provider weekly projections are published as each week approaches, so for weeks that aren't out yet the API returns a prorated season-long projection (season points ÷ games) for every player. The projection_source field tells you which was used — weekly (real per-week number) or season_prorated (estimate) — and real weekly values replace the estimate automatically once published.

Path Parameters

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/projections/12?position=QB&scoring=half"

{
  "week": "12",
  "season": "2026",
  "scoring": "half",
  "projections": [
    {
      "player_id": "Josh Allen#QB",
      "player_name": "Josh Allen",
      "position": "QB",
      "team": "BUF",
      "week": "12",
      "projected_points": 24.5,
      "projection_source": "season_prorated",
      "injury_status": "Healthy"
    }
  ],
  "count": 32,
  "prorated_count": 32
}

GET Get Player Stats

Get historical stats for a player in a specific season.

Path Parameters

Query Parameters

Alternative: You can also query by name and position:

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/stats?name=Josh%20Allen&position=QB&season=2024&scoring=ppr"

{
  "player_id": "Justin Jefferson#WR",
  "season": "2024",
  "scoring": "ppr",
  "season_points": 227.9,
  "weekly_stats": {
    "1": {
      "opponent": "NYG",
      "fantasy_points": 11.9,        // standard (base)
      "fantasy_points_ppr": 15.9,
      "fantasy_points_half": 13.9,
      "points": 15.9                 // resolved for scoring=ppr
    }
  },
  "season_totals": {
    "MISC_FPTS": 149.9,              // standard
    "MISC_FPTS_PPR": 227.9,
    "MISC_FPTS_HALF": 188.9,
    "Rank": 8, "Rank_PPR": 3, "Rank_HALF": 5
  }
}

GET Get Projection Deviations

Analyze how a player performs vs their projections. Useful for identifying boom/bust candidates.

Path Parameters

Query Parameters

Alternative: Query by name and position:

{
  "player_id": "Josh Allen#QB",
  "player_name": "Josh Allen",
  "position": "QB",
  "season": "2025",
  "avg_deviation": 3.2,
  "weeks_analyzed": 11,
  "weekly_deviations": [
    {
      "week": 1,
      "actual_points": 28.4,
      "projected_points": 24.5,
      "deviation": 3.9,
      "deviation_percentage": 15.9,
      "opponent": "ARI"
    }
  ]
}

GET Get Snap Share

Per-week snap share — the percentage of his team’s offensive plays a player was on the field for — plus special-teams snaps, a season average, and a trailing trend. Snap share moves before box-score production does, so it is the earliest reliable signal of a role change.

Data is sourced from nflverse / Pro-Football-Reference game-level snap counts. Percentages are returned as 0–100. Seasons 2020–2026 are available (the current season updates weekly); regular season (weeks 1–18) only.

Path Parameters

Query Parameters

Alternative: Query by name and position:

Response Fields

GET /snaps/Bucky%20Irving%23RB?season=2024&trend=4

{
  "player_id": "Bucky Irving#RB",
  "player_name": "Bucky Irving",
  "position": "RB",
  "season": "2024",
  "games": 17,
  "games_with_snaps": 17,
  "season_snap_pct_avg": 44.4,
  "recent_snap_pct_avg": 57.0,
  "trend_weeks": 4,
  "trend_delta": 12.6,
  "totals": {
    "games": 17,
    "offense_snaps": 516,
    "offense_pct_avg": 44.4,
    "st_snaps": 41,
    "st_pct_avg": 8.6
  },
  "weekly_snaps": [
    { "week": 1,  "offense_snaps": 20, "snap_pct": 31.0, "st_snaps": 8, "st_pct": 30.0, "team": "TB", "opponent": "WAS" },
    { "week": 18, "offense_snaps": 48, "snap_pct": 72.0, "st_snaps": 0, "st_pct": 0.0,  "team": "TB", "opponent": "NO"  }
  ],
  "source": "nflverse / Pro-Football-Reference game-level snap counts"
}

// Irving opened 2024 at 31% of Tampa Bay's snaps and finished at 72%.
// trend_delta of +12.6 flags the takeover while it is still happening.

Snap share on /stats

Snap data is also joined onto the stats endpoint, so you can read production and playing time together without a second request. Each weekly entry gains snap_pct and offense_snaps, and the response carries a snap_counts block.

GET /stats/Bucky%20Irving%23RB/2024

{
  "weekly_stats": {
    "1": { "points": 12.6, "opponent": "WAS", "snap_pct": 31.0, "offense_snaps": 20 }
  },
  "snap_counts": {
    "weekly": { ... },
    "totals": { "games": 17, "offense_snaps": 516, "offense_pct_avg": 44.4 }
  }
}

Note: weeks played and weeks with snaps are not always the same set — a blocking tight end can log snaps with no fantasy line. Weeks missing from one side simply omit the corresponding fields rather than reporting zero.

GET League-wide News Feed

Recent news across every tracked player, newest first, in one call: signings, trades, releases, injuries and depth-chart moves. Use it through free agency (March) and the NFL Draft (April) instead of polling player by player. The scrapers run year-round.

Plans: Basic and above get the full feed: 90 days of history, filters and paging. Free keys get a preview of the 5 newest headlines from the last 24 hours, marked "teaser": true with an upgrade_url.

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/news/latest?since=2027-03-09T00:00:00Z&impact=transaction&position=WR"

{
  "since": "2027-03-09T00:00:00Z",
  "until": "2027-03-11T14:02:10Z",
  "count": 1,
  "filters": {"impact": ["transaction"], "position": ["WR"]},
  "news": [
    {
      "player_id": "Davante Adams#WR",
      "player_name": "Davante Adams",
      "position": "WR",
      "team": "LAR",
      "headline": "Davante Adams expected at start of Rams offseason program",
      "summary": "",
      "impact": "transaction",
      "source": "pft-nbc",
      "url": "https://profootballtalk.nbcsports.com/...",
      "published_at": "2027-03-10T19:41:00Z"
    }
  ],
  "next_cursor": "WyIyMDI3LTAzLTEwVDE5OjQxOjAwWiIs..."
}

One headline about two players appears once per player, so a position or team filter still catches it.

GET Get Player News

Recent NFL news headlines for a player, newest first. Each item is tagged with an impact category (injury, transaction, role, or general) to help surface start/sit-relevant updates. Items are refreshed throughout the day, all year, and roll off after 90 days. For every player at once, use /news/latest.

Path Parameters

Query Parameters

Alternative: Query by name and position:

{
  "player_id": "Malik Nabers#WR",
  "days": 14,
  "count": 2,
  "news": [
    {
      "headline": "Nabers (knee) full participant at Wednesday practice",
      "summary": "Giants WR Malik Nabers practiced fully and is trending toward playing Sunday.",
      "impact": "injury",
      "source": "espn-nfl",
      "url": "https://www.espn.com/nfl/story/_/id/00000000",
      "published_at": "2026-09-10T17:22:00Z"
    },
    {
      "headline": "Nabers feeling 'good' but mum on playing Week 1",
      "summary": "",
      "impact": "general",
      "source": "espn-nfl",
      "url": "https://www.espn.com/nfl/story/_/id/00000001",
      "published_at": "2026-09-01T03:21:40Z"
    }
  ]
}

No news yet? When a player has no recent news, the response includes a request_scrape link you can call to queue an on-demand scrape (see next endpoint):

{
  "player_id": "Max Bredeson#RB",
  "days": 14,
  "count": 0,
  "news": [],
  "message": "No news found for Max Bredeson#RB in the last 14 days.",
  "request_scrape": {
    "method": "POST",
    "href": "https://api.gridirondata.com/api/v1/news/Max%20Bredeson%23RB/request",
    "description": "No news yet — POST to this link to request a fresh scrape for this player."
  }
}

POST Request a News Scrape

Queue an on-demand news scrape for a specific player — useful when GET /news/{player_id} returns no results and you want the latest sources checked immediately. The request is accepted and processed asynchronously; poll GET /news/{player_id} shortly after to see any new headlines. No request body is required.

Path Parameters

{
  "player_id": "Max Bredeson#RB",
  "status": "accepted",
  "message": "Scrape requested. New headlines (if any are found in current sources) will appear shortly.",
  "poll": {
    "method": "GET",
    "href": "https://api.gridirondata.com/api/v1/news/Max%20Bredeson%23RB"
  }
}

GET Get Injury Status Changes

Returns every player whose injury status changed since since. This is a Pro plan feature; Free and Basic keys get 403 with "reason": "pro_required", an upgrade_url and a pro_includes list of what the plan adds.

GridIron refreshes injury status every day at 11:00 ET. On game days it refreshes again after inactives: Sunday around 12:45 pm, 3:50 pm and 7:45 pm ET, and Thursday and Monday around 7:15 pm ET. About ten minutes after each refresh, changes are recorded with a detected_at time. Poll with the next_since value from your last response to get only new changes.

Query Parameters

curl -H "x-api-key: YOUR_PRO_KEY" \
  "https://api.gridirondata.com/api/v1/injuries/changes?since=2026-09-27T16:00:00Z"

{
  "season": "2026",
  "since": "2026-09-27T16:00:00Z",
  "until": "2026-09-27T17:05:41Z",
  "count": 1,
  "changes": [
    {
      "player_id": "Josh Allen#QB",
      "player_name": "Josh Allen",
      "position": "QB",
      "team": "BUF",
      "previous_status": "Questionable",
      "status": "Out",
      "detected_at": "2026-09-27T16:55:12Z"
    }
  ],
  "next_since": "2026-09-27T16:55:12Z",
  "last_checked_at": "2026-09-27T16:55:12Z",
  "truncated": false
}

GET Get vs Opponent History

Get historical performance data for a player against a specific opponent.

Path Parameters

Alternative: Query by name and position:

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

GET Health Check

Check API status and version.

{
  "status": "healthy",
  "version": "1.0.0",
  "default_season": "2026"
}