Most people searching for an NFL API want one of three things: scores and schedules, statistics (play-by-play, box scores, player totals), or betting odds. They're different products, often from different providers, and the right one depends on what your program does with the data.
ZippyOddsAPI is the third kind. It returns NFL games with each sportsbook's spreads, totals, moneylines and player props, plus boards worked out from those prices. It is not a play-by-play or box-score statistics feed. This guide sets out what each kind of data looks like, so you can tell which one you need and how they fit together.
Three kinds of football data
| Kind | What a row looks like | Typical use |
|---|---|---|
| Scores and schedules | A game, its kickoff, its teams, its status and score | Scoreboards, alerts, fantasy apps |
| Statistics | A play, a drive, or a player's passing yards in one game | Models, research, fantasy scoring |
| Odds | A book's price and line on a market, with the time it was read | Price comparison, betting models, market research |
A model usually needs at least two. Stats tell you what happened. Odds tell you what the market expected beforehand, and the closing spread on a game is one of the hardest benchmarks a model can be tested against.
The NFL scores API question
If you want final scores for every game of a season, you want a results feed. ZippyOddsAPI isn't one, and it's worth knowing why before you build on it.
Its events come from the books that are pricing them. /v1/events?league=nfl returns the games on the board, soonest first, each with start_time, home, away and status. A game leaves the board as soon as a source reports it final, so /v1/scores has no finished games to return. In practice it lists games in progress with their current score, and it needs a plan that includes live data. That makes it a live view for pricing, not an NFL scores API you can query for last week's results.
So use ZippyOddsAPI for upcoming games and their prices, and a results source for what happened.
Stats: play-by-play and player totals
An NFL stats API returns the record of the game itself: every snap, every target, every tackle, or the totals built from them. An NFL player stats API narrows that to per-player lines, such as a quarterback's attempts, completions and yards in each game.
There are commercial feeds for this, and there are community open-source clients that read the stats published on league and media websites. Before using any of them, read the provider's own terms and documentation: what you may store, whether you may show the data in a product, and how often you may ask. That's the part that changes, and only the provider can tell you.
What none of these give you is the price. An NFL statistics API can tell you a receiver averaged 71 yards over his last eight games. It can't tell you that the market's line on him this week is 64.5 and what it costs to bet the over.
Where odds fit: player props as targets
Player props are where odds and stats meet most directly. A prop line on passing yards is the market's estimate of the middle of that player's outcomes, and it comes with a price on each side. ZippyOddsAPI's market catalog includes player_pass_yds, player_pass_tds, player_rush_yds, player_rec_yds and player_receptions, among others.
curl -s "https://zippyoddsapi.com/v1/props?league=nfl&markets=player_pass_yds" \
-H "Authorization: Bearer $ZIPPYODDS_KEY"Each row is a game with each book's markets, and a player market carries player (id, name, team, position), the line, and an over and an under. Props need the props feature on your plan and cost 3 credits a request, a page of up to 25 games. A league id being accepted doesn't mean games are on the board, and the coverage page shows which books are feeding now.
A worked example: what a spread price says
A book has a game at home -3 (-110) and away +3 (-110). Each -110 implies 110 / 210 = 52.38%. The two add up to 104.76%, so the book's margin is 4.76%. Divide each side by 1.0476 and the fair chance of each side covering is 50%.
That 50% is the number to test a model against. If your model, built on an NFL data API, says the home side covers 55% of the time, it disagrees with the market by 5 points. Over many games, closing prices are a hard benchmark to beat, so a gap that size is more often a modelling error than an edge. Check it before you trust it.
Joining odds to stats
The awkward part of using two providers is matching them. Each names teams and players its own way.
- Teams. ZippyOddsAPI team ids come from the league and the last word of the team's name, such as
nfl_chiefs. Build a lookup from those ids to your stats provider's ids once, and keep it in your code. - Players. A player id starts with
plr_and is built from the league and the player's name.team_idis always null today, andpositionis empty when the source didn't give one. Match on name and team, then check by hand any name that matches more than once. - Games. Join on the two teams and the kickoff date, not the time. Kickoffs shift, and sources disagree by minutes.
If you work across leagues, the NBA API guide covers the same split for basketball, and the college football API guide covers the extra trouble of a few hundred similar team names.
Choosing, in short
- Want results, standings or play-by-play? You want an NFL football API built on stats, not an odds service.
- Want what the books are offering on upcoming games, props included, with the time each price was read? That's ZippyOddsAPI.
- Building a model? You'll want both, joined on team and date.
The sports odds API guide explains how prices are read and dated, and the docs list every NFL-relevant endpoint and field, along with how to get a key.