Spatial events and tracking

Spatial event data describes where a recorded action occurred. Continuous tracking describes player and ball positions over time. A shot map, passing matrix, formation grid or distance-run total does not establish continuous tracking coverage.

Existing API responses retain their default shape. Request the additions explicitly, and check source, observation time, coordinate definitions and coverage before displaying them. A supported route does not guarantee a populated match or complete season.

Soccer shots

GET /v1/epl/games/{canonical_match_id}/extended?season_label=2025-2026&season_scope=split&include=spatial

The /matches/{id}/extended alias accepts the same selector. When enrichment exists, shot_spatial contains individual Understat shots with source IDs, nullable canonical player IDs, minute, raw and validated coordinates, body part, situation, preceding action, result and xG. The independently observed snapshot has its own observedAt and payloadHash. Missing shot_spatial means unavailable, not zero shots.

The optional revision identifies the projected snapshot, including resolved player identities; payloadHash identifies the raw source payload. These can change independently when a verified identity is added.

The five integrated competitions are EPL, LaLiga, Bundesliga, Serie A and Ligue 1. Both teams use Understat’s attacking frame: X and Y are fractions from 0 to 1, with the attacking goal at X=1. Physical pitch dimensions, stadium direction and the physical meaning of Y’s left/right orientation are not inferred. A UI must not plot these records as simultaneous player positions.

sourceListsPresent means both source arrays passed validation. It does not certify every shot of the match. coverage states that full-match completeness is unverified. Unknown values remain null, including flags whose source classification is unavailable. Own goals remain visible in this view; the legacy team-summary calculation is unchanged. A preceding cross or through ball is shot context, not a complete pass event with start/end coordinates.

MLB pitch coefficients

GET /v1/mlb/games/{canonical_game_id}/pbp/extended?season=2026&include=spatial&producer=mlb_pitch_physics

The independent mlb_pitch_physics producer returns complete, validated native pitch coefficients: position in feet, velocity in feet per second and acceleration in feet per second squared. Each event includes its source event ID and pitch/at-bat reference. Missing or invalid coefficients suppress that reconstruction; unavailable counts remain visible.

The model is p(t)=p0+v0*t+0.5*a*t^2, with time zero at the source fit reference near Y=50 feet. It is labelled derived_reconstruction. These coefficients do not establish observed tracking frames, pitch release position, flight duration, a plate endpoint, batted-ball landing coordinates or fielder movements. No flight animation is supplied by this addition.

The public Statcast CSV definition changes from front-of-plate through 2025 to middle-of-plate in 2026. That CSV convention is not silently applied to StatsAPI or existing fields. Omit include=spatial to exclude spatial producers from existing baseball responses, even if a producer name is supplied.

MLB’s existing live gamefeed task is configured for two-second polling; the five-second parity task reads the newest retained payload and prioritizes active/today games. Physics requires raw retention, both BASEBALL_PARITY_ENABLED=true and MLB_PITCH_PHYSICS_ENABLED=true, and the normal league/source gates. These intervals describe configured ingestion, not guaranteed source or widget latency.

NFL play context

GET /v1/nfl/games/{canonical_game_id}/pbp/extended?season=2025&limit=50

This separate endpoint exposes provider pass length/direction, air yards, yards after catch, run direction/gap, shotgun and no-huddle flags. Missing values remain null. It retains source play IDs and does not change existing plays, calculations or ordering. These scalar classifications are not player routes or XY tracking.

Use next_cursor for continuation. Cursors bind to the game and source snapshot; after a correction, a stale cursor returns 400 and pagination must restart without a cursor. Omit season for the latest stored season. Coverage is explicitly unverified, and source observations may be absent until the isolated enrichment runs.

Widget opt-in

Add spatial-events to the widget’s configured modules to enable recorded event locations and selected-event details. Ongoing games are labelled “In-game events”; completed games are labelled “Historical events.” Existing configurations keep their default presentation and response. Enriched widgets use separate cache/delivery namespaces.

Sport	Available presentation	Limits
Soccer	Individual shot locations and context when the optional snapshot exists	Provider attacking frame; no full passing or player tracking claim
Basketball	Existing shot context, raw chart coordinates and retained KBL team totals when a dedicated box-score side is missing	Dedicated totals take precedence; raw chart coordinates are not silently converted into physical court positions
Baseball	Existing pitch/play context; separate MLB coefficient API	No fabricated pitch flight or continuous fielder movement
Hockey	Existing event locations and shot context	Event locations are historical; goal-replay raw data remains unverified
American football	Existing drive/play context plus verified pass/run context joined by exact source play IDs	No inferred player routes or continuous tracking
Volleyball	Scoring/action/result context	No inferred attack zones, rotations or player trajectories

New enriched event details identify their source and evidence type. Existing canonical event metadata retains its original scope. Invalid coordinates and unsupported frames remain unavailable. Event positions never become a live-ball signal or a continuous motion path.

enrichmentSource, optional enrichmentObservedAt and enrichmentTiming describe added source context. Observation time is when the enrichment source was retrieved, not when the action occurred. Delayed or timing-unknown enrichment is labelled separately; its observation clock does not advance the canonical event clock. The opt-in cache/delivery suffix is :spatial-events:v2, separate from the default widget namespace.

For KBL, the opt-in view can use team totals already retained on the canonical game when that side has no measured dedicated box score. Team identities must match; measured zero is retained. Per-field ingestion provenance supplies timing when available, and unrelated game updates do not make the statistics appear newer. This adds no source request or polling schedule.

Understat’s played-match discovery and two-hour shot/replay tasks do not establish in-play shot availability. NFL’s nflverse PBP/context tasks are manual, and enabling their projection flag does not start live polling. A connected stream or the browser’s five-second fallback refresh does not establish source freshness. End-to-end live latency requires separate measurements of provider event time, retrieval, canonical commit, widget receipt and render; no production latency guarantee is supplied here.

Historical tracking research sample

Open the widget application with ?research=skillcorner to view a separate research page. It plays a bounded 100-frame, 10 Hz excerpt from a 2025 A-League match, with provider attribution and the bundled license. Detected positions and extrapolated positions are visually distinct. Playback uses the supplied frames and remains labelled historical.

This route does not connect to the live tracker, mint production identities, populate production records or advertise current league coverage. It demonstrates the interface that a future permitted tracking source could support.

Coverage boundaries

Complete current soccer passing streams, league-wide player trajectories, NHL goal replay payloads, reusable MLB Gameday 3D data, additional NBA Inside the Game exports and V-League scouting files remain conditional. Published reports and research datasets have different scope and reuse conditions. Missing data is not a zero, and differently defined classifications do not establish exact STATS/Opta equivalence.