# BirdieAPI

> The golf data API. 14 golf data tools for AI agents. REST API + MCP server.

Full reference with response shapes: https://birdieapi.com/llms-full.txt
MCP server setup: https://birdieapi.com/llms-install.md
MCP server for AI agents (clients, prompts, every tool): https://birdieapi.com/mcp
Datasets with live coverage by season: https://birdieapi.com/docs/atlas
Tool catalogue with JSON Schema: https://mcp.birdieapi.com/v1/tools
OpenAPI 3.1 spec: https://mcp.birdieapi.com/openapi.json

## Quick Start

- API base URL: https://mcp.birdieapi.com
- Auth: `Authorization: Bearer YOUR_API_KEY` or `x-api-key: YOUR_API_KEY`
- MCP server: `https://mcp.birdieapi.com/mcp?key=YOUR_API_KEY`
- Python client: `pip install birdieapi` (https://pypi.org/project/birdieapi/). Reads BIRDIEAPI_API_KEY.
- 500 free credits every month, no credit card required
- REST API responses include `X-Credits-Used` and `X-Credits-Remaining` headers
- Seasons: 4-digit season year (the PGA Tour's season as filed; from 2014 to 2024 seasons began the October before). Tournament ids like 401580344 (a tournament id; list_tournaments returns them).

## Data timing and rights

- Odds and props are pre-game only. captured_at is when a line was captured (the page says exactly what it means for each kind of row); where props are held, rows also carry scheduled_start and minutes_before_scheduled_start (negative when captured after the scheduled start).
- Records are overwritten when sources correct them; no revision history is kept.
- You may store the data, train models, backtest, and build commercial products that show your users what you derive. You may not redistribute the data, or odds as a raw feed, as a dataset or API of its own. After an account closes, stored data is for internal use only.
- BirdieAPI is independent, not an official league partner, and grants no league rights.
- Full answers: https://birdieapi.com/docs/timing-and-rights

## Which Tool Should I Use?

### Static reference
- A season's tournaments with dates, winner, purse and courses -> list_tournaments (1 cr)
- Tournaments this week and coming up, with the host course -> get_schedule (1 cr)
- Find players by name -> search_players (1 cr)

### Basic lookup
- A tournament's full leaderboard: position, rounds, total, earnings and points -> get_leaderboard (2 cr)
- A course as set up for a tournament: par and yards per hole and how each hole played -> get_course (2 cr)
- A player's hole-by-hole scorecard for a tournament, with par and yardage -> get_scorecard (2 cr)
- Our strokes-versus-field rating: every active player, field-strength adjusted -> get_ratings (2 cr)

### Stats + aggregation
- Profile, rating, season lines and recent finishes -> get_player (5 cr)
- A player's tournaments and rounds by season, with strokes versus the field -> get_player_results (5 cr)
- A player's season stats: scoring, birdies, par-3/4/5 scoring, driving, greens, putting -> get_player_stats (5 cr)
- A player's record at one tournament or course, every year -> get_course_history (5 cr)
- Two players' finishes and rounds in every tournament they both played -> get_head_to_head (5 cr)
- Season leaders for any stat we compute or keep -> get_leaders (5 cr)

### Time-series
- The four majors' winner prices by sportsbook before the first round: opening and latest, with implied probability -> get_winner_odds (5 cr)

## Intents

- "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 Masters" -> get_leaderboard
- "Scheffler's final round at Augusta, hole by hole" -> get_scorecard
- "Which holes played hardest at the Masters?" -> get_course
- "Who are the best players in the world right now?" -> get_ratings
- "Scheffler's career in one call" -> get_player
- "Every tournament Scheffler played in 2025, round by round" -> get_player_results
- "How many birdies a round did Scheffler make in 2025?" -> get_player_stats
- "How has Rory McIlroy played at the Masters over the years?" -> get_course_history
- "Scheffler against McIlroy in 2025" -> get_head_to_head
- "Who led the PGA Tour in strokes versus the field in 2025?" -> get_leaders
- "Who were the favourites to win the 2024 Masters, and how did their prices move?" -> get_winner_odds

## Pages

- [Docs](https://birdieapi.com/docs): every endpoint, with parameters and a live example response.
- [Data changelog](https://birdieapi.com/changelog): when each dataset was last refreshed and what it runs through, read from the database.
- [Status](https://birdieapi.com/status): measured uptime for the website and MCP server over 24 hours, 7 days and 90 days, probed every five minutes from outside our own infrastructure, with incidents and data freshness.
- [Data atlas](https://birdieapi.com/docs/atlas): what exists, which endpoints expose it, and where coverage is partial.
- [Players](https://birdieapi.com/players): a page per PGA Tour player with career wins, top tens, cuts, earnings, scoring average, strokes versus the field, a line per season and recent results.
- [Data timing and rights](https://birdieapi.com/docs/timing-and-rights): what timestamps mean, when each dataset updates, whether lines are pre-game, and what the terms allow.
- [Pricing](https://birdieapi.com/pricing): credits per call and what a plan includes.
- [Sign up](https://birdieapi.com/signup): 500 free credits every month, no card.

### Live odds

- [Golf major winner odds](https://birdieapi.com/odds): Winner prices for the next Masters, PGA Championship, U.S. Open and Open Championship from tracked sportsbooks, with each golfer's implied and margin-free probability. Refreshed daily while a major's market is open.

### Other leagues

- [The LPGA data API](https://birdieapi.com/lpga): LPGA Tour leaderboards: 436 tournaments with every player's finish, round scores and earnings, plus a strokes-versus-field rating. REST and MCP. MCP: https://mcp.birdieapi.com/mcp/lpga
- [The LIV Golf data API](https://birdieapi.com/liv): LIV Golf since the first event in June 2022: 62 individual leaderboards, every round score and a strokes-versus-field rating. REST and MCP. MCP: https://mcp.birdieapi.com/mcp/liv
- [The DP World Tour data API](https://birdieapi.com/dp-world-tour): DP World Tour (European Tour): 598 leaderboards since 2009, about 240,000 round scores and a strokes-versus-field rating. REST and MCP. MCP: https://mcp.birdieapi.com/mcp/dpwt
- [The Korn Ferry Tour data API](https://birdieapi.com/korn-ferry-tour): Korn Ferry Tour since 2007: full leaderboards for 524 finished tournaments, about 230,000 round scores with the strokes on each hole, and a strokes-versus-field rating. REST and MCP. MCP: https://mcp.birdieapi.com/mcp/kornferry

### Datasets

- [PGA Tour hole-by-hole data](https://birdieapi.com/data/pga-tour-hole-by-hole-data): Strokes on each hole for about 99% of PGA Tour rounds since 2001, with par and yardage from the course setup. REST or MCP.
- [Golf leaderboard and results data](https://birdieapi.com/data/golf-leaderboard-data): Full PGA Tour leaderboards since 2001, every player in every field, with rounds, status and money; the LPGA, LIV and DP World Tour through the same tools.
- [PGA Tour player stats data](https://birdieapi.com/data/pga-tour-stats-data): Driving distance and accuracy, greens in regulation, putts per green and sand saves per player per PGA Tour tournament, with scoring stats counted from every hole.
- [Golf major winner odds by sportsbook](https://birdieapi.com/data/major-winner-odds): Pre-tournament winner prices for the Masters, PGA Championship, U.S. Open and Open Championship by sportsbook, from 2021, with how they moved. REST or MCP.

### Compared with the alternatives

- [The PGA Tour API: free endpoints, Data Golf and BirdieAPI](https://birdieapi.com/compare/golf-api): The PGA Tour's site API, ESPN's golf JSON and Data Golf differ in access, cost and depth. Where each fits, and how BirdieAPI differs. (checked 2026-10-14)
- [BirdieAPI vs the Data Golf API](https://birdieapi.com/compare/data-golf-api): Data Golf's API sells model predictions, strokes gained and odds. BirdieAPI serves leaderboards and hole-by-hole scores over REST and MCP, paid per call. (checked 2026-10-08)
- [BirdieAPI vs calling ESPN's golf endpoints yourself](https://birdieapi.com/compare/espn-golf-api): ESPN's golf JSON is public but undocumented and split across endpoints. BirdieAPI serves golf results as documented tools over REST and MCP. (checked 2026-10-08)
- [BirdieAPI vs SportsDataIO](https://birdieapi.com/compare/sportsdataio-golf): SportsDataIO's golf API has live scores, odds, props and projections, sold via sales. BirdieAPI: historical results and scores, self-serve, major winner odds only. (checked 2026-10-09)
- [BirdieAPI vs Sportradar](https://birdieapi.com/compare/sportradar-golf): Sportradar sells licensed, live golf feeds by contract. BirdieAPI is historical results and hole-by-hole scores, self-serve, 500 free credits a month. (checked 2026-10-09)

### Endpoint pages

- [list_tournaments](https://birdieapi.com/docs/list-tournaments): A season's tournaments with dates, winner, purse and courses
- [get_schedule](https://birdieapi.com/docs/get-schedule): Tournaments this week and coming up, with the host course
- [get_leaderboard](https://birdieapi.com/docs/get-leaderboard): A tournament's full leaderboard: position, rounds, total, earnings and points
- [get_course](https://birdieapi.com/docs/get-course): A course as set up for a tournament: par and yards per hole and how each hole played
- [search_players](https://birdieapi.com/docs/search-players): Find players by name
- [get_player](https://birdieapi.com/docs/get-player): Profile, rating, season lines and recent finishes
- [get_player_results](https://birdieapi.com/docs/get-player-results): A player's tournaments and rounds by season, with strokes versus the field
- [get_player_stats](https://birdieapi.com/docs/get-player-stats): A player's season stats: scoring, birdies, par-3/4/5 scoring, driving, greens, putting
- [get_scorecard](https://birdieapi.com/docs/get-scorecard): A player's hole-by-hole scorecard for a tournament, with par and yardage
- [get_course_history](https://birdieapi.com/docs/get-course-history): A player's record at one tournament or course, every year
- [get_head_to_head](https://birdieapi.com/docs/get-head-to-head): Two players' finishes and rounds in every tournament they both played
- [get_ratings](https://birdieapi.com/docs/get-ratings): Our strokes-versus-field rating: every active player, field-strength adjusted
- [get_leaders](https://birdieapi.com/docs/get-leaders): Season leaders for any stat we compute or keep
- [get_winner_odds](https://birdieapi.com/docs/get-winner-odds): The four majors' winner prices by sportsbook before the first round: opening and latest, with implied probability

### Metric definitions

- [Strokes versus the field](https://birdieapi.com/glossary/strokes-versus-field): How many strokes better than the field's average a round was, on the same course on the same day.
- [Field-strength adjustment](https://birdieapi.com/glossary/field-strength): Strokes versus the field, corrected for how good the players in that field were.
- [Par 3, par 4 and par 5 splits](https://birdieapi.com/glossary/par-type-splits): Strokes versus the field on par 3, par 4 and par 5 holes separately, PGA Tour and Korn Ferry Tour.
- [Scoring average](https://birdieapi.com/glossary/scoring-average): The mean score of a player's full 18-hole rounds.
- [Score to par](https://birdieapi.com/glossary/score-to-par): Strokes taken against the par of a hole or a round: a birdie is one under, a bogey one over.
- [Made cut](https://birdieapi.com/glossary/made-cut): Finishing inside the score line that decides who plays the last rounds of a tournament.
- [Course history](https://birdieapi.com/glossary/course-history): How a player has done at one tournament, or on one course, over the years.
- [Greens in regulation](https://birdieapi.com/glossary/greens-in-regulation): The share of holes where the ball reached the green with at least two putts left for par.
- [Putts per green in regulation](https://birdieapi.com/glossary/putts-per-gir): The average number of putts on the holes where a player reached the green in regulation.
- [Driving accuracy](https://birdieapi.com/glossary/driving-accuracy): The share of par 4 and par 5 tee shots that finish in the fairway.
- [Driving distance](https://birdieapi.com/glossary/driving-distance): The average length of a player's measured drives in a tournament, in yards.
- [Playoff](https://birdieapi.com/glossary/playoff): Extra holes played when two or more players tie for the lead after the last round.
- [Major championship](https://birdieapi.com/glossary/major): The four biggest men's events: the Masters, the PGA Championship, the U.S. Open and The Open.
- [Outright winner odds](https://birdieapi.com/glossary/outright-winner-odds): A sportsbook's price on a golfer to win the whole tournament, posted weeks or months before the first round.

### By what you are building

- [Bettors and modellers](https://birdieapi.com/for/bettors): PGA Tour rounds since 2001 measured against their fields, a player's record at every course, and two players' meetings, ready for outright and matchup models.
- [Analysts and researchers](https://birdieapi.com/for/analysts): Hole-by-hole strokes with par and yardage for every PGA Tour round since 2001, full leaderboards on four tours, and ratings computed from every round.
- [Developers and AI builders](https://birdieapi.com/for/developers): REST and MCP over the same data: tournaments, leaderboards, scorecards, players and ratings, with stable ids.

### Code guides

Python, JavaScript and cURL for common questions, each run against the live API (code verified 2026-10-12). Index: https://birdieapi.com/guides

- [Where do I get strokes gained style data for golfers in Python?](https://birdieapi.com/guides/golf-strokes-gained-style-ratings-python): A rating in strokes per round better than the field, adjusted for field strength and weighted toward recent rounds, for every active player. Tool: get_ratings.
- [How do I get a golfer's strokes versus the field for each round?](https://birdieapi.com/guides/golf-player-strokes-vs-field-python): Every tournament a player teed up in a season, with each round's strokes, the field average that day and the difference, raw and adjusted for field strength. Tool: get_player_results.
- [How do I get a golf tournament leaderboard in Python?](https://birdieapi.com/guides/golf-tournament-leaderboard-python): A tournament's full leaderboard with position, each round, total, earnings and cup points, and the course and purse alongside. Tool: get_leaderboard.
- [How do I get a golfer's hole-by-hole scorecard in Python?](https://birdieapi.com/guides/golf-hole-by-hole-scorecard-python): Every hole of every round a player played in a tournament, with par, yardage, strokes and the result of each hole. Tool: get_scorecard.
- [How has a golfer played at one course or event over the years?](https://birdieapi.com/guides/golf-course-history-python): A player's result at one tournament in every year they played it, with finish, score, earnings and strokes against the field, plus a career summary. Tool: get_course_history.
- [How do I turn golf major winner odds into probabilities in Python?](https://birdieapi.com/guides/golf-major-winner-odds-implied-probability-python): Every golfer's pre-tournament winner price at a men's major, opening and latest, as implied probability. At the 2025 Masters the 125 prices added up to 150%. Tool: get_winner_odds.
- [How do I track a golfer's winner odds across the majors in Python?](https://birdieapi.com/guides/golf-golfer-major-odds-movement-python): One golfer's opening and latest winner price at every major he was priced for, as implied probability. Scottie Scheffler was priced for 28 majors from 2021 to 2027. Tool: get_winner_odds.
- [How do I get the PGA Tour schedule in Python?](https://birdieapi.com/guides/pga-tour-schedule-python): PGA Tour events in the next 45 days with dates, purse, course and defending champion. Six events were listed, $39.4 million in total purse. Tool: get_schedule.
- [How do I get PGA Tour stat leaders in Python?](https://birdieapi.com/guides/golf-stat-leaders-python): Fifteen PGA Tour players ranked on driving distance for 2026, with the sample behind each. Aldrich Potgieter led at 331.6 yards. Tool: get_leaders.
- [How do I get a golfer's season stats in Python?](https://birdieapi.com/guides/golf-player-season-stats-python): A golfer's season: starts, wins, scoring average, strokes versus the field, hole scoring and ball striking. Scottie Scheffler won 3 of 20 starts in 2026. Tool: get_player_stats.

### Claude skills

16 free Claude skills (SKILL.md files) wired to these tools: https://github.com/noahowsh/birdieapi-mcp/tree/main/skills. Overview: https://birdieapi.com/skills

- tournament-lookup (Data Exploration): Find tournaments, winners, schedules and full leaderboards on every tour.
- player-scouting (Data Exploration): Player ids, career and season lines, recent rounds and head-to-head.
- odds-explorer (Data Exploration): Compare major winner prices across books and read how they moved.
- tournament-preview (Data Exploration): Course, form, course record and market in one pre-tournament read.
- strokes-vs-field (Golf Analytics): Rate and rank golfers on strokes versus the field, adjusted for field strength.
- hole-scoring (Golf Analytics): Par 3/4/5 splits, birdie and bogey rates, hole difficulty and scorecards.
- course-fit (Golf Analytics): A player's record at one event or course, shrunk toward general form.
- outright-model (Golf Analytics): Simulate a tournament from ratings and compare with the devigged market.
- feature-engineering (Methodology): Leak-free golf features: as-of ratings, rolling form, course history.
- walk-forward-validation (Methodology): Time-ordered, tournament-grouped testing with a market baseline.
- probability-calibration (Methodology): Reliability checks for made-cut, top-10 and winner probabilities.
- odds-analysis (Methodology): Implied probability, overround and devigging for a 100-runner outright.
- edge-detection (Betting): EV, joint Kelly on mutually exclusive winners and sample-size reality.
- backtesting (Betting): Test rules on past majors with bootstrap intervals; bet log template.
- dispatch (Workflow): Routes a golf request to the right 2-3 skills.
- birdieapi-tool (Infrastructure): All 14 BirdieAPI tools, credits, the league switch and the data envelope.