NAV
shell

NFL API

Welcome to the BALLDONTLIE NFL API, the best NFL API on the planet. This API contains data from 2002-current. An API key is required. You can obtain an API key by creating a free account on our website. Read the authentication section to learn how to use the API key.

If you're looking for the NBA API go here.

If you're looking for the MLB API go here.

Join us on discord.

Account Tiers

There are three different account tiers which provide you access to different types of data. Visit our website to create an account for free.

Paid tiers do not apply across sports. The tier you purchase for NFL will not be applied to other sports.

Read the table below to see the breakdown.

Endpoint Free ALL-STAR GOAT
Teams Yes Yes Yes
Players Yes Yes Yes
Games Yes Yes Yes
Player Injuries No Yes Yes
Active Players No Yes Yes
Team Standings No Yes Yes
Stats No Yes Yes
Season Stats No Yes Yes
Advanced Rushing Stats No No Yes
Advanced Passing Stats No No Yes
Advanced Receiving Stats No No Yes

The feature breakdown per tier is shown in the table below.

Tier Requests / Min $USD / mo.
GOAT 6000 39.99
ALL-STAR 600 9.99
Free 30 0

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"

Make sure to replace YOUR_API_KEY with your API key.

BALLDONTLIE uses API keys to allow access to the API. You can obtain an API key by creating a free account at our website

We expect the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: YOUR_API_KEY

Pagination

This API uses cursor based pagination rather than limit/offset. Endpoints that support pagination will send back responses with a meta key that looks like what is displayed on the right.

{
  "meta": {
    "next_cursor": 90,
    "per_page": 25
  }
}

You can use per_page to specify the maximum number of results. It defaults to 25 and doesn't allow values larger than 100.

You can use next_cursor to get the next page of results. Specify it in the request parameters like this: ?cursor=NEXT_CURSOR.

Errors

The API uses the following error codes:

Error Code Meaning
401 Unauthorized - You either need an API key or your account tier does not have access to the endpoint.
400 Bad Request -- The request is invalid. The request parameters are probably incorrect.
404 Not Found -- The specified resource could not be found.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're rate limited.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Teams

Get All Teams

curl "https://api.balldontlie.io/nfl/v1/teams" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 18,
      "conference": "NFC",
      "division": "EAST",
      "location": "Philadelphia",
      "name": "Eagles",
      "full_name": "Philadelphia Eagles",
      "abbreviation": "PHI"
    },
    ...
  ]
}

This endpoint retrieves all teams.

HTTP Request

GET https://api.balldontlie.io//nfl/v1/teams

Query Parameters

Parameter Required Description
division false Returns teams that belong to this division
conference false Returns teams that belong to this conference

Get a Specific Team

curl "https://api.balldontlie.io/nfl/v1/teams/<ID>" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 18,
      "conference": "NFC",
      "division": "EAST",
      "location": "Philadelphia",
      "name": "Eagles",
      "full_name": "Philadelphia Eagles",
      "abbreviation": "PHI"
    }
  ]
}

This endpoint retrieves a specific team.

HTTP Request

GET https://api.balldontlie.io/nfl/v1/teams/<ID>

URL Parameters

Parameter Required Description
ID true The ID of the team to retrieve

Players

Get All Players

curl "https://api.balldontlie.io/nfl/v1/players" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 33,
      "first_name": "Lamar",
      "last_name": "Jackson",
      "position": "Quarterback",
      "position_abbreviation": "QB",
      "height": "6' 2\"",
      "weight": "205 lbs",
      "jersey_number": "8",
      "college": "Louisville",
      "experience": "7th Season",
      "age": 27,
      "team": {
        "id": 6,
        "conference": "AFC",
        "division": "NORTH",
        "location": "Baltimore",
        "name": "Ravens",
        "full_name": "Baltimore Ravens",
        "abbreviation": "BAL"
      }
    },
    ...
  ],
  "meta": { "next_cursor": 25, "per_page": 25 }
}

This endpoint retrieves all players.

HTTP Request

GET https://api.balldontlie.io/nfl/v1/players

Query Parameters

Parameter Required Description
cursor false The cursor, used for pagination
per_page false The number of results per page. Default to 25. Max is 100
search false Returns players whose first or last name matches this value. For example, ?search=lamar will return players that have 'lamar' in their first or last name.
first_name false Returns players whose first name matches this value. For example, ?search=lamar will return players that have 'lamar' in their first name.
last_name false Returns players whose last name matches this value. For example, ?search=jackson will return players that have 'jackson' in their last name.
team_ids false Returns players that belong to these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2
player_ids false Returns players that match these ids. This should be an array: ?player_ids[]=1&player_ids[]=2

Get a Specific Player

curl "https://api.balldontlie.io/nfl/v1/players/<ID>" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": {
    "id": 33,
    "first_name": "Lamar",
    "last_name": "Jackson",
    "position": "Quarterback",
    "position_abbreviation": "QB",
    "height": "6' 2\"",
    "weight": "205 lbs",
    "jersey_number": "8",
    "college": "Louisville",
    "experience": "7th Season",
    "age": 27,
    "team": {
      "id": 6,
      "conference": "AFC",
      "division": "NORTH",
      "location": "Baltimore",
      "name": "Ravens",
      "full_name": "Baltimore Ravens",
      "abbreviation": "BAL"
    }
  }
}

This endpoint retrieves a specific player.

HTTP Request

GET https://api.balldontlie.io/nfl/v1/players/<ID>

URL Parameters

Parameter Required Description
ID true The ID of the player to retrieve

Player Injuries

Get All Player Injuries

curl "https://api.balldontlie.io/nfl/v1/player_injuries" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
      "player": {
        "id": 85,
        "first_name": "Dorian",
        "last_name": "Thompson-Robinson",
        "position": "Quarterback",
        "position_abbreviation": "QB",
        "height": "6' 2\"",
        "weight": "203 lbs",
        "jersey_number": "17",
        "college": "UCLA",
        "experience": "2nd Season",
        "age": 24,
        "team": {
          "id": 8,
          "conference": "AFC",
          "division": "NORTH",
          "location": "Cleveland",
          "name": "Browns",
          "full_name": "Cleveland Browns",
          "abbreviation": "CLE"
        }
      },
      "status": "Questionable",
      "comment": "Thompson-Robinson (finger) received negative X-ray results on his right middle finger Monday but is undergoing an MRI to determine the severity of the injury, Mary Kay Cabot of The Cleveland Plain Dealer reports.",
      "date": "2024-10-21T16:04:00.000Z"
    },
    ...
  ],
  "meta": { "next_cursor": 62089, "per_page": 25 }
}

This endpoint retrieves all player injuries.

HTTP Request

GET https://api.balldontlie.io/nfl/v1/player_injuries

Query Parameters

Parameter Required Description
cursor false The cursor, used for pagination
per_page false The number of results per page. Default to 25. Max is 100
team_ids false Returns players that belong to these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2
player_ids false Returns players that match these ids. This should be an array: ?player_ids[]=1&player_ids[]=2

Active Players

Get All Active Players

curl "https://api.balldontlie.io/nfl/v1/players/active" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 12,
      "first_name": "Kenneth",
      "last_name": "Gainwell",
      "position": "Running Back",
      "position_abbreviation": "RB",
      "height": "5' 9\"",
      "weight": "200 lbs",
      "jersey_number": "14",
      "college": "Memphis",
      "experience": "4th Season",
      "age": 25,
      "team": {
        "id": 18,
        "conference": "NFC",
        "division": "EAST",
        "location": "Philadelphia",
        "name": "Eagles",
        "full_name": "Philadelphia Eagles",
        "abbreviation": "PHI"
      }
    },
    ...
  ],
  "meta": { "next_cursor": 23, "per_page": 25 }
}

This endpoint retrieves all active players.

HTTP Request

GET https://api.balldontlie.io/nfl/v1/players/active

Query Parameters

Parameter Required Description
cursor false The cursor, used for pagination
per_page false The number of results per page. Default to 25. Max is 100
search false Returns players whose first or last name matches this value. For example, ?search=lamar will return players that have 'lamar' in their first or last name.
first_name false Returns players whose first name matches this value. For example, ?search=lamar will return players that have 'lamar' in their first name.
last_name false Returns players whose last name matches this value. For example, ?search=jackson will return players that have 'jackson' in their last name.
team_ids false Returns players that belong to these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2
player_ids false Returns players that match these ids. This should be an array: ?player_ids[]=1&player_ids[]=2

Games

Get All Games

curl "https://api.balldontlie.io/nfl/v1/games" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 7001,
      "visitor_team": {
        "id": 6,
        "conference": "AFC",
        "division": "NORTH",
        "location": "Baltimore",
        "name": "Ravens",
        "full_name": "Baltimore Ravens",
        "abbreviation": "BAL"
      },
      "home_team": {
        "id": 14,
        "conference": "AFC",
        "division": "WEST",
        "location": "Kansas City",
        "name": "Chiefs",
        "full_name": "Kansas City Chiefs",
        "abbreviation": "KC"
      },
      "summary": "Chiefs hold off Ravens 27-20 when review overturns TD on final play of NFL's season opener",
      "venue": "GEHA Field at Arrowhead Stadium",
      "week": 1,
      "date": "2024-09-06T00:20:00.000Z",
      "season": 2024,
      "postseason": false,
      "status": "Final",
      "home_team_score": 27,
      "home_team_q1": 7,
      "home_team_q2": 6,
      "home_team_q3": 7,
      "home_team_q4": 7,
      "home_team_ot": null,
      "visitor_team_score": 20,
      "visitor_team_q1": 7,
      "visitor_team_q2": 3,
      "visitor_team_q3": null,
      "visitor_team_q4": 10,
      "visitor_team_ot": null
    }
  ],
  "meta": {
    "per_page": 25,
    "next_cursor": 7024
  }
}

This endpoint retrieves all games.

HTTP Request

GET https://api.balldontlie.io/nfl/v1/games

Query Parameters

Parameter Required Description
cursor false The cursor, used for pagination
per_page false The number of results per page. Default to 25. Max is 100
dates false Returns games that match these dates. Dates should be formatted in YYYY-MM-DD. This should be an array: ?dates[]=2024-01-01&dates[]=2024-01-02
seasons false Returns games that occurred in these seasons. This should be an array: ?seasons[]=2022&seasons[]=2023
team_ids false Returns games for these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2
posteason false Returns playoffs games when set to true. Returns regular season games when set to false. Returns both when not specified
weeks false Returns games that occurred in these weeks. This should be an array: ?weeks[]=3

Get a Specific Game

curl "https://api.balldontlie.io/nfl/v1/games/<ID>" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": {
    "id": 7001,
    "visitor_team": {
      "id": 6,
      "conference": "AFC",
      "division": "NORTH",
      "location": "Baltimore",
      "name": "Ravens",
      "full_name": "Baltimore Ravens",
      "abbreviation": "BAL"
    },
    "home_team": {
      "id": 14,
      "conference": "AFC",
      "division": "WEST",
      "location": "Kansas City",
      "name": "Chiefs",
      "full_name": "Kansas City Chiefs",
      "abbreviation": "KC"
    },
    "summary": "Chiefs hold off Ravens 27-20 when review overturns TD on final play of NFL's season opener",
    "venue": "GEHA Field at Arrowhead Stadium",
    "week": 1,
    "date": "2024-09-06T00:20:00.000Z",
    "season": 2024,
    "postseason": false,
    "status": "Final",
    "home_team_score": 27,
    "home_team_q1": 7,
    "home_team_q2": 6,
    "home_team_q3": 7,
    "home_team_q4": 7,
    "home_team_ot": null,
    "visitor_team_score": 20,
    "visitor_team_q1": 7,
    "visitor_team_q2": 3,
    "visitor_team_q3": null,
    "visitor_team_q4": 10,
    "visitor_team_ot": null
  }
}

This endpoint retrieves a specific game.

HTTP Request

GET https://api.balldontlie.io/nfl/v1/games/<ID>

URL Parameters

Parameter Required Description
ID true The ID of the game to retrieve

Stats

Get All Stats

curl "https://api.balldontlie.io/nfl/v1/stats"

The above command returns JSON structured like this:

{
  "data": [
    {
      "player": {
        "id": 33,
        "first_name": "Lamar",
        "last_name": "Jackson",
        "position": "Quarterback",
        "position_abbreviation": "QB",
        "height": "6' 2\"",
        "weight": "205 lbs",
        "jersey_number": "8",
        "college": "Louisville",
        "experience": "7th Season",
        "age": 27
      },
      "team": {
        "id": 6,
        "conference": "AFC",
        "division": "NORTH",
        "location": "Baltimore",
        "name": "Ravens",
        "full_name": "Baltimore Ravens",
        "abbreviation": "BAL"
      },
      "game": {
        "id": 7001,
        "visitor_team": {
          "id": 6,
          "conference": "AFC",
          "division": "NORTH",
          "location": "Baltimore",
          "name": "Ravens",
          "full_name": "Baltimore Ravens",
          "abbreviation": "BAL"
        },
        "home_team": {
          "id": 14,
          "conference": "AFC",
          "division": "WEST",
          "location": "Kansas City",
          "name": "Chiefs",
          "full_name": "Kansas City Chiefs",
          "abbreviation": "KC"
        },
        "summary": "Chiefs hold off Ravens 27-20 when review overturns TD on final play of NFL's season opener",
        "venue": "GEHA Field at Arrowhead Stadium",
        "week": 1,
        "date": "2024-09-06T00:20:00.000Z",
        "season": 2024,
        "postseason": false,
        "status": "Final",
        "home_team_score": 27,
        "home_team_q1": 7,
        "home_team_q2": 6,
        "home_team_q3": 7,
        "home_team_q4": 7,
        "home_team_ot": null,
        "visitor_team_score": 20,
        "visitor_team_q1": 7,
        "visitor_team_q2": 3,
        "visitor_team_q3": null,
        "visitor_team_q4": 10,
        "visitor_team_ot": null
      },
      "passing_completions": 26,
      "passing_attempts": 41,
      "passing_yards": 273,
      "yards_per_pass_attempt": 6.7,
      "passing_touchdowns": 1,
      "passing_interceptions": null,
      "sacks": 1,
      "sacks_loss": 6,
      "qbr": 61.1,
      "qb_rating": 90.8,
      "rushing_attempts": 16,
      "rushing_yards": 122,
      "yards_per_rush_attempt": 7.6,
      "rushing_touchdowns": 0,
      "long_rushing": 16,
      "receptions": null,
      "receiving_yards": null,
      "yards_per_reception": null,
      "receiving_touchdowns": null,
      "long_reception": null,
      "receiving_targets": null,
      "fumbles": 1,
      "fumbles_lost": 1,
      "fumbles_recovered": 0,
      "total_tackles": null,
      "defensive_sacks": null,
      "solo_tackles": null,
      "tackles_for_loss": null,
      "passes_defended": null,
      "qb_hits": null,
      "fumbles_touchdowns": null,
      "defensive_interceptions": null,
      "interception_yards": null,
      "interception_touchdowns": null,
      "kick_returns": null,
      "kick_return_yards": null,
      "yards_per_kick_return": null,
      "long_kick_return": null,
      "kick_return_touchdowns": null,
      "punt_returns": null,
      "punt_return_yards": null,
      "yards_per_punt_return": null,
      "long_punt_return": null,
      "punt_return_touchdowns": null,
      "field_goal_attempts": null,
      "field_goals_made": null,
      "field_goal_pct": null,
      "long_field_goal_made": null,
      "extra_points_made": null,
      "total_points": null,
      "punts": null,
      "punt_yards": null,
      "gross_avg_punt_yards": null,
      "touchbacks": null,
      "punts_inside_20": null,
      "long_punt": null
    },
    ...
  ],
  "meta": { "per_page": 25 }
}

This endpoint retrieves all stats.

HTTP Request

GET https://api.balldontlie.io/nfl/v1/stats

Query Parameters

Parameter Required Description
cursor false The page number, used for pagination.
per_page false The number of results returned per call, used for pagination. Max 100.
player_ids false Returns stats for these player ids. This should be an array: ?player_ids[]=1&player_ids[]=2
game_ids false Returns stat for these game ids. This should be an array: ?game_ids[]=1&game_ids[]=2
seasons false Returns stats that occurred in these seasons. This should be an array: ?seasons[]=2022&seasons[]=2023

Season Stats

Get Season Stats

curl "https://api.balldontlie.io/nfl/v1/season_stats"

The above command returns JSON structured like this:

{
  "data": [
    {
      "player": {
        "id": 36,
        "first_name": "Derrick",
        "last_name": "Henry",
        "position": "Running Back",
        "position_abbreviation": "RB",
        "height": "6' 2\"",
        "weight": "247 lbs",
        "jersey_number": "22",
        "college": "Alabama",
        "experience": "9th Season",
        "age": 30
      },
      "games_played": 7,
      "season": 2024,
      "postseason": false,
      "passing_completions": null,
      "passing_attempts": null,
      "passing_yards": null,
      "yards_per_pass_attempt": null,
      "passing_touchdowns": null,
      "passing_interceptions": null,
      "passing_yards_per_game": null,
      "passing_completion_pct": null,
      "qbr": null,
      "rushing_attempts": 134,
      "rushing_yards": 873,
      "rushing_yards_per_game": 124.7143,
      "yards_per_rush_attempt": 6.515,
      "rushing_touchdowns": 8,
      "rushing_fumbles": 1,
      "rushing_fumbles_lost": null,
      "rushing_first_downs": 39,
      "receptions": 7,
      "receiving_yards": 62,
      "yards_per_reception": 8.857,
      "receiving_touchdowns": 2,
      "receiving_fumbles": null,
      "receiving_fumbles_lost": null,
      "receiving_first_downs": 4,
      "receiving_targets": 9,
      "receiving_yards_per_game": 8.857142,
      "fumbles_forced": null,
      "fumbles_recovered": null,
      "total_tackles": null,
      "defensive_sacks": null,
      "defensive_sack_yards": null,
      "solo_tackles": null,
      "assist_tackles": null,
      "fumbles_touchdowns": null,
      "defensive_interceptions": null,
      "interception_touchdowns": null,
      "kick_returns": null,
      "kick_return_yards": null,
      "yards_per_kick_return": null,
      "kick_return_touchdowns": null,
      "punt_returner_returns": null,
      "punt_returner_return_yards": null,
      "yards_per_punt_return": null,
      "punt_return_touchdowns": null,
      "field_goal_attempts": null,
      "field_goals_made": null,
      "field_goal_pct": null,
      "punts": null,
      "punt_yards": null,
      "field_goals_made_1_19": null,
      "field_goals_made_20_29": null,
      "field_goals_made_30_39": null,
      "field_goals_made_40_49": null,
      "field_goals_made_50": null,
      "field_goals_attempts_1_19": null,
      "field_goals_attempts_20_29": null,
      "field_goals_attempts_30_39": null,
      "field_goals_attempts_40_49": null,
      "field_goals_attempts_50": null
    }
  ],
  "meta": { "next_cursor": 83571, "per_page": 25 }
}

HTTP Request

GET https://api.balldontlie.io/nfl/v1/season_stats

Query Parameters

Parameter Required Description
season true Returns season stats for this season
player_ids false Returns season stats for these players. This should be an array: player_ids[]=1
team_id false Returns season stats for his team
postseason false Returns season stats for postseason or regular season. Defaults to false.
sort_by false Returns season stats sorted by this attribute. Most attributes in the response body can be specified
sort_order false Returns season stats sorted in asc or desc

Team Standings

Get Team Standings

curl "https://api.balldontlie.io/nfl/v1/standings?season=2024" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
      "team": {
        "id": 21,
        "conference": "NFC",
        "division": "EAST",
        "location": "Washington",
        "name": "Commanders",
        "full_name": "Washington Commanders",
        "abbreviation": "WSH"
      },
      "win_streak": 1,
      "points_for": 218,
      "points_against": 152,
      "playoff_seed": 2,
      "point_differential": 66,
      "overall_record": "5-2",
      "conference_record": "3-1",
      "division_record": "1-0",
      "wins": 5,
      "losses": 2,
      "ties": 0,
      "home_record": "3-0",
      "road_record": "2-2",
      "season": 2024
    },
    ...
  ]
}

This endpoint retrieves regular season team standings.

HTTP Request

GET https://api.balldontlie.io/nfl/v1/standings

Query Parameters

Parameter Required Description
season true Returns regular season standings for the specified season. For example, ?season=2023 will return the team standings for the 2023-24 season.

Advanced Rushing Stats

Get Advanced Rushing Stats

curl "https://api.balldontlie.io/nfl/v1/advanced_stats/rushing?season=2024"

The above command returns JSON structured like this:

{
  "data": [
    {
      "player": {
        "id": 466,
        "first_name": "James",
        "last_name": "Conner",
        "position": "Running Back",
        "position_abbreviation": "RB",
        "height": "6' 1\"",
        "weight": "233 lbs",
        "jersey_number": "6",
        "college": "Pittsburgh",
        "experience": "8th Season",
        "age": 29
      },
      "season": 2024,
      "week": 0,
      "avgTimeToLos": 2.91877397260274,
      "expectedRushYards": 618.9679635508963,
      "rushAttempts": 159,
      "rushPctOverExpected": 0.4285714285714285,
      "rushTouchdowns": 5,
      "rushYards": 697,
      "rushYardsOverExpected": 59.03203644910366,
      "rushYardsOverExpectedPerAtt": 0.3833249120071666,
      "efficiency": 4.161334289813485,
      "percentAttemptsGteEightDefenders": 25.15723270440252,
      "avgRushYards": 4.383647798742138
    }
  ],
  "meta": { "next_cursor": 83571, "per_page": 25 }
}

HTTP Request

GET https://api.balldontlie.io/nfl/v1/advanced_stats/rushing?season=2024

Query Parameters

Parameter Required Description
season true Returns season stats for this season
player_id false Returns season stats for this player
week false Returns season stats for this week. Week 0 represents stats for the whole season

Advanced Passing Stats

Get Advanced Passing Stats

curl "https://api.balldontlie.io/nfl/v1/advanced_stats/passing?season=2024"

The above command returns JSON structured like this:

{
  "data": [
    {
      "player": {
        "id": 63,
        "first_name": "Matthew",
        "last_name": "Stafford",
        "position": "Quarterback",
        "position_abbreviation": "QB",
        "height": "6' 3\"",
        "weight": "214 lbs",
        "jersey_number": "9",
        "college": "Georgia",
        "experience": "16th Season",
        "age": 36
      },
      "season": 2024,
      "week": 0,
      "aggressiveness": 13.9751552795031,
      "attempts": 322,
      "avgAirDistance": 21.63436475569557,
      "avgAirYardsDifferential": -2.125107043683379,
      "avgAirYardsToSticks": -0.8761341853035138,
      "avgCompletedAirYards": 5.58981308411215,
      "avgIntendedAirYards": 7.714920127795528,
      "avgTimeToThrow": 2.78214953271028,
      "completionPercentage": 66.45962732919256,
      "completionPercentageAboveExpectation": -1.853113571776092,
      "completions": 214,
      "expectedCompletionPercentage": 68.31274090096865,
      "gamesPlayed": 9,
      "interceptions": 7,
      "maxAirDistance": 62.01834083559476,
      "maxCompletedAirDistance": 55.93206057352081,
      "passTouchdowns": 9,
      "passYards": 2262,
      "passerRating": 86.99534161490683
    }
  ],
  "meta": { "next_cursor": 83571, "per_page": 25 }
}

HTTP Request

GET https://api.balldontlie.io/nfl/v1/advanced_stats/passing?season=2024

Query Parameters

Parameter Required Description
season true Returns season stats for this season
player_id false Returns season stats for this player
week false Returns season stats for this week. Week 0 represents stats for the whole season

Advanced Receiving Stats

Get Advanced Receiving Stats

curl "https://api.balldontlie.io/nfl/v1/advanced_stats/receiving?season=2024"

The above command returns JSON structured like this:

{
  "data": [
    {
      "player": {
        "id": 651,
        "first_name": "Tutu",
        "last_name": "Atwell",
        "position": "Wide Receiver",
        "position_abbreviation": "WR",
        "height": "5' 9\"",
        "weight": "165 lbs",
        "jersey_number": "5",
        "college": "Louisville",
        "experience": "4th Season",
        "age": 25
      },
      "season": 2024,
      "week": 0,
      "avgCushion": 8.23361111111111,
      "avgExpectedYac": 4.380550229106592,
      "avgIntendedAirYards": 12.60675,
      "avgSeparation": 3.579191769761275,
      "avgYac": 3.581153846153846,
      "avgYacAboveExpectation": -0.7993963829527457,
      "catchPercentage": 65,
      "percentShareOfIntendedAirYards": 20.61619221664847,
      "recTouchdowns": 0,
      "receptions": 26,
      "targets": 40,
      "yards": 372
    }
  ],
  "meta": { "next_cursor": 83571, "per_page": 25 }
}

HTTP Request

GET https://api.balldontlie.io/nfl/v1/advanced_stats/receiving?season=2024

Query Parameters

Parameter Required Description
season true Returns season stats for this season
player_id false Returns season stats for this player
week false Returns season stats for this week. Week 0 represents stats for the whole season
shell