Skip to content
BirdieAPI

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

json
{
  "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:

bash
curl -X POST https://mcp.birdieapi.com/v1/list_tournaments \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

With parameters:

bash
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:

bash
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.json

The 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:

bash
pip install birdieapi

Then call any endpoint as a method (the example uses pandas, pip install "birdieapi[pandas]"):

python
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:

json
{
  "mcpServers": {
    "birdieapi": {
      "url": "https://mcp.birdieapi.com/mcp?key=YOUR_API_KEY"
    }
  }
}

Claude Code

One command:

bash
claude mcp add birdieapi https://mcp.birdieapi.com/mcp?key=YOUR_API_KEY --transport streamable-http

Find the right call

All 14 questions

What timestamps mean, whether lines are pre-game, and what you can do with the data: data timing and rights.

Working Python, JavaScript and cURL for common questions, each run against the live API.

Endpoints

14 endpoints by category. Each page has parameters, requests in three formats, a full example response and every response field.

Reference

Authentication

Every request requires an API key. Pass it via header or query parameter:

bash
x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY
# or (MCP only)
?key=YOUR_API_KEY

Verify your email, then create an API key from the dashboard. Free accounts get 500 credits every month.

Base URL

text
https://mcp.birdieapi.com

REST 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 balanceRate limit
100 credits or more60 req/min
Under 100 credits10 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

CodeMeaningWhat to do
400Invalid parametersCheck required fields and value types
401Invalid or missing API keyCheck your x-api-key header
402Insufficient creditsTop up your wallet or upgrade your plan
429Rate limit exceededWait and retry (see limits above)
500Server errorRetry 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.

DataStatusCoverageVolume
Leaderboards and results
Finishing position, ties, cut and withdrawal status, score to par, total strokes, each round, earnings and season points.
AvailablePGA Tour 2001 to currentEvery 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.
AvailablePGA Tour 2001 to currentAbout 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.
AvailablePGA Tour 2001 to currentEvery 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.
PartialPGA Tour, from 2011Per 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.
PartialThe four majors from 2021 (and the 2020 U.S. Open), plus the next edition of each while its market is openWeekly 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.
AvailableEach 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:

json
{ "data": { "tournaments": [...], "count": 49 } }

Error responses return:

json
{ "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.

Ready to start?

500 free credits every month. No credit card required.

Get a free key