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

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