espn_basketball_player_core: *Project an ESPN core-v2 athlete record into a 'player_core'...

In wehoop: Access Women's Basketball Play by Play Data

Project an ESPN core-v2 athlete record into a player_core row

Description

Turns one ESPN core-v2 ⁠/athletes/{id}⁠ payload into the single tidy row released as the player_core dataset.

This is a pure projection: it takes an already-fetched payload and never performs I/O. That is deliberate — the compile stages in wehoop-wnba-data / wehoop-wbb-data read the payload from the sibling -raw tree, and re-fetching here would both break the one-way raw -> data boundary and mean the R and Python pipelines read different bytes, so a value divergence could not be attributed to method.

Ids for college and current team are parsed out of the payload's ⁠$ref⁠ URLs (⁠/colleges/{id}⁠, ⁠/teams/{id}⁠). The ⁠$ref⁠ is never followed.

Usage

espn_basketball_player_core(payload, athlete_id)

Arguments

payload	list. One athlete's core-v2 ⁠/athletes/{athlete_id}⁠ payload, as returned by jsonlite::fromJSON(..., simplifyVector = FALSE). An empty or non-list value yields a zero-row tibble rather than an error.
athlete_id	numeric or character. The ESPN athlete id. Required and never inferred from the payload — callers pass the id from the file path, so a payload missing its own id still produces a joinable row.

Details

What the row means. current_team_id is the athlete's team today, not their team in any past season — the season a released row is filed under is participation (who appeared that year, taken from player_box), not the vintage of the bio. Height, weight and jersey are likewise a current snapshot: ESPN overwrites them in place, so era-correct bio is not obtainable from this endpoint.

Parity. This is a port of sportsdataverse.wbb.helper_wbb_player_core (sdv-py 0.0.75), which produces the released dataset today. The two are held to byte-parity by tests/testthat/test-espn_basketball_player_core.R against a golden fixture captured from that function; see tests/testthat/fixtures/player_core/README.md for provenance. Neither implementation is authoritative — a divergence is a review item.

Value

A one-row tibble carrying the full 35-column set (absent fields are NA), so callers see a stable schema regardless of payload completeness:

col_name	types
athlete_id	integer
guid	character
uid	character
slug	character
type	character
first_name	character
last_name	character
full_name	character
display_name	character
short_name	character
height	numeric
display_height	character
weight	numeric
display_weight	character
age	integer
date_of_birth	character
birth_city	character
birth_state	character
birth_country	character
jersey	character
position_id	integer
position_name	character
position_abbreviation	character
position_display_name	character
college_id	integer
current_team_id	integer
headshot_href	character
experience_years	integer
status_id	integer
status_name	character
status_type	character
draft_year	integer
draft_round	integer
draft_selection	integer
active	logical

Twin

hoopR::espn_basketball_player_core() is the identical function for the men's leagues. The core-v2 athlete resource is the same payload shape for nba/wnba/mbb/wbb, so the projection is league-agnostic – sdv-py implements it once and re-exports it per league. hoopR and wehoop are independently published and neither depends on the other, so here it is duplicated: a change to one must land in the other in the same session, verified.

Author(s)

Saiem Gilani

See Also

Other ESPN Basketball: espn_basketball

Examples

  # Split across lines to keep the Rd under the line-width limit; the
  # core-v2 $ref URLs are long enough to be truncated in the PDF manual.
  team_ref <- paste0(
    "http://sports.core.api.espn.com/v2/sports/basketball/",
    "leagues/wnba/seasons/2025/teams/22"
  )
  payload <- list(
    guid = "abc", fullName = "Jane Doe", jersey = "23",
    position = list(id = "5", abbreviation = "G"),
    team = list(`$ref` = team_ref)
  )
  espn_basketball_player_core(payload, athlete_id = 1966)

wehoop documentation built on Aug. 25, 2026, 1:06 a.m.