API Reference

Live Tournament Data

pgatourpy.pga_current_tournament

pga_current_tournament(tour: str = 'R') -> str

Return this week's tournament ID for a tour.

Reads defaultTournaments from the PGA Tour web-config document (the same source the frontend uses). Raises PgaTourError if that tour has no default event.

Parameters:

Name	Type	Description	Default
tour	str	Tour code. Defaults to "R".	'R'

Returns:

Type	Description
str	Tournament ID (e.g. "R2026027").

pgatourpy.pga_leaderboard

pga_leaderboard(tournament_id: str) -> pd.DataFrame

Get tournament leaderboard.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (e.g., "R2026475").	required

Returns:

Type	Description
DataFrame	DataFrame with one row per player.

pgatourpy.pga_field

pga_field(tournament_id: str, *, include_withdrawn: bool = True) -> pd.DataFrame

Get the tournament field.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (e.g., "R2026027").	required
include_withdrawn	bool	Include withdrawn players.	True

Returns:

Type	Description
DataFrame	DataFrame with one row per player (field + alternates).

pgatourpy.pga_field_stats

pga_field_stats(tournament_id: str, field_stat_type: str = 'CURRENT_FORM') -> pd.DataFrame

Get field-level current-form or course-fit stats.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID.	required
field_stat_type	str	"CURRENT_FORM" or "COURSE_FIT".	'CURRENT_FORM'

Returns:

Type	Description
DataFrame	DataFrame with one row per player. Shape varies by type.

pgatourpy.pga_leaderboard_holes

pga_leaderboard_holes(tournament_id: str, round: int | None = None) -> pd.DataFrame

Get hole-by-hole scores for the whole field.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID.	required
round	int | None	Round number. Defaults to the API's current round.	None

Returns:

Type	Description
DataFrame	DataFrame with one row per player per hole.

pgatourpy.pga_current_leaders

pga_current_leaders(tournament_id: str) -> pd.DataFrame

Get current leaders snapshot (top 15).

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (e.g., "R2026475").	required

Returns:

Type	Description
DataFrame	DataFrame of current leaders.

pgatourpy.pga_tee_times

pga_tee_times(tournament_id: str) -> pd.DataFrame

Get tee times for a tournament.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (e.g., "R2026475").	required

Returns:

Type	Description
DataFrame	DataFrame with one row per player per round.

pgatourpy.pga_scorecard

pga_scorecard(tournament_id: str, player_id: str) -> pd.DataFrame

Get hole-by-hole scorecard.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (e.g., "R2026475").	required
player_id	str	Player ID (e.g., "39971").	required

Returns:

Type	Description
DataFrame	DataFrame with one row per hole per round.

pgatourpy.pga_shot_details

pga_shot_details(tournament_id: str, player_id: str, round: int, *, include_radar: bool = False) -> pd.DataFrame

Get shot-level tracking data with coordinates.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (e.g., "R2026475").	required
player_id	str	Player ID (e.g., "39971").	required
round	int	Round number (1-4).	required
include_radar	bool	Include radar data.	False

Returns:

Type	Description
DataFrame	DataFrame with one row per stroke.

pgatourpy.pga_odds

pga_odds(tournament_id: str) -> pd.DataFrame

Get odds to win for a tournament.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (e.g., "R2026475").	required

Returns:

Type	Description
DataFrame	DataFrame with player odds data.

pgatourpy.pga_odds_markets

pga_odds_markets(tournament_id: str) -> pd.DataFrame

Get the available betting-market catalog for a tournament.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID.	required

Returns:

Type	Description
DataFrame	DataFrame of market types (To Win, matchups, finishes, …).

pgatourpy.pga_player_odds

pga_player_odds(tournament_id: str, player_id: str) -> pd.DataFrame

Get FanDuel markets for one player in a tournament.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID.	required
player_id	str	Player ID.	required

Returns:

Type	Description
DataFrame	DataFrame of market lines (finish, matchups, props, …).

pgatourpy.pga_coverage

pga_coverage(tournament_id: str) -> pd.DataFrame

Get broadcast/streaming coverage info.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (e.g., "R2026475").	required

Returns:

Type	Description
DataFrame	DataFrame of coverage entries.

pgatourpy.pga_weather

pga_weather(tournament_id: str) -> pd.DataFrame

Get hourly and daily weather for a tournament.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID.	required

Returns:

Type	Description
DataFrame	DataFrame with a horizon column (hourly / daily).

pgatourpy.pga_course_stats

pga_course_stats(tournament_id: str) -> pd.DataFrame

Get per-hole course stats for a tournament.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID.	required

Returns:

Type	Description
DataFrame	DataFrame with one row per hole (or summary row) per round.

Statistics & Standings

pgatourpy.pga_stats

pga_stats(stat_id: str | list[str], year: int | list[int] | None = None, tour: str = 'R', *, event_query: str | None = None) -> pd.DataFrame

Get PGA Tour statistics.

Accepts a single stat ID or a list, and a single year or a list. The upstream StatDetails operation only accepts one (statId, year) pair per call, so multi-stat or multi-year requests loop client-side and concatenate. Each row carries stat_id and year columns so chunks remain distinguishable.

Parameters:

Name	Type	Description	Default
stat_id	str | list[str]	Stat ID (e.g., "02675" for SG: Total) or list of stat IDs.	required
year	int | list[int] | None	Season year or list of years. Defaults to current season.	None
tour	str	Tour code. Defaults to "R".	'R'
event_query	str | None	Optional event filter forwarded to the GraphQL StatDetailEventQuery variable (e.g. last-N-events filters on the PGA Tour stats page).	None

Returns:

Type	Description
DataFrame	DataFrame with stat_id and year columns followed by player
DataFrame	rankings. For a single-call result, metadata is also available via
DataFrame	df.attrs (stat_title, stat_description, tour_avg,
DataFrame	year, display_season).

pgatourpy.pga_fedex_cup

pga_fedex_cup(year: int | None = None, tour: str = 'R', *, event_query: str | None = None) -> pd.DataFrame

Get FedExCup standings.

Parameters:

Name	Type	Description	Default
year	int | None	Season year. Defaults to current year.	None
tour	str	Tour code. Defaults to "R".	'R'
event_query	str | None	Optional event filter forwarded to the GraphQL StatDetailEventQuery variable (e.g. last-N-events filters).	None

Returns:

Type	Description
DataFrame	DataFrame with player standings.

pgatourpy.pga_signature_standings

pga_signature_standings(tour: str = 'R') -> pd.DataFrame

Get Signature Event standings.

Parameters:

Name	Type	Description	Default
tour	str	Tour code. Defaults to "R".	'R'

Returns:

Type	Description
DataFrame	DataFrame of official (and interim, if present) standings.

pgatourpy.pga_priority_rankings

pga_priority_rankings(tour: str = 'R', year: int | None = None) -> pd.DataFrame

Get priority / exemption rankings.

Parameters:

Name	Type	Description	Default
tour	str	Tour code. Defaults to "R".	'R'
year	int | None	Season year. Defaults to the current season.	None

Returns:

Type	Description
DataFrame	DataFrame with one row per (category, player).

pgatourpy.pga_scorecard_comparison

pga_scorecard_comparison(tournament_id: str, player_ids: list[str], category: str = 'SCORING') -> pd.DataFrame

Get scorecard stat comparison between players.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (e.g., "R2026475").	required
player_ids	list[str]	List of player IDs to compare.	required
category	str	Comparison category (e.g., "SCORING", "DRIVING").	'SCORING'

Returns:

Type	Description
DataFrame	DataFrame of comparison category pills.

pgatourpy.pga_course_stats_overview

pga_course_stats_overview(tour: str = 'R', year: int | None = None) -> pd.DataFrame

Get the season course-stats hub.

Parameters:

Name	Type	Description	Default
tour	str	Tour code. Defaults to "R".	'R'
year	int | None	Season year. Defaults to the current season.	None

Returns:

Type	Description
DataFrame	Long DataFrame of category items and their detail labels.

Players & Tournaments

pgatourpy.pga_players

pga_players(tour: str = 'R') -> pd.DataFrame

Get PGA Tour player directory.

Parameters:

Name	Type	Description	Default
tour	str	Tour code. Defaults to "R".	'R'

Returns:

Type	Description
DataFrame	DataFrame with one row per player.

pgatourpy.pga_tournaments

pga_tournaments(ids: str | list[str]) -> pd.DataFrame

Get tournament metadata.

Parameters:

Name	Type	Description	Default
ids	str | list[str]	One or more tournament IDs (e.g., "R2026475").	required

Returns:

Type	Description
DataFrame	DataFrame with one row per tournament.

pgatourpy.pga_schedule

pga_schedule(year: int | None = None, tour: str = 'R') -> pd.DataFrame

Get season schedule.

Parameters:

Name	Type	Description	Default
year	int | None	Season year. Defaults to current year.	None
tour	str	Tour code. Defaults to "R".	'R'

Returns:

Type	Description
DataFrame	DataFrame with one row per tournament including dates, purse,
DataFrame	course, champion, and FedExCup points.

pgatourpy.pga_tournament_overview

pga_tournament_overview(tournament_id: str) -> dict

Get tournament overview tiles and champions.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID.	required

Returns:

Type	Description
dict	Dict with overview (DataFrame of tiles), defending_champion
dict	(dict or None), past_champions (DataFrame), plus URL
dict	scalars (tickets_url, tourcast_url, share_url,
dict	event_guide_url).

pgatourpy.pga_tournament_past_results

pga_tournament_past_results(tournament_id: str, year: int | None = None) -> pd.DataFrame

Get historical finishes for a tournament.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (perm id, e.g. "R2026027").	required
year	int | None	Season year. Defaults to the most recent year the API returns.	None

Returns:

Type	Description
DataFrame	DataFrame with one row per player.

Player Profiles

pgatourpy.pga_player_profile

pga_player_profile(player_id: str) -> dict

Get player profile overview.

Parameters:

Name	Type	Description	Default
player_id	str	Player ID (e.g., "52955" for Ludvig Aberg).	required

Returns:

Type	Description
dict	Dict with flat bio scalars (player_id, first_name,
dict	last_name, country, country_code, born, age,
dict	birthplace, college, turned_pro) plus two DataFrames:
dict	highlights: career-highlight tiles (title, value, subtitle)
dict	overview: overview-stats grid (section, subtitle, title, value)

pgatourpy.pga_player_career

pga_player_career(player_id: str) -> pd.DataFrame

Get player career data.

Returns career achievements including starts, cuts, wins, finish distribution, and earnings.

Parameters:

Name	Type	Description	Default
player_id	str	Player ID.	required

Returns:

Type	Description
DataFrame	DataFrame of career statistics.

pgatourpy.pga_player_results

pga_player_results(player_id: str, season: int | list[int] | None = None) -> pd.DataFrame

Get player tournament results.

The upstream REST endpoint returns one season per call. Pass season to request specific years, or omit it to loop every season listed in resultPills (the 0.2.0 "every season" contract). Each row carries a season column. Dynamic header labels are coerced to snake_case and deduplicated so column names never collide.

Parameters:

Name	Type	Description	Default
player_id	str	Player ID.	required
season	int | list[int] | None	Season year, list of years, or None for every season the API advertises for this player.	None

Returns:

Type	Description
DataFrame	DataFrame with one row per tournament across the requested
DataFrame	seasons.

pgatourpy.pga_player_stats

pga_player_stats(player_id: str) -> pd.DataFrame

Get player stats profile.

Returns a player's full statistical profile with ranks and values for 130+ stats in a single call.

Parameters:

Name	Type	Description	Default
player_id	str	Player ID.	required

Returns:

Type	Description
DataFrame	DataFrame with one row per stat.

pgatourpy.pga_player_bio

pga_player_bio(player_id: str) -> dict

Get player bio.

Returns biographical text, amateur highlights, and widget data.

Parameters:

Name	Type	Description	Default
player_id	str	Player ID.	required

Returns:

Type	Description
dict	Dict with text (list of paragraphs), amateur_highlights
dict	(list of strings), and widgets DataFrame.

pgatourpy.pga_player_tournament_status

pga_player_tournament_status(player_id: str) -> pd.DataFrame

Get player tournament status.

Returns the player's status in the current tournament (if playing). Returns an empty DataFrame when the API returns no status, or when every scalar field on the status object is null — callers can rely on len(df) > 0 to detect "player is in a tournament right now."

Parameters:

Name	Type	Description	Default
player_id	str	Player ID.	required

Returns:

Type	Description
DataFrame	DataFrame with one row, or empty if not currently in a tournament.

Content

pgatourpy.pga_news

pga_news(tour: str = 'R', franchises: list[str] | None = None, player_ids: list[str] | None = None, limit: int = 20, offset: int = 0) -> pd.DataFrame

Get news articles.

Parameters:

Name	Type	Description	Default
tour	str	Tour code. Defaults to "R".	'R'
franchises	list[str] | None	Filter by franchise categories.	None
player_ids	list[str] | None	Filter by player IDs.	None
limit	int	Max articles. Defaults to 20.	20
offset	int	Pagination offset.	0

Returns:

Type	Description
DataFrame	DataFrame with one row per article.

pgatourpy.pga_news_franchises

pga_news_franchises(tour: str = 'R') -> pd.DataFrame

Get news franchise/category list.

Parameters:

Name	Type	Description	Default
tour	str	Tour code. Defaults to "R".	'R'

Returns:

Type	Description
DataFrame	DataFrame with franchise and label columns.

pgatourpy.pga_videos

pga_videos(player_ids: list[str] | None = None, tournament_id: str | None = None, tour: str = 'R', season: str | None = None, franchises: list[str] | None = None, limit: int = 18, offset: int = 0) -> pd.DataFrame

Get player video highlights.

Parameters:

Name	Type	Description	Default
player_ids	list[str] | None	Player IDs to filter by.	None
tournament_id	str | None	Tournament ID (numeric part only, e.g., "475").	None
tour	str	Tour code. Defaults to "R".	'R'
season	str | None	Season year as string.	None
franchises	list[str] | None	Franchise filters.	None
limit	int	Max videos. Defaults to 18.	18
offset	int	Pagination offset.	0

Returns:

Type	Description
DataFrame	DataFrame of videos.

pgatourpy.pga_tourcast_videos

pga_tourcast_videos(tournament_id: str, player_id: str, round: int, *, hole: int | None = None, shot: int | None = None) -> pd.DataFrame

Get shot-by-shot video clips for a player round.

Parameters:

Name	Type	Description	Default
tournament_id	str	Tournament ID (e.g., "R2026475").	required
player_id	str	Player ID.	required
round	int	Round number.	required
hole	int | None	Specific hole number.	None
shot	int | None	Specific shot number.	None

Returns:

Type	Description
DataFrame	DataFrame of video clips.

pgatourpy.pga_content

pga_content(path: str) -> Any

Fetch a CMS content fragment from the GraphQL GenericContentCompressed op.

The shape of the returned object varies by path — it is whatever the CMS publishes for that URL. Returned as the raw parsed JSON, not a DataFrame, since the schema isn't stable across paths.

Parameters:

Name	Type	Description	Default
path	str	CMS path (e.g. a tournament landing-page slug).	required

Returns:

Type	Description
Any	Parsed JSON from the decompressed payload, or None if the
Any	operation returns no payload.

pgatourpy.pga_odds_interactivity

pga_odds_interactivity() -> Any

Fetch the odds-interactivity widget configuration (REST).

Returns the raw parsed JSON — schema is whatever the widget needs and isn't worth coercing into a DataFrame.

pgatourpy.pga_speed_rounds

pga_speed_rounds(tour: str = 'R') -> Any

Fetch the speed-rounds video index for a tour (REST).

Parameters:

Name	Type	Description	Default
tour	str	Tour code. Defaults to "R".	'R'

Returns:

Type	Description
Any	Raw parsed JSON from /content/watch/speedRounds/{tour}.

Errors

pgatourpy.PgaTourError

Bases: RuntimeError

Raised when a PGA Tour API call fails in a way the caller may want to handle.