"NBA API" is a search with several answers. Some developers want box scores and shot charts, some want live scores for an app, and some want what the sportsbooks are offering on tonight's games. A statistics source answers the first, a scores source the second, and an odds service the third.
ZippyOddsAPI is an odds service. For the NBA it returns games on the board with each book's moneyline, spread and total, quarter and half lines where books offer them, player props, pick'em lines, and boards built from those prices, such as +EV and best lines. It doesn't return box scores or play-by-play. Below is how the pieces fit, and what each looks like in code.
Stats: the community client and reference sites
The name many Python developers have in mind is nba_api, a community client for NBA.com's stats endpoints. It's an open-source package, not an official product of the league, and its own documentation is the place to learn what it covers, how to install it and how to use it responsibly. Read that before you build on it, and read the league site's terms too, since the data comes from there.
The other common search is for a basketball reference API, meaning a way to get the tables from that stats website into a program. Before you collect anything from a reference site, check its own terms and any data-use page it publishes, which say what automated access it allows. Only the site can tell you that.
Whichever source you use, an NBA statistics API gives you what happened: minutes, usage, shooting splits, possessions. It doesn't give you the market's view of what will happen next, and that's where odds come in.
What ZippyOddsAPI returns for NBA games
A first request for the main markets in decimal odds:
curl -s "https://zippyoddsapi.com/v1/odds?league=nba&format=decimal" \
-H "Authorization: Bearer $ZIPPYODDS_KEY"Each row is a game with start_time, home, away and status, and a bookmakers list. Each bookmaker has its markets, and each market has its key, period, line and outcomes. Every book's entry carries updated_at, the time its prices were read, so you can see how old each price is. A league id being accepted doesn't mean there are games on the board, so /v1/leagues and the coverage page are the places to check what's there now.
Quarters, halves and the period field
Basketball books often price quarters and halves as well as the full game. In ZippyOddsAPI those lines have their own period: 1q to 4q for quarters, 1h and 2h for halves, and full_game by default. A period is what the source said it was, and it's never assumed, so a first-quarter total never sits among full-game totals.
Ask for periods by name: periods=1q,1h. /v1/leagues lists the periods actually on the board for the NBA at the moment, which is more useful than guessing, since not every book posts every period.
Player props and pick'em lines
The NBA catalog includes player_points, player_rebounds, player_assists, player_threes and player_pra (points, rebounds and assists combined). /v1/props returns them from sportsbooks and pick'em apps together:
curl -s "https://zippyoddsapi.com/v1/props?league=nba&markets=player_points,player_pra" \
-H "Authorization: Bearer $ZIPPYODDS_KEY"A pick'em app appears as a bookmaker with type: "dfs", and its outcomes can have price: null, because a pick'em app pays by entry, not by a price on each pick. Pass include_dfs=false to leave those apps out. Props need the props feature on your plan, and the docs list which endpoints need which feature.
A worked example: one over, two prices
Two books have the same player at over 27.5 points. One prices it at -120, the other at -105.
- At -120 you risk $120 to win $100, so the over has to win 120 / 220 = 54.55% of the time to break even.
- At -105 you risk $105 to win $100, and the break-even is 105 / 205 = 51.22%.
Same player, same line, and a 3.33-point difference in how often the bet has to win. Over hundreds of bets, that gap can be bigger than a model's whole edge. /v1/best-lines?league=nba&markets=player_points returns the best fresh price on each side and which books have it, so you don't have to scan every book yourself. A price past its age limit never sets a best line there.
Live games and the NBA scores API question
ZippyOddsAPI's /v1/scores lists games in progress with their current score, and it needs a plan that includes live data. Once a source reports a game final, it leaves the board. So it works as a live view next to live prices, but it isn't an NBA scores API for looking up results after the fact, and it doesn't carry the game clock. If you need finished scores, use a results source and join on teams and date.
For live prices, the stream at /v1/stream sends a snapshot and then changes as books are read, and an event message when a score or status changes.
Putting a stack together
- Research and modelling: a statistics source for what happened, plus ZippyOddsAPI's
/v1/historyfor how a game's full-game moneyline, spread or total moved, with points kept for 30 days. - A price comparison app: ZippyOddsAPI on its own, with
best-linesand the age of every price. - A scores app: a results source. An NBA data API built around odds is the wrong tool for a scoreboard.
The same split applies to other sports. The sports API guide covers the categories in general, the college football API guide covers the team-matching problems of a league with far more teams, and the sports odds API guide covers how prices are read and dated. If you only need one NBA stat API call to settle a question, a stats source is the right place to start.