What if you could describe what you want to build and have AI write the code for you? With our OpenAPI specification, that's exactly what you can do.
New to the API? Start with our Getting Started guide first to set up your account and API key.
The OpenAPI Specification
The BALLDONTLIE API has a complete OpenAPI specification available at:
This machine-readable file describes every endpoint, parameter, and response format in our API. Modern LLMs like ChatGPT and Claude can parse this specification and generate accurate integration code.
The Basic Workflow
- Copy the OpenAPI spec URL:
https://balldontlie.io/openapi.yml - Paste it into ChatGPT, Claude, or your preferred AI assistant
- Describe what you want to build
- Get working code in seconds
Let's see this in action.
Example 1: Fetching Box Scores
Prompt to ChatGPT/Claude:
Using the OpenAPI spec at https://balldontlie.io/openapi.yml, write a Python script that fetches today's NBA games with box scores and prints each team's score. Use the requests library and include error handling.
Generated code:
import requests
from datetime import date
API_KEY = "your-api-key"
BASE_URL = "https://api.balldontlie.io"
headers = {"Authorization": API_KEY}
today = date.today().isoformat()
# Fetch today's box scores
response = requests.get(
f"{BASE_URL}/nba/v1/box_scores",
headers=headers,
params={"date": today}
)
if response.status_code != 200:
print(f"Error: {response.status_code}")
exit(1)
data = response.json()
print(f"NBA Games - {today}")
print("=" * 50)
for game in data.get("data", []):
home = game["home_team"]
away = game["visitor_team"]
print(f"\n{away['full_name']} @ {home['full_name']}")
print(f"Score: {game['visitor_team_score']} - {game['home_team_score']}")
print(f"Status: {game['status']}")
Output:
NBA Games - 2025-12-07
==================================================
Orlando Magic @ New York Knicks
Score: 100 - 106
Status: Final
Boston Celtics @ Toronto Raptors
Score: 60 - 47
Status: 2nd Qtr
Denver Nuggets @ Charlotte Hornets
Score: 0 - 0
Status: 2025-12-07T23:00:00Z
Portland Trail Blazers @ Memphis Grizzlies
Score: 0 - 0
Status: 2025-12-07T23:00:00Z
Golden State Warriors @ Chicago Bulls
Score: 0 - 0
Status: 2025-12-08T00:00:00Z
Example 2: Formatting Betting Odds
Prompt to ChatGPT/Claude:
Using the OpenAPI spec at https://balldontlie.io/openapi.yml, create a Python script that gets current betting odds for tonight's NBA games and formats them as a table showing the sportsbook, spread, moneyline, and total for each game.
Generated code:
import requests
from datetime import date
from collections import defaultdict
API_KEY = "your-api-key"
BASE_URL = "https://api.balldontlie.io"
headers = {"Authorization": API_KEY}
today = date.today().isoformat()
# Get games
games_response = requests.get(
f"{BASE_URL}/nba/v1/games",
headers=headers,
params={"dates[]": today}
)
games = {g["id"]: g for g in games_response.json()["data"]}
# Get odds
odds_response = requests.get(
f"{BASE_URL}/nba/v2/odds",
headers=headers,
params={"dates[]": today}
)
# Group odds by game
game_odds = defaultdict(list)
for odd in odds_response.json()["data"]:
game_odds[odd["game_id"]].append(odd)
print(f"NBA Betting Odds - {today}")
print("=" * 70)
for game_id, odds_list in game_odds.items():
if game_id not in games:
continue
game = games[game_id]
home = game["home_team"]["abbreviation"]
away = game["visitor_team"]["abbreviation"]
print(f"\n{away} @ {home}")
print("-" * 70)
print(f"{'Sportsbook':<12} {'Spread':<15} {'Moneyline':<20} {'Total'}")
print("-" * 70)
for odd in sorted(odds_list, key=lambda x: x["vendor"])[:5]:
spread = f"{home} {odd['spread_home_value']} ({odd['spread_home_odds']:+d})"
ml = f"{home} {odd['moneyline_home_odds']:+d}"
total = f"O/U {odd['total_value']}"
print(f"{odd['vendor'].capitalize():<12} {spread:<15} {ml:<20} {total}")
Output:
NBA Betting Odds - 2025-12-07
======================================================================
ORL @ NYK
----------------------------------------------------------------------
Sportsbook Spread Moneyline Total
----------------------------------------------------------------------
Ballybet NYK -10.5 (-118) NYK -3335 O/U 202.5
Bet365 NYK -5.5 (-115) NYK -20000 O/U 203.5
Betmgm NYK -10.5 (-140) NYK -10000 O/U 200.5
Betparx NYK -11 (-129) NYK -10000 O/U 202
Betrivers NYK -10.5 (-113) NYK -5000 O/U 202.5
Tips for Better Prompts
-
Be specific about the output format: "Format as a table", "Output as JSON", "Print one line per game"
-
Mention the league: The API covers NBA, NFL, MLB, NHL, EPL, WNBA, NCAAF, and NCAAB. Be clear about which one you want.
-
Ask for error handling: LLMs often skip error handling unless you ask. Include "with error handling" in your prompt.
-
Request comments: Add "include comments explaining each step" if you want to learn from the code.
-
Specify the language: We used Python here, but you can ask for JavaScript, TypeScript, Go, or any language.
Example Prompts to Try
Here are some prompts you can copy and modify:
- "Write a script that fetches NBA player stats for the last 10 games and calculates their averages"
- "Create a function that compares player prop lines across different sportsbooks for a given game"
- "Build a script that tracks NFL team standings and alerts when my team's ranking changes"
- "Generate code that fetches EPL match results and calculates each team's win percentage"
Why This Works
The OpenAPI specification contains:
- Every endpoint URL and HTTP method
- Required and optional parameters
- Response schemas with all field types
- Authentication requirements
- Example requests and responses
LLMs can parse this structured data and generate code that matches the actual API behavior, not just guessing at endpoint names.
Next Steps
Now that you can quickly generate scripts, try building a real tool. Our odds comparison tutorial walks you through finding betting value by comparing lines across sportsbooks.
Want to customize these scripts further? Just ask the AI to modify them. Describe what you want to change and paste the existing code for context.