# BirdieAPI

> The golf data API. 13 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

## 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`
- 500 free credits on signup, 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 ESPN files it; from 2014 to 2024 seasons began the October before). Tournament ids like 401580344 (an ESPN tournament id; list_tournaments returns them).

## 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 ESPN keeps -> get_leaders (5 cr)

## Intents

- "Which tournaments were played in 2024, 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 2024, round by round" -> get_player_results
- "How many birdies a round did Scheffler make in 2024?" -> get_player_stats
- "How has Rory McIlroy played at the Masters over the years?" -> get_course_history
- "Scheffler against McIlroy in 2024" -> get_head_to_head
- "Who led the PGA Tour in strokes versus the field in 2024?" -> get_leaders

## 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.
- [Data atlas](https://birdieapi.com/docs/atlas): what exists, which endpoints expose it, and where coverage is partial.
- [Pricing](https://birdieapi.com/pricing): credits per call and what a plan includes.
- [Sign up](https://birdieapi.com/signup): 500 free credits, no card.

### Other leagues

- [The LPGA data API](https://birdieapi.com/lpga): LPGA Tour leaderboards from public ESPN data: 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 from public ESPN data 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) from public ESPN data: 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

### 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.

### Compared with the alternatives

- [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.
- [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 stores, joins and serves it as documented tools over REST and MCP.

### 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 ESPN keeps

### 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.
- [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.

### 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 ESPN's stable ids.