Golf API documentation
14 golf data endpoints over REST and MCP. One key, credits per call.
Coming from the PGA Tour's endpoints or Data Golf? See how they compare.
Your first call
Sign up for a free key (500 credits every month, no card), swap it in for YOUR_API_KEY, and send this. list_tournaments costs 1 credit.
Request
curl -X POST https://mcp.birdieapi.com/v1/list_tournaments \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"season": 2025,
"major": true,
"limit": 3
}'Response
{
"tournaments": [
{
"tournament_id": "401703504",
"name": "Masters Tournament",
"season": 2025,
"start_date": "2025-04-10",
"end_date": "2025-04-13",
"status": "final",
"major": true,
"scoring_system": "Medal",
"rounds_scheduled": 4,
"purse": 21000000,
"field_size": 95,
...First 14 lines. Full response and every field
REST / cURL
POST to /v1/{tool_name} with your params as JSON body. No MCP client needed:
curl -X POST https://mcp.birdieapi.com/v1/list_tournaments \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY"With parameters:
curl -X POST https://mcp.birdieapi.com/v1/list_tournaments \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"season":2025,"major":true,"limit":3}'Save the raw JSON
Keep your key in an environment variable so it never sits in a script or a chat, and write each response to a file:
export BIRDIEAPI_API_KEY="your key here"
curl -s -X POST https://mcp.birdieapi.com/v1/list_tournaments \
-H "Content-Type: application/json" \
-H "x-api-key: $BIRDIEAPI_API_KEY" \
-d '{"season":2025,"major":true,"limit":3}' \
-o list_tournaments.jsonThe file holds exactly what the API returned. Tools that page their results return a next_offset; send it back as offset for the next page.
ChatGPT and Claude
Both connect to the MCP server with a sign-in instead of a key: you sign in to BirdieAPI once and press Allow. Step-by-step for ChatGPT and Claude.
Python
The official client is on PyPI. It has no required dependencies. Set BIRDIEAPI_API_KEY to your key and it is picked up automatically:
pip install birdieapiThen call any endpoint as a method (the example uses pandas, pip install "birdieapi[pandas]"):
from birdieapi import Client
client = Client()
events = client.list_tournaments(status="final", limit=3)["tournaments"]
for e in events:
print(e["tournament_id"], e["name"], e["winner_name"], e["winning_to_par"])Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"birdieapi": {
"url": "https://mcp.birdieapi.com/mcp?key=YOUR_API_KEY"
}
}
}Claude Code
One command:
claude mcp add birdieapi https://mcp.birdieapi.com/mcp?key=YOUR_API_KEY --transport streamable-httpFind the right call
All 14 questions- Which tournaments were played in 2025, and who won them?list_tournaments
- What is Scottie Scheffler's player id?search_players
- What is on this week, and who is defending?get_schedule
- Full results of the 2024 Mastersget_leaderboard
- Scheffler's final round at Augusta, hole by holeget_scorecard
- Which holes played hardest at the Masters?get_course
What timestamps mean, whether lines are pre-game, and what you can do with the data: data timing and rights.
Guides
All guidesWorking Python, JavaScript and cURL for common questions, each run against the live API.
- Where do I get strokes gained style data for golfers in Python?get_ratings
- How do I get a golfer's strokes versus the field for each round?get_player_results
- How do I get a golf tournament leaderboard in Python?get_leaderboard
- How do I get a golfer's hole-by-hole scorecard in Python?get_scorecard
- How has a golfer played at one course or event over the years?get_course_history
- How do I turn golf major winner odds into probabilities in Python?get_winner_odds
- How do I track a golfer's winner odds across the majors in Python?get_winner_odds
- How do I get the PGA Tour schedule in Python?get_schedule
- How do I get PGA Tour stat leaders in Python?get_leaders
- How do I get a golfer's season stats in Python?get_player_stats
Endpoints
14 endpoints by category. Each page has parameters, requests in three formats, a full example response and every response field.
Static reference1 credit/call
Basic lookup2 credits/call
- get_leaderboard2 creditsA tournament's full leaderboard: position, rounds, total, earnings and points
- get_course2 creditsA course as set up for a tournament: par and yards per hole and how each hole played
- get_scorecard2 creditsA player's hole-by-hole scorecard for a tournament, with par and yardage
- get_ratings2 creditsOur strokes-versus-field rating: every active player, field-strength adjusted
Stats + aggregation5 credits/call
- get_player5 creditsProfile, rating, season lines and recent finishes
- get_player_results5 creditsA player's tournaments and rounds by season, with strokes versus the field
- get_player_stats5 creditsA player's season stats: scoring, birdies, par-3/4/5 scoring, driving, greens, putting
- get_course_history5 creditsA player's record at one tournament or course, every year
- get_head_to_head5 creditsTwo players' finishes and rounds in every tournament they both played
- get_leaders5 creditsSeason leaders for any stat we compute or keep
Reference
Authentication
Every request requires an API key. Pass it via header or query parameter:
x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY
# or (MCP only)
?key=YOUR_API_KEYVerify your email, then create an API key from the dashboard. Free accounts get 500 credits every month.
Base URL
https://mcp.birdieapi.comREST API: POST /v1/{tool} with JSON body. Works with cURL, Python, any HTTP client.
MCP: POST /mcp via Streamable HTTP. Works with Claude Desktop, Claude Code, Cursor, and any MCP client.
Rate limits
| Credit balance | Rate limit |
|---|---|
| 100 credits or more | 60 req/min |
| Under 100 credits | 10 req/min |
The limit is the same on every plan. It is burst protection, not the spend boundary; credits are that, and they are enforced per request. Running low slows you down so you notice before the balance reaches zero.
Error handling
| Code | Meaning | What to do |
|---|---|---|
| 400 | Invalid parameters | Check required fields and value types |
| 401 | Invalid or missing API key | Check your x-api-key header |
| 402 | Insufficient credits | Top up your wallet or upgrade your plan |
| 429 | Rate limit exceeded | Wait and retry (see limits above) |
| 500 | Server error | Retry with idempotency key. Credits auto-refund on server errors. |
Pass x-idempotency-key or x-request-id headers to make retries duplicate-safe.
Data coverage
LPGA Tour (LPGA)
BirdieAPI also serves the LPGA. Pass "league": "lpga" to any tool that lists it, or connect to https://mcp.birdieapi.com/mcp/lpga. LPGA API coverage.
LIV Golf (LIV)
BirdieAPI also serves the LIV. Pass "league": "liv" to any tool that lists it, or connect to https://mcp.birdieapi.com/mcp/liv. LIV API coverage.
DP World Tour (DP World Tour)
BirdieAPI also serves the DP World Tour. Pass "league": "dpwt" to any tool that lists it, or connect to https://mcp.birdieapi.com/mcp/dpwt. DP World Tour API coverage.
Korn Ferry Tour (Korn Ferry Tour)
BirdieAPI also serves the Korn Ferry Tour. Pass "league": "kornferry" to any tool that lists it, or connect to https://mcp.birdieapi.com/mcp/kornferry. Korn Ferry Tour API coverage.
| Data | Status | Coverage | Volume |
|---|---|---|---|
Leaderboards and results Finishing position, ties, cut and withdrawal status, score to par, total strokes, each round, earnings and season points. | Available | PGA Tour 2001 to current | Every player in every field |
Hole-by-hole scores Strokes on each hole with par and yardage from the tournament's course setup; for pro-ams, the course each round was played on. PGA Tour, and the Korn Ferry Tour from 2007 (99% of its rounds); only round totals, not holes, are kept for the LPGA, LIV and the DP World Tour. | Available | PGA Tour 2001 to current | About 99% of PGA Tour rounds; the rest have round totals only |
Courses Par and yards per hole as set up for each tournament, and how each hole played. | Available | PGA Tour 2001 to current | Every tournament's setup |
Driving, greens and putting The stat line per player per tournament: driving distance and accuracy, greens in regulation, putts per green, sand saves. PGA Tour only; no strokes gained by category and no shot-level data. | Partial | PGA Tour, from 2011 | Per player per tournament |
Major winner odds Each sportsbook's price on every priced golfer to win the Masters, PGA Championship, U.S. Open and Open Championship before the first round: the opening price, the latest price and every snapshot, with the implied probability, linked to our player id where the name matches the field. The four men's majors only; past majors are weekly archive snapshots, so their latest price can be up to a week before the first tee time; an upcoming major is refreshed daily while its market is open (every six hours in tournament week) and not at all once the first round starts; the 2020 U.S. Open has one snapshot and 2021 fewer than later years; no round, matchup or other-tournament markets. | Partial | The four majors from 2021 (and the 2020 U.S. Open), plus the next edition of each while its market is open | Weekly archive snapshots per sportsbook and golfer, then daily (every six hours in tournament week) while a major's market is open |
Strokes versus the field Each round against its field's average on the same course, adjusted for field strength (score-based, the same idea as strokes gained: total), and a rating after every tournament. The PGA Tour and Korn Ferry Tour also get par 3, 4 and 5 splits (sg_par3, sg_par4, sg_par5); there are no shot-level splits. | Available | Each tour's seasons with leaderboards (PGA Tour 2001 on; Korn Ferry Tour 2007 on; LPGA, LIV and DP World Tour with the gaps their pages list) | Full 18-hole rounds in fields of ten or more |
Coverage describes the datasets BirdieAPI supports. Freshness and operational health are tracked separately.
Odds snapshot definitions
opening: A sportsbook's first weekly snapshot of the golfer's winner price for the major, from the sportsbook odds archive.
closing: The sportsbook's last snapshot before the first round's start date, which for a past major can be up to a week before the first tee time.
Odds coverage currently documents winner prices for the four men's majors from DraftKings, FanDuel, BetMGM, ESPN BET and Pinnacle, among other books, as the sportsbook odds archive holds them. Outright winner prices for the four men's majors only, from 2021: weekly archive snapshots for past majors, refreshed daily for an upcoming major while its market is open, none once play starts; no round, matchup, three-ball or finishing-position prices, nothing for other tournaments or tours, and no in-play prices. Winner prices for the four men's majors from 2021 (one snapshot of the 2020 U.S. Open), weekly, from the sportsbook odds archive. No round, matchup or other-tournament prices, and none for the LPGA, LIV or the DP World Tour.
Response format
REST API
All successful REST responses wrap the result in a data key:
{ "data": { "tournaments": [...], "count": 49 } }Error responses return:
{ "error": "Insufficient credits", "message": "This tool costs 5 credits, you have 2" }MCP Protocol
MCP responses follow the standard MCP tool result format. The data is returned directly (no data wrapper). Both access methods return identical data, just different envelopes.
Conventions
Seasons: 4-digit season year (the PGA Tour's season as filed; from 2014 to 2024 seasons began the October before). Example: 2025.
Tournament IDs: Event ids, e.g. 401580344 (the 2024 Masters). Get them from list_tournaments or get_schedule.
Player IDs: Athlete ids, the same on every tour. Get them from search_players, or from any leaderboard.
Course IDs: list_tournaments lists each tournament's courses; pass one to get_course or get_course_history.
Pagination: Endpoints use a limit parameter. No cursor or offset. Narrow your filters to get different slices of data.
Credits: Deducted before the request executes. Automatically refunded on server errors. Monthly credits are used first, then wallet balance.