003 Name Skill 154869da

---
name: golf-data
description: |
  PGA Tour, LPGA, and DP World Tour golf data via ESPN public endpoints — tournament leaderboards, scorecards, season schedules, golfer profiles/overviews, and news. Zero config, no API keys.

  Use when: user asks about golf scores, tournament leaderboards, scorecards, PGA Tour schedule, golfer profiles, golfer season stats, LPGA results, or golf news.
  Don't use when: user asks about other sports.
license: MIT
metadata:
  author: machina-sports
  version: "0.1.0"
---

# Golf Data (PGA / LPGA / DP World Tour)

## Setup

Before first use, check if the CLI is available:
```bash
which sports-skills || pip install sports-skills
```
If `pip install` fails with a Python version error, the package requires Python 3.10+. Find a compatible Python:
```bash
python3 --version  # check version
# If < 3.10, try: python3.12 -m pip install sports-skills
# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills
```
No API keys required.

## Quick Start

Prefer the CLI — it avoids Python import path issues:
```bash
sports-skills golf get_leaderboard --tour=pga
sports-skills golf get_schedule --tour=pga --year=2026
sports-skills golf get_news --tour=pga
```

## Important: Golf is Not a Team Sport

Golf data is fundamentally different from team sports (NFL, NBA, etc.):
- **Tournaments, not games**: Each event is a multi-day tournament (typically 4 rounds, Thu–Sun).
- **Individual athletes**: The leaderboard has 72–147 individual golfers, not 2 teams.
- **Score relative to par**: Scores are strings like "-17", "E" (even), "+2" — not point totals.
- **Round-by-round scoring**: Each golfer has 4 round scores (stroke count and score-to-par).
- **One event per week**: Unlike team sports with multiple games per day, golf has one tournament per week per tour.
- **No standings/rankings endpoint**: FedEx Cup standings are not available via this API.

## The `tour` Parameter

Most commands require `--tour=pga`, `--tour=lpga`, or `--tour=eur`:
- **PGA**: PGA Tour (men's professional golf)
- **LPGA**: LPGA Tour (women's professional golf)
- **EUR**: DP World Tour (formerly European Tour)

If the user doesn't specify, default to `pga`. If they say "women's golf" or "LPGA", use `lpga`. If they mention the European Tour or DP World Tour, use `eur`.

## Commands

### get_leaderboard
Get the current tournament leaderboard with all golfer scores.
- `tour` (str, required): "pga", "lpga", or "eur"

Returns the current/most recent tournament with:
- Tournament name, venue, status, current round
- `leaderboard[]` sorted by position with golfer name, country, total score, and round-by-round scores
- `field_size` — total number of golfers in the field

The leaderboard is sorted by position (1 = leader). Each golfer has:
- `position`: Leaderboard rank
- `name`: Golfer name
- `country`: Nationality
- `score`: Total score relative to par (e.g., "-17", "E", "+2")
- `rounds[]`: Array of round scores with stroke count and score-to-par

### get_schedule
Get full season tournament schedule.
- `tour` (str, required): "pga", "lpga", or "eur"
- `year` (int, optional): Season year. Defaults to current.

Returns `tournaments[]` with tournament name, ID, start/end dates. Useful for answering "when is the Masters?" or "what tournaments are coming up?"

### get_player_info
Get individual golfer profile.
- `player_id` (str, required): ESPN athlete ID
- `tour` (str, optional): "pga", "lpga", or "eur". Defaults to "pga".

Returns golfer details: name, age, nationality, birthplace, height/weight, turned pro year, college, headshot URL, and ESPN profile link.

**Finding player IDs:** Player IDs appear in leaderboard results (`id` field on each golfer). You can also find them in ESPN golf URLs (e.g., espn.com/golf/player/_/id/9478/scottie-scheffler → ID is 9478).

**Note:** Player profiles work for PGA Tour and DP World Tour golfers. LPGA player profiles are not available through ESPN's API — the command will automatically try PGA and EUR tours as fallback.

### get_player_overview
Get detailed golfer overview with season stats, rankings, and recent results.
- `player_id` (str, required): ESPN athlete ID
- `tour` (str, optional): "pga", "lpga", or "eur". Defaults to "pga".

Returns season statistics (scoring average, earnings, wins, top-10s), world/tour rankings, and recent tournament results.

### get_scorecard
Get hole-by-hole scorecard for a golfer in the current/most recent tournament.
- `tour` (str, required): "pga", "lpga", or "eur"
- `player_id` (str, required): ESPN athlete ID

Returns `rounds[]` with hole-by-hole scores (strokes, score relative to par) for each completed round.

### get_news
Get golf news articles.
- `tour` (str, required): "pga", "lpga", or "eur"

Returns `articles[]` with headline, description, published date, and link.

## Common Player IDs

| Player | ID | Player | ID |
|--------|-----|--------|-----|
| Scottie Scheffler | 9478 | Nelly Korda | 9012 |
| Rory McIlroy | 3470 | Jin Young Ko | 9758 |
| Jon Rahm | 9780 | Lydia Ko | 7956 |
| Collin Morikawa | 10592 | Lilia Vu | 9401 |
| Xander Schauffele | 10404 | Nasa Hataoka | 10484 |
| Viktor Hovland | 10503 | Atthaya Thitikul | 10982 |
| Hideki Matsuyama | 5765 | Celine Boutier | 9133 |
| Ludvig Aberg | 4686088 | Lexi Thompson | 6843 |

**Tip:** Use `get_leaderboard` to find current player IDs from the active tournament.

## Reading Leaderboard Scores

Golf scores are relative to par. Example response:
```json
{
  "leaderboard": [
    {"position": 1, "name": "Scottie Scheffler", "country": "United States", "score": "-17",
     "rounds": [
       {"round": 1, "strokes": 63, "score": "-8"},
       {"round": 2, "strokes": 68, "score": "-3"},
       {"round": 3, "strokes": 67, "score": "-4"},
       {"round": 4, "strokes": 70, "score": "-1"}
     ]},
    {"position": 2, "name": "Rory McIlroy", "country": "Northern Ireland", "score": "-15", ...}
  ]
}
```
- **Negative score** = under par (good). "-17" means 17 strokes under par.
- **"E"** = even par.
- **Positive score** = over par. "+2" means 2 strokes over par.
- **Strokes** = actual stroke count for that round (par 72 course → 63 strokes = -9).

## Major Championships

| Tournament | Months | Course(s) |
|-----------|--------|-----------|
| The Masters | April | Augusta National |
| PGA Championship | May | Varies |
| U.S. Open | June | Varies |
| The Open Championship | July | Links courses (UK) |

Use `get_schedule` and search for these tournament names to find dates and event IDs.

## Examples

**User: "What's the PGA leaderboard right now?"**
```bash
sports-skills golf get_leaderboard --tour=pga
```

**User: "Show me the LPGA schedule for 2026"**
```bash
sports-skills golf get_schedule --tour=lpga --year=2026
```

**User: "Tell me about Scottie Scheffler"**
```bash
sports-skills golf get_player_info --player_id=9478
```

**User: "When is the Masters this year?"**
```bash
sports-skills golf get_schedule --tour=pga --year=2026
```
Then search the results for "Masters Tournament".

**User: "Show me Scottie Scheffler's scorecard"**
```bash
sports-skills golf get_scorecard --tour=pga --player_id=9478
```

**User: "How has Rory McIlroy been playing this season?"**
```bash
sports-skills golf get_player_overview --player_id=3470
```

**User: "Latest golf news"**
```bash
sports-skills golf get_news --tour=pga
```

## Error Handling

When a command fails, **do not surface raw errors to the user**. Instead:
1. If no active tournament, tell the user and suggest checking the schedule
2. If a player ID is wrong, suggest using `get_leaderboard` to find current player IDs
3. Only report failure with a clean message after exhausting alternatives

## Troubleshooting

- **`sports-skills` command not found**: Run `pip install sports-skills`
- **No active tournament**: Golf tournaments run Thursday–Sunday. Between events, `get_leaderboard` may show no active tournament. Use `get_schedule` to see upcoming events.
- **Limited round data**: Before a tournament starts, round scores will be empty. During the tournament, only completed rounds have scores.
- **Player not found**: Use `get_leaderboard` to find player IDs from the current field, or look up ESPN golf URLs.