API Documentation

Complete reference for the GridIron Data Fantasy Football API

Authentication

API Key Required
All API requests require an API key passed in the x-api-key header. Send the header name in lowercase — x-api-key — for the widest client compatibility. 
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.gridirondata.com/api/v1/health"

Rate Limits

Rate limits vary by plan:
  • Basic: 30 requests/minute, 5,000/month
  • Pro: 100 requests/minute, 50,000/month
  • Enterprise: Custom limits

When rate limited, the API returns a 429 Too Many Requests response.

Base URL

https://api.gridirondata.com/api/v1

Example Data

See the rich fantasy data you'll have access to. All examples show real data from our database.

Player Profile with Historical Data

Each player includes 5 years of historical stats (2020-2024) 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
}

Players

GET Get Player by ID

/players/{player_id}

Retrieve detailed information for a specific player.

Path Parameters

Parameter Type Description
player_id required string Player ID in format: First Last#POSITION (e.g., Josh Allen#QB; defense: Houston Texans#DST). URL-encode the space and #.

Query Parameters

Parameter Type Description
season string Filter to specific season (e.g., "2026")

Example Request

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

GET Search Players

/players/search

Search for players by name, position, or team.

Query Parameters

Parameter Type Description
name string Partial or full player name
position string Position: QB, RB, WR, TE, K, DST
team string Team abbreviation (e.g., BUF, KC)
limit integer Max results (default: 50, max: 100)

Example Request

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

GET Get Player (Exact Match)

/players?name={name}&position={position}

Get a specific player by exact name and position match.

Query Parameters

Parameter Type Description
name required string Exact player name
position required string Position: QB, RB, WR, TE, K, DST

Example Request

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

GET List Players

/players

List all players with pagination.

Query Parameters

Parameter Type Description
position string Filter by position
limit integer Results per page (default: 50, max: 100)
cursor string Pagination cursor from previous response

Projections

GET Get Weekly Projections

/projections/{week}

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

Parameter Type Description
week required integer NFL week number (1-18)

Query Parameters

Parameter Type Description
position string Filter by position
season string Season year (default: current NFL season)
source string Pass weekly to return ONLY real per-week projections (no season-prorated fallback)
scoring string Scoring format for projected_points: ppr (default), half, or standard. The echoed scoring field confirms which was applied.

Example Request

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

Example Response

{
  "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
}

Stats

GET Get Player Stats

/stats/{player_id}/{season}

Get historical stats for a player in a specific season.

Path Parameters

Parameter Type Description
player_id required string Player ID
season string Season year (default: current NFL season)

Query Parameters

Parameter Type Description
scoring string Scoring format: ppr (default), half, or standard. Sets the resolved points on each week and the top-level season_points. The raw fantasy_points (standard) plus fantasy_points_ppr / fantasy_points_half variants are always present too.

Alternative: You can also query by name and position:

/stats?name={name}&position={position}&season={season}

Example Request

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

Example Response

{
  "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
  }
}

Deviations

GET Get Projection Deviations

/deviations/{player_id}

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

Path Parameters

Parameter Type Description
player_id required string Player ID

Query Parameters

Parameter Type Description
season string Season year (default: current NFL season)

Alternative: Query by name and position:

/deviations?name={name}&position={position}

Example Response

{
  "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"
    }
  ]
}

Snap Counts

GET Get Snap Share

/snaps/{player_id}

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–2025 are available; regular season (weeks 1–18) only.

Path Parameters

Parameter Type Description
player_id required string Player ID (First Last#POS, URL-encoded)

Query Parameters

Parameter Type Description
season string Season year (default: current NFL season)
trend integer Weeks in the trailing average, 1–18 (default: 4)

Alternative: Query by name and position:

/snaps?name={name}&position={position}

Response Fields

Field Type Description
season_snap_pct_avg number Average snap share across every week he took a snap
recent_snap_pct_avg number Average over the most recent trend weeks played
trend_delta number Recent minus season. Positive = trending up (role growing)
games_with_snaps integer Weeks with a non-zero snap share. Zero-snap weeks are excluded from averages
weekly_snaps[] array Per week: snap_pct, offense_snaps, st_snaps, st_pct, team, opponent

Example Response

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.

News

GET Get Player News

/news/{player_id}

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 and roll off after ~30 days.

Path Parameters

Parameter Type Description
player_id required string Player ID (e.g. Malik Nabers#WR)

Query Parameters

Parameter Type Description
days integer Lookback window in days (default: 14, max: 90)
limit integer Max headlines to return (default: 10, max: 50)
impact string Filter by category: injury, transaction, role, or general

Alternative: Query by name and position:

/news?name={name}&position={position}

Example Response

{
  "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

/news/{player_id}/request

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

Parameter Type Description
player_id required string Player ID (e.g. Max Bredeson#RB)

Example Response (202 Accepted)

{
  "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"
  }
}

Matchups

GET Get vs Opponent History

/matchups/{player_id}/{opponent}

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

Path Parameters

Parameter Type Description
player_id required string Player ID
opponent required string Opponent team abbreviation (e.g., KC, NE)

Alternative: Query by name and position:

/matchups?name={name}&position={position}&opponent={opponent}

Example Request

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

Health Check

GET Health Check

/health

Check API status and version.

Example Response

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

Error Codes

Code Description
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
404 Not Found - Resource doesn't exist
409 Conflict - Multiple matches found (use player_id for exact match)
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error