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.

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.

{
  "player_id": "Jared Goff#QB",
  "player_name": "Jared Goff",
  "position": "QB",
  "team": "DET",
  "seasons": {
    "2024": {
      "weekly_stats": {
        "1": {
          "opponent": "LA",
          "fantasy_points": 18.56,
          "passing_yards": 217,
          "passing_tds": 1,
          "rushing_yards": 5,
          "rushing_tds": 0
        },
        "2": {
          "opponent": "TB",
          "fantasy_points": 29.08,
          "passing_yards": 307,
          "passing_tds": 2,
          "rushing_yards": 4,
          "rushing_tds": 0
        }
        // ... weeks 3-17
      }
    },
    "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!

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)

Query Parameters

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

Example Request

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/players/josh_allen%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.

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: 2025)

Example Request

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

Example Response

{
  "week": "12",
  "season": "2025",
  "projections": [
    {
      "player_id": "josh_allen#QB",
      "player_name": "Josh Allen",
      "position": "QB",
      "team": "BUF",
      "week": "12",
      "projected_points": 24.5,
      "injury_status": "Healthy"
    }
  ],
  "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: 2025)

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"

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: 2025)

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

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_allen%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