World Cup MVP Trophy Data

2025-07-17 08:27 UTC o3 Open in ChatGPT ↗

Below is a quick-fire tour of the kind of World-Cup-specific historical data Stats Perform (Opta) can drop on your lap. Think of it as a menu you can raid for creative inspiration when you’re turning raw numbers into a tangible MVP trophy.

1. ‟Every pass, tackle, save and goal since 1966”

Opta analysts have logged every men’s World-Cup match from England ’66 onwards, capturing 1 600-2 000 on-ball events per game (and well over 3 000 in modern editions).citeturn1view0turn5search1
Each event is time-stamped and geo-coded (X-Y pitch location) and comes with rich qualifiers: body-part, technique, pressure state, outcome, assist chain, etc. The official event‐type glossary runs to 300-plus definitions.citeturn5search0

Design angle: You could laser-engrave an XY heat-map of the MVP’s passes & shots onto the medal face, or etch the minute-markers of key events around the rim like a sundial.

2. Core match & player aggregates

Category	Typical fields you can request
Attacking	goals, assists, expected goals (xG), expected assists (xA), shots (on/off/blocked), touches in box
Passing & build-up	attempts & completed, pass % by zone, progressive/carry distance, key passes, crosses, switches
Defending	tackles, interceptions, recoveries, pressure regains, aerial duels, blocks, clearances
Goalkeeping	shots-faced split, post-shot xG, save difficulty model, claims, sweeps
Physical/tempo	distance covered, sprints, top speed (if tracking is enabled for that year)
Discipline & context	fouls, cards, VAR overturns, formation, minute-by-minute score state

These roll up from event feeds (F24) or match-stat feeds (F9/F8) and are available per match, per phase (group / knock-out), per tournament or across all World Cups.

3. Advanced & AI-derived metrics

Possession Value models (xThreat, xOV) – quantifies the danger added by every carry, pass or dribble.
Sequence & “Packing” metrics – how many opponents a pass or dribble bypassed.
Press-resistance and team “stability” ratings – who keeps the ball under pressure.
Live Win Probability & Momentum curves – swing charts that can be frozen at the exact minute the MVP changed the game.

All of these are part of Opta’s **“advanced metrics” layer highlighted in their World-Cup coverage packs.**citeturn0search1turn0search8

Design angle: Imagine a spiralling column whose twist angle equals a player’s total xThreat, with hash-marks showing the opponents bypassed.

4. Tracking & biomechanics (newer tournaments)

From 2022 onward, Stats Perform’s “Opta Vision” fuses optical tracking with the event feed:

3-D player and ball positions at 25 Hz
Instant acceleration, proximity, spacing grids, off-ball runs

That means you can pull signature sprint speed or “distance between back line & keeper” at the exact moment of a match-winning save.citeturn0search8

5. Contextual & narrative data

Man-of-the-Match votes, Golden Ball history, previous MVPs
Referee, stadium, attendance, weather, altitude
Editorial nuggets and ready-to-post graphics from the Opta Content Agency or PressBox Live feeds – handy if you want QR-codes on the plinth that open animated dashboards.

How this helps your trophy brief

Pick one hero metric per match (e.g., highest xG-over-performance) and let it dictate a physical dimension – height, twist, facet count.
Embed micro-details – coordinates of the winning goal engraved as lat/long on the base; sprint top-speed translated into the trophy’s angle of lean.
Leave space for live data – an NFC tag under the trophy could pull that match’s full Opta dashboard when scanned.

Next step? Let me know which data stories resonate most with the client (heat-maps, xG, top speed, etc.) and I can sketch concrete ways to translate them into shapes, textures or lighting inside your MVP trophy.

ok i received this json file from a stats company. Can you help me understand it?

“matchInfo”: { “id”: “71pif9hi2vwzp6q0xzilyxst0”, “coverageLevel”: “15”, “date”: “2021-09-11Z”, “time”: “18:30:00Z”, “localDate”: “2021-09-11”, “localTime”: “20:30:00”, “week”: “6”, “attendanceInfoId”: “2”, “attendanceInfo”: “Limited Audience”, “numberOfPeriods”: 2, “periodLength”: 45, “lastUpdated”: “2025-06-25T22:44:30Z”, “description”: “Hamburger SV vs Sandhausen”, “sport”: { “id”: “289u5typ3vp4ifwh5thalohmq”, “name”: “Soccer” }, “ruleset”: { “id”: “79plas4983031idr6vw83nuel”, “name”: “Men” }, “competition”: { “id”: “722fdbecxzcq9788l6jqclzlw”, “name”: “2. Bundesliga”, “knownName”: “German Bundesliga Zwei”, “competitionCode”: “2.B”, “competitionFormat”: “Domestic league”, “country”: { “id”: “36min0qztu8eydwvpv8t1is0m”, “name”: “Germany” } }, “tournamentCalendar”: { “id”: “93wcwtf25153hracvqva88aac”, “startDate”: “2021-07-23Z”, “endDate”: “2022-05-15Z”, “name”: “2021/2022” }, “stage”: { “id”: “9443wbz12vfz0f7ewmg8xhes4”, “formatId”: “e2q01r9o9jwiq1fls93d1sslx”, “startDate”: “2021-07-23Z”, “endDate”: “2022-05-15Z”, “name”: “Regular Season” }, “contestant”: [ { “id”: “75xi6hloabmnjn2kzgj1g8h1s”, “name”: “Hamburger SV”, “shortName”: “Hamburg”, “officialName”: “Hamburger SV”, “code”: “HSV”, “position”: “home”, “country”: { “id”: “36min0qztu8eydwvpv8t1is0m”, “name”: “Germany” } }, { “id”: “884uzyf1wosc7ykji6e18gifp”, “name”: “Sandhausen”, “shortName”: “Sandhausen”, “officialName”: “SV Sandhausen”, “code”: “SVS”, “position”: “away”, “country”: { “id”: “36min0qztu8eydwvpv8t1is0m”, “name”: “Germany” } } ], “venue”: { “id”: “8gaqzo8y471bfkkc3tq7ra7o”, “neutral”: “no”, “longName”: “Volksparkstadion”, “shortName”: “Volksparkstadion” } }, “liveData”: { “matchDetails”: { “periodId”: 14, “matchStatus”: “Played”, “winner”: “home”, “matchLengthMin”: 97, “matchLengthSec”: 41, “period”: [ { “id”: 1, “start”: “2021-09-11T18:30:06Z”, “end”: “2021-09-11T19:15:08Z”, “lengthMin”: 45, “lengthSec”: 2 }, { “id”: 2, “start”: “2021-09-11T19:34:13Z”, “end”: “2021-09-11T20:26:52Z”, “lengthMin”: 52, “lengthSec”: 39 } ], “scores”: { “ht”: { “home”: 0, “away”: 0 }, “ft”: { “home”: 2, “away”: 1 }, “total”: { “home”: 2, “away”: 1 } } }, “event”: [ { “id”: 2328542063, “eventId”: 1, “typeId”: 34, “periodId”: 16, “timeMin”: 0, “timeSec”: 0, “contestantId”: “75xi6hloabmnjn2kzgj1g8h1s”, “outcome”: 1, “x”: 0.0, “y”: 0.0, “timeStamp”: “2021-09-11T17:39:28.239Z”, “lastModified”: “2021-09-11T17:39:10Z”, “qualifier”: [ { “id”: 3087870323, “qualifierId”: 130, “value”: “4” }, { “id”: 3087870311, “qualifierId”: 30, “value”: “8b60vtt1stnmt2uoj0f4lh49h, ci4pwzieoc94uj3i1371bsatx, 46vr35g415omy60ahbiv40wk5, apdrig6xt1hxub1986s3uh1x, n82tdzb1liltoe33f5p6xbhm, do9g7p0jtcfngmvq1uzy2tqdx, 8metzwuemi3edqhsv2pnqqbx1, 2nrmndj0uq3f46c2cb1fbf85, e7if3ma2jblaurrokcxadk0k5, aksjicf4keobpav3tuujngell, enpnulwzdxetukh80iwyazkk5, 3xq9irm7o2mp3zdlw4qt5plka, etfmz143p0d2yowiiijd8g6sq, 7b9gqjq7z692znpoklj7c057u, 4tufo2e9tsw24l2cx7m5b6xh, 3mp7p8tytgkbwi8itxl5mfkrt, 1px9whllb1pnprmgq4fjw3qhh, bhshqnrzmdjbqhtr8rcy7tca2, 4o4sv7lm8h0qvwiv81enhjv1l, 9ed74dfr9aeuedaf63l0i7aei” }, { “id”: 3087870335, “qualifierId”: 194, “value”: “do9g7p0jtcfngmvq1uzy2tqdx” }, { “id”: 3087870315, “qualifierId”: 44, “value”: “1, 2, 2, 3, 2, 2, 3, 3, 4, 4, 4, 5, 5, 5, 5, 5, 5, 5, 5, 5” }, { “id”: 3087870339, “qualifierId”: 197, “value”: “4938” }, { “id”: 3087870319, “qualifierId”: 59, “value”: “1, 2, 21, 23, 34, 4, 6, 3, 9, 19, 10, 8, 11, 14, 16, 18, 28, 41, 44, 48” }, { “id”: 3087870329, “qualifierId”: 131, “value”: “1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 0, 0, 0, 0, 0, 0, 0, 0, 0” }, { “id”: 3087870343, “qualifierId”: 227, “value”: “0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0” } ] }, { “id”: 2328543167, “eventId”: 1, “typeId”: 34, “periodId”: 16, “timeMin”: 0, “timeSec”: 0, “contestantId”: “884uzyf1wosc7ykji6e18gifp”, “outcome”: 1, “x”: 0.0, “y”: 0.0, “timeStamp”: “2021-09-11T17:40:17.141Z”, “lastModified”: “2021-09-11T17:39:59Z”, “qualifier”: [ { “id”: 3087875847, “qualifierId”: 59, “value”: “1, 19, 36, 17, 15, 2, 30, 22, 9, 26, 27, 5, 7, 8, 13, 14, 18, 23, 25, 35” }, { “id”: 3087875857, “qualifierId”: 194, “value”: “47ye0gt6bw2ilvl9s0e0ogr11” }, { “id”: 3087875865, “qualifierId”: 227, “value”: “0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0” }, { “id”: 3087875851, “qualifierId”: 130, “value”: “5” }, { “id”: 3087875853, “qualifierId”: 131, “value”: “1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 0, 0, 0, 0, 0, 0, 0, 0, 0” }, { “id”: 3087875843, “qualifierId”: 44, “value”: “1, 2, 2, 3, 2, 2, 3, 3, 4, 3, 3, 5, 5, 5, 5, 5, 5, 5, 5, 5” }, { “id”: 3087875841, “qualifierId”: 30, “value”: “5ysw8ditixnietm3lejwmw4id, ehvnch6p70deczk99k156jglx, 8tqphrtr7fraqeunw67iwwq8l, 68u3vd1upyaz92c06d1ekpbyt, 4oaj1qrhwobtrso61687x9ck5, 47ye0gt6bw2ilvl9s0e0ogr11, dkf9v2y9a7ogw6k53crs6dc5x, 4wk62n7739xlysrxoky33mf2t, dvljd3jdouhags70b4rv7jl5h, 2np4n7d10f0jsgor0zbs5acwl, 8jildds7zfj7uk3iohmmkj3kl, 8sh1fdq95u43vc8cku5ckf6xh, 8asvg8sto06l27xjgbzyzqx1x, 5revw8iy1mhgi4jbb5nae2ind, 7adaw298hyb8lf2lqsc428vrp, 8l443indci9k4q1i3akstjmc5, c7nq7mou1gyrzl60ho7pmaok5, 6hh1y9t572yqk7d1zegi0hm5m, hpzxgnwobdttfgd04dykf26t, cipmd3k2nfv0ddic0l8go14gl” }, { “id”: 3087875861, “qualifierId”: 197, “value”: “8283” } ] }, { “id”: 2328589731, “eventId”: 2, “typeId”: 32, “periodId”: 1, “timeMin”: 0, “timeSec”: 0, “contestantId”: “75xi6hloabmnjn2kzgj1g8h1s”, “outcome”: 1, “x”: 0.0, “y”: 0.0, “timeStamp”: “2021-09-11T18:30:06.787Z”, “lastModified”: “2021-09-15T06:48:59Z”, “qualifier”: [ { “id”: 3088123721, “qualifierId”: 127, “value”: “Left to Right” } ] }, { “id”: 2328589745, “eventId”: 2, “typeId”: 32, “periodId”: 1, “timeMin”: 0, “timeSec”: 0, “contestantId”: “884uzyf1wosc7ykji6e18gifp”, “outcome”: 1, “x”: 0.0, “y”: 0.0, “timeStamp”: “2021-09-11T18:30:06.787Z”, “lastModified”: “2021-09-15T06:49:00Z”, “qualifier”: [ { “id”: 3088123765, “qualifierId”: 127, “value”: “Right to Left” } ] }, { “id”: 2328589789, “eventId”: 3, “typeId”: 1, “periodId”: 1, “timeMin”: 0, “timeSec”: 0, “contestantId”: “75xi6hloabmnjn2kzgj1g8h1s”, “playerId”: “aksjicf4keobpav3tuujngell”, “playerName”: “M. Wintzheimer”, “outcome”: 1, “x”: 50.0, “y”: 50.0, “timeStamp”: “2021-09-11T18:30:06.817Z”, “lastModified”: “2021-09-16T05:47:19Z”, “qualifier”: [ { “id”: 3098033315, “qualifierId”: 178 }, { “id”: 3088123979, “qualifierId”: 141, “value”: “51.0” }, { “id”: 3088123975, “qualifierId”: 56, “value”: “Back” }, { “id”: 3088123985, “qualifierId”: 279, “value”: “S” }, { “id”: 3088123983, “qualifierId”: 213, “value”: “3.1” }, { “id”: 3088123977, “qualifierId”: 140, “value”: “33.9” }, { “id”: 3088123981, “qualifierId”: 212, “value”: “16.9” } ] },

Below is a tour of what you’re looking at and some pointers on how to read—and eventually exploit—each part of the feed. I’ll keep the jargon to a minimum and flag the fields that usually matter most to designers, analysts, or developers.

1. Top-level structure

Key	What it holds
`matchInfo`	One-off metadata that never changes for this fixture (who, where, when, competition, venue, teams, etc.).
`liveData`	Everything that can change while the game is in progress or once Opta’s reviewers add corrections: the result, the running clock, and an `event` array that lists every on-ball action, sub, card, shot, line-up confirmation, etc.

Think of matchInfo as the label on a wine bottle and liveData as what’s sloshing around inside.

2. `matchInfo` dissected

Path	Meaning & typical use
`id`	Unique Opta fixture GUID—handy for joins across other Opta endpoints.
`coverageLevel`	15 = full granular event feed (all touches, qualifiers, tracking alignment).
`date` / `time` (UTC) + `localDate` / `localTime`	UTC and in-stadium kickoff stamps (always ISO-8601).
`description`	Convenient plain-English label: “Hamburger SV vs Sandhausen”.
`competition > name` / `knownName`	“2. Bundesliga” and its marketing alias “German Bundesliga Zwei”.
`tournamentCalendar` & `stage`	Spell out the season (“2021/2022”) and phase (“Regular Season”).
`contestant[]`	Two objects, one per team. Key fields: `id` (team GUID), `name`, `code` (three-letter TV ticker), `position` (“home”/“away”).
`venue`	Stadium metadata; `neutral=no` flags home-advantage matches.

Why it matters for you:
These fields let you label or group data when you build dashboards or metadata plaques for the trophy. The contestant IDs also link to Opta’s season-long team stats and squad lists.

3. `liveData.matchDetails`

Field	What it tells you
`matchStatus`	“Played” = finalised and QA-checked. (Live games cycle through “In Progress”, “Ended”, “Played”).
`winner`	“home”, “away” or “draw”.
`matchLengthMin/Sec`	Opta’s actual played time (97 min 41 sec here, reflecting added time).
`period[]`	Start/end timestamps for each half. Useful for syncing with tracking or broadcast archives.
`scores`	`ht`, `ft` and `total` objects—identical here because it’s a two-period match without extra-time.

4. `liveData.event[]` – the heartbeat of the feed

Each object is one discrete event. Key fields:

Field	Example	Meaning
`typeId`	34, 32, 1	The kind of event (Opta’s numeric taxonomy). e.g., 34 = Starting XI confirmation, 32 = Direction/side selection, 1 = Formation set-up. A goal would be 16, a pass 1 or 2 depending on feed spec, etc.
`periodId`	16, 1, 2	16 = Pre-match administrative period. 1 = 1st half, 2 = 2nd half.
`timeMin` / `timeSec`	Clock time within the period (so kickoff is 0:00).
`contestantId`	`"75xi…"`	Links back to the team that generated the event.
`playerId` / `playerName`	Present for player-centric actions. Absent for team-level events.
`x`, `y`	Normalised pitch coordinates (0–100, origin bottom-left from TV camera).
`outcome`	1 = successful/positive, 0 = unsuccessful (model varies by event type).
`qualifier[]`	Extra context—see next section.
`timeStamp` / `lastModified`	When the event was first logged and when it was last QA-edited.

How many events should I expect?

For a fully coded 90-minute match you’ll typically see 1 600–2 000 events—including every pass, duel, shot, card, set-piece, sub and a handful of housekeeping ones like these lineup messages.

5. `qualifier[]` – adding colour to each event

A qualifier is a (qualifierId, value) pair that refines the parent event. A pass, for instance, might carry qualifiers for body part, pass length, pressure, height, assist ID, etc.

Example here	Likely meaning*
`qualifierId 130 = "4"`	Starting formation (4-something).
`qualifierId 30`	Comma-separated list of player IDs in the starting XI.
`qualifierId 44`	Corresponding shirt numbers.
`qualifierId 59`	Player position codes (Opta’s 1 = GK, 2 = RB … 11 = CF, 21+ special roles).
`qualifierId 127 = "Left to Right"`	Attack direction chosen at coin toss.
`qualifierId 178`	Flags this event as captaincy or on-pitch status for the named player.

*Exact mappings live in Opta’s Qualifier Dictionary; ask your feed provider for the latest sheet.

6. Quick sanity-check on the sample

Kick-off: both orientation events (typeId 32) fire at the same millisecond, assigning directions.
Line-ups: two typeId 34 events—one per team—list the 20 outfielders + 2 GKs with formations.
First competitive touch: the typeId 1 event for Hamburg at (50, 50) is Opta’s internal way to log “ball in play”. More granular touches (passes, duels, shots) would follow further down the feed.

7. How to make this digestible for design work

Group by typeId to peel out just the bits you need—e.g., goals (16), shots (14/15), cards (4/5), substitutions (19).
Join playerId and contestantId to Opta’s reference tables to fetch human-readable names and positions.
Exploit coordinates: heat-maps, pass plots and shot charts can be auto-generated straight from the x-y pairs.
Leverage qualifiers for storytelling: shirt numbers (44) engraved around the trophy base, a captain’s armband icon if 178 is present, etc.

Need a starter code snippet?

If you’d like, I can spin up a quick Python/Pandas example that:

loads this JSON,
explodes the event list,
converts x/y to a scatter-plot of all shots or passes.

Just say the word and I’ll drop runnable code (or a ready-made CSV) into the chat.

Bottom line:
This feed gives you every fact you need to turn a match into data-driven artwork. Once you’re comfortable identifying the event types and qualifiers relevant to “Most Valuable Player”, we can map those directly onto physical trophy elements—height, materials, engravings, embedded NFC tags, you name it. Let me know which parts you want to zoom in on next!

How an event and a qualifier fit together

Every on-ball action is logged once in the event[] array.
- The action type is the numeric typeId (e.g. 34 = line-ups, 16 = goal, 1 = pass/kick-off, 4 = yellow-card). These values are fixed in Opta’s “event-type list”.citeturn7view0
Each event then carries a bundle of qualifier objects.
- A qualifier is a (qualifierId, value) pair that adds colour: body-part, assist ID, xG, shirt-number, formation, etc. For example, in your sample qualifierId 130 =4 means the team will line up in a 4-x-x shape; 30 holds the 20 player-GUIDs that make up the starting XI; 44 is the matching shirt numbers.citeturn9view0

Put simply:

event.typeId -> “what happened?”
qualifier[].qualifierId -> “exactly how / where / who?”

Where to find the master lists

What you need	Where it lives	Notes
Full event-type table & permitted qualifiers per event	Stats Perform Developer Portal → F24 Feed Specification (PDF)	Appendix 1 = event IDs; Appendix 2 = qualifier IDs. A public copy circulates under the title “Opta Playground – F24 documentation”.citeturn7view0
Quick narrative definitions	Stats Perform site – Opta Event Definitions page	Plain-English explanations of every event and most common qualifiers.citeturn19view0
CSV / JSON look-ups	Community GitHub repos (e.g. `football-scores/data/reference/opta-qualifiers.csv`)	Handy for building a local dictionary in code.citeturn0search0
Code libraries that ship the mapping	• `kloppy` • `floodlight`	Both parse F24 XML/JSON and expose `event_type_id → name` & `qualifier_id → name` dictionaries.citeturn9view0

Tip: the official PDFs are still the source of truth; open-source copies sometimes lag a version or two after Stats Perform change or add a qualifier.

Decoding a real example from your feed

# event block (abridged)
"typeId": 34          ← Starting-XI event
"qualifier": [
  { "qualifierId": 130, "value": "4" }      # base formation: 4---
  { "qualifierId": 30,  "value": "<20 player IDs>" }
  { "qualifierId": 44,  "value": "<20 shirt numbers>" }
  { "qualifierId": 59,  "value": "<20 position codes>" }
]

With the lookup tables loaded you could translate that to:

Event = LINE-UPS
Formation = 4-4-2 diamond
Players   = [GUID list → names via F7 squad feed]
Shirts    =  1  2  3  …
Positions =  GK RB CB …

The same logic works for any other action:

typeId 16 + qualifierId 52 = goal scored with the left foot.
typeId 14 + qualifierId 80 = shot blocked by a defender.
typeId 1 + qualifierId 56 = pass made with the player’s back to goal (a lay-off).

A 5-minute starter script

import pandas as pd, json, requests

# 1) build local dictionaries -----------------------------
evt_map = pd.read_csv("event_ids.csv").set_index("id")["name"].to_dict()
qual_map = pd.read_csv("qualifier_ids.csv").set_index("id")["name"].to_dict()

# 2) load the match JSON ----------------------------------
with open("match_71pif9hi.json") as f:
    data = json.load(f)
events = pd.json_normalize(data["liveData"]["event"])

# 3) explode qualifiers and decode ------------------------
events = events.explode("qualifier")
events["qual_id"] = events["qualifier"].apply(lambda q: q.get("qualifierId"))
events["qual_val"] = events["qualifier"].apply(lambda q: q.get("value"))
events["event_name"] = events["typeId"].map(evt_map)
events["qual_name"] = events["qual_id"].map(qual_map)

From there you can pivot, plot, or feed the decoded data straight into your trophy-design logic.

If you only remember three things

typeId ⇒ event category, qualifierId ⇒ extra detail.
Use the official F24 spec (plus appendices) as your canonical mapping.
Open-source look-ups and libraries (Kloppy, Floodlight) are quick shortcuts but keep them in sync with the PDF now and then.

Ping me whenever you hit a stray qualifierId and I’ll help you translate it!

Those numeric codes are not something analysts dream up ad-hoc—they’re baked into the data feed itself. Stats Perform (Opta) publish a canonical lookup table for every feed they ship, and third-party tools mirror those tables so developers don’t have to copy-paste PDFs.

Where the numbers live	What you’ll find there	Access route
Official F24 feed specification	Appendix 1 = Event Type IDs (1 = Pass/Kick-off, 4 = Yellow-card incident, 16 = Goal, 34 = Team line-ups, etc.). Appendix 2 = Qualifier IDs.	Login to the Stats Perform Developer Portal → Soccer → F24 Event Details. Public mirror PDFs circulate under names like “Opta Playground – F24 documentation” citeturn1view0
Opta Event Definitions web page	Plain-English description of each event/qualifier—handy when you need prose rather than the numeric code.	statsperform.com → Resources / Opta Event Definitions citeturn18view0
Open-source lookup files (CSV/JSON)	Community-maintained tables such as `34,Team set-up,Team line-up` `16,Goal,Shot ends in goal`	GitHub repos like tomh05/football-scores keep `opta-events.csv` & `opta-qualifiers.csv` in `data/reference/` citeturn16search0
Research papers & theses	Embedded XML snippets that show the ID in action—for example `type_id="34"` in a Real Madrid v Atlético sample feed citeturn21view0
Python libraries (Kloppy, Floodlight)	Dictionaries that map `type_id → “Line-up”` and `qualifier_id → “Body Part-Left Foot”` so you can decode on the fly.	See Kloppy’s StatsPerform loader docs citeturn9view0

How the mapping works in practice

<Event … type_id="16" …>
    <Q qualifier_id="52" value="LeftFoot"/>
</Event>

16 → Goal event (from the Event-Type table).
52 → Body-part: left foot (from the Qualifier table).

That two-step lookup is how you turn “type 16 + qualifier 52” into the human sentence “Goal scored with the left foot.”

Tips for working with the tables

Treat the PDFs as the “source of truth”. Open-source copies can lag a version or two behind when Opta add a new metric.
Load them once, join everywhere. Most practitioners drop the CSV into a small database table or a Python dict and join on type_id / qualifier_id whenever they flatten a match file.
Watch for feed-specific quirks. The same numeric code can mean slightly different things in cricket or rugby feeds; always grab the soccer-specific sheet.
Version-control your copy. Opta occasionally renames a qualifier (e.g., “Last Man Tackle” became “Last Player Tackle” in 2023). Keeping diffable CSVs lets you spot changes before they break code.

Bottom line:
Those IDs come straight from Stats Perform’s own documentation; everything else (GitHub lists, Kloppy, academic PDFs) is simply repackaging that master list so developers and analysts can reference it quickly without logging into the portal each time.

Below is a minimal but complete Python “recipe” that shows the standard workflow:

load the two mapping CSVs once (event_ids.csv, qualifier_ids.csv);
read an Opta (Stats Perform) match file in JSON format;
explode the event list and the nested qualifier list;
translate the numeric IDs into human-readable names;
keep whatever columns you care about (here I keep the basics plus two common qualifier fields).

import json
import pandas as pd
from pathlib import Path

# ------------------------------------------------------------------
# 1)  One-time setup: read the lookup tables into Python dicts
# ------------------------------------------------------------------
# • event_ids.csv        expected cols:  id,name                 (e.g. 16,Goal)
# • qualifier_ids.csv    expected cols:  id,name                 (e.g. 52,Body-part-Left Foot)
evt_map  = pd.read_csv("event_ids.csv").set_index("id")["name"].to_dict()
qual_map = pd.read_csv("qualifier_ids.csv").set_index("id")["name"].to_dict()

# ------------------------------------------------------------------
# 2)  Load the Opta JSON (full match or snippet) --------------------
# ------------------------------------------------------------------
match_path = Path("match_71pif9hi2vwzp6q0xzilyxst0.json")
with match_path.open(encoding="utf-8") as f:
    j = json.load(f)

events_raw = pd.json_normalize(j["liveData"]["event"])          # ≈2 000 rows for a full game

# ------------------------------------------------------------------
# 3)  Flatten the qualifier array for easier joins -----------------
# ------------------------------------------------------------------
events = (
    events_raw
      .explode("qualifier", ignore_index=True)                    # long form: one row per qualifier
)

# pull qualifierId & value out of the dict
events["qualifierId"] = events["qualifier"].apply(lambda d: d.get("qualifierId") if isinstance(d, dict) else None)
events["qualValue"]   = events["qualifier"].apply(lambda d: d.get("value")       if isinstance(d, dict) else None)

# ------------------------------------------------------------------
# 4)  Translate numeric IDs into text ------------------------------
# ------------------------------------------------------------------
events["eventName"]    = events["typeId"].map(evt_map)
events["qualifierName"] = events["qualifierId"].map(qual_map)

# ------------------------------------------------------------------
# 5)  OPTIONAL: keep only a handful of columns ---------------------
# ------------------------------------------------------------------
cols_we_like = [
    "eventId", "eventName", "periodId", "timeMin", "timeSec",
    "contestantId", "playerId", "playerName",
    "x", "y",
    "qualifierName", "qualValue"
]
decoded = events[cols_we_like]

# ------------------------------------------------------------------
# 6)  EXAMPLE: pull out just the goals and show useful context -----
# ------------------------------------------------------------------
goals = decoded[decoded["eventName"] == "Goal"]      # or use typeId == 16

print(goals.to_markdown(index=False))

What this script gives you

Step	Result
1 & 2	Two small dictionaries (`evt_map`, `qual_map`) you can reuse match after match; a Pandas table where each row is one Opta event.
3	“Explodes” the nested `qualifier` list so the data are properly tabular (one qualifier per row).
4	Adds human-readable columns (`eventName`, `qualifierName`).
6	Shows how trivial it is to filter for, say, goals or yellow cards once the names are attached.

Tweaks you might want

Pivot back to wide form if you’d rather have all qualifiers for a single event in one row.

wide = (decoded
        .pivot_table(index=["eventId", "eventName", "playerName"],
                     columns="qualifierName",
                     values="qualValue",
                     aggfunc="first")
        .reset_index())

Persist the decoded data to a feather/Parquet file so designers can load it in Illustrator or Figma without touching Python.
Join extra feeds (Opta F7 squad list, tracking data, etc.) on playerId or contestantId.

That’s it—drop in real CSV paths and the full match JSON and you’ll have a fully decoded table ready for whatever analysis or creative mapping you want to do next (heat-maps, trophy engravings, NFC dashboards, …). Let me know if you’d like a follow-up example that builds a shot map or computes player-level aggregates!

Sure—let’s read that line from left to right and unpack what each method call is doing.

evt_map = (
    pd.read_csv("opta-events.csv")   # 1️⃣
        .set_index("id")             # 2️⃣
        ["name"]                     # 3️⃣
        .to_dict()                   # 4️⃣
)

Step	Code	What happens	Resulting object
1️⃣	`pd.read_csv("opta-events.csv")`	Pandas opens `opta-events.csv` (a lookup table that might look like `id,name\n16,Goal\n34,Line-ups\n…`).	A DataFrame with two columns: `id` and `name`.
2️⃣	`.set_index("id")`	Moves the `id` column into the index so each row is now keyed by that numeric event-type ID.	DataFrame whose index is 16, 34, … and whose single remaining column is `name`.
3️⃣	`["name"]`	Selects just the `name` column (drops all others).	A Series whose index is still the event ID and whose values are the event names (“Goal”, “Line-ups”, …).
4️⃣	`.to_dict()`	Converts that Series into a plain Python dictionary.	`{16: "Goal", 34: "Line-ups", …}` assigned to `evt_map`.

Why do it this way?
You end up with an in-memory lookup (evt_map) that lets you translate numeric typeId values straight into human-readable labels in constant time:

>>> evt_map[16]
'Goal'
>>> evt_map.get(1, "Unknown")
'Pass / Kick-off'

That dictionary is then reused whenever you process an Opta match file—no costly joins or repeated CSV reads.

Here’s what happens, piece-by-piece:

events_raw = pd.json_normalize(j["liveData"]["event"])

Segment	What it does	Resulting object
`j`	A regular Python dictionary that you previously created by doing something like `j = json.load(f)`.	`dict`
`j["liveData"]["event"]`	Navigates that dictionary: 1) go into the `"liveData"` key, 2) pick the `"event"` list. That list contains one Python `dict` for every Opta event in the match (passes, shots, cards, line-ups, etc.).	`list[dict]`, length ≈1 600–2 000 for a full game
`pd.json_normalize( … )`	A Pandas helper that flattens a list of nested dictionaries into a tabular structure: * each item in the list → one row* * each key inside the dictionaries → one column* Nested keys are given dotted names (`qualifier.0.qualifierId`, etc.) unless you tell Pandas to do something else.	`DataFrame` with ~2 000 rows and dozens of columns
Assignment to `events_raw`	Stores that DataFrame so you can manipulate it further (e.g., explode the `qualifier` column, filter goals, plot locations).	`pd.DataFrame`

Why use `json_normalize`?

Speed: one call converts the whole JSON array into a DataFrame—no manual loops.
Column access: once it’s a DataFrame you can do events_raw["typeId"], boolean masks, group-bys, etc.
Foundation for further cleaning: complex columns (like the nested qualifier list) stay intact for now; you handle them in the next step with .explode().

In other words, that single line turns the raw Opta event feed—still in JSON form—into a spreadsheet-like table that’s much easier to query and join with the lookup dictionaries you built earlier.

Here are the two most common “quick-peek” patterns people use with a Pandas DataFrame after they’ve normalised the Opta JSON:

# OPTION 1 ─ look at the very first event (row 0)
print(events_raw.iloc[0])          # prints the row as a Series

# OPTION 2 ─ show the first few events, laid out in a table
print(events_raw.head(5).to_markdown(index=False))   # or just events_raw.head()

Why those two?

Method	What you see	When to use it
`iloc[0]` (or any row number)	A Series, i.e., a one-dimensional view of that event with column names on the left and the values on the right.	Great when you want to inspect every field and qualifier for a single event without line-wrapping.
`head(n)`	A miniature DataFrame (default 5 rows) that keeps the table structure.	Handy for getting a feel for column names, data types, and whether `json_normalize` did the flattening you expected.

Picking a specific event by ID instead of by row number

If you know the Opta eventId you want (say 2328589789), filter first:

event_id = 2328589789
event = events_raw.query("eventId == @event_id").iloc[0]
print(event)

query("eventId == @event_id") returns a one-row DataFrame.
.iloc[0] turns that one row into a Series, ready to print.

Pretty printing (optional)

If the normal console output feels cramped, flip the row so each key/value sits on its own line:

print(event.to_frame().T)   # shows the event as a one-row DataFrame

or—in Jupyter/VS Code—

event.to_frame().style

which gives you a nicely formatted HTML table in the notebook.

That’s all there is to it: choose a row (by position with iloc, by condition with query/loc), then print or display. Let me know if you’d like to see the same for qualifiers, goals only, or even a quick shot map!

it looks like there is a repetition of the same events over and over

eventId	eventName	periodId	timeMin	timeSec	contestantId	playerId	playerName	x	y	qualifierName	qualValue
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	Box-centre
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	2021-09-11 21:02:52.140
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	Goal mouth y co-ordinate	52.6
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	49.8
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	496
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	enpnulwzdxetukh80iwyazkk5
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	Low left
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	99.7
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	Big Chance
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	Standing Goalkeeper
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	53.1
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	Zone	Center
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	73:38.708
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	Right footed
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	161
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	Goal mouth z co-ordinate	0.6
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	PENALTY_WON
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	Penalty
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	112975
813	Goal	2	73	39	75xi6hloabmnjn2kzgj1g8h1s	8metzwuemi3edqhsv2pnqqbx1	D. Kinsombi	88.5	50	nan	0.2
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	Intentional assist
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	nan	2021-09-11 21:16:10.002
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	Standing Goalkeeper
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	Assisted
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	nan	52.5
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	Right footed
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	nan	97.7
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	Goal mouth z co-ordinate	26.6
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	Zone	Center
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	nan	50.9
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	nan	97.8
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	High centre
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	nan	86:56.570
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	Related event ID	567
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	Box-centre
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	Regular play
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	Goal mouth y co-ordinate	48.5
568	Goal	2	86	57	884uzyf1wosc7ykji6e18gifp	2np4n7d10f0jsgor0zbs5acwl	J. Bachmann	92.5	55.7	nan
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	nan	95:21.809
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	From corner
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Right footed
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	nan	51.8
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Box-deep left
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Keeper Touched
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	nan	48.9
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Related event ID	1014
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Goal mouth z co-ordinate	1.9
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Low centre
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Zone	Center
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Intentional assist
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	nan	0.7
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	nan	2021-09-11 21:24:35.241
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Standing Goalkeeper
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	nan	99.4
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Assisted
1015	Goal	2	95	22	75xi6hloabmnjn2kzgj1g8h1s	2nrmndj0uq3f46c2cb1fbf85	M. Heyer	95.9	66	Goal mouth y co-ordinate	48.7

That “déjà-vu” effect is coming from the .explode("qualifier") step we used earlier:

┌─ event (dict) ─┐
│  qualifiers[]  │   ← one list **inside** the event
└────────────────┘
        │             explode()
        ▼
┌ event 1 + qualifier A ┐   ← row 1
│ event 1 + qualifier B │   ← row 2
│ event 1 + qualifier C │   ← row 3
└───────────────────────┘

So:

eventId stays the same (it really is a single shot/goal/pass).
qualifierName / qualValue change—each qualifier becomes its own row.
Everything else (period, time, x-y, player, …) is duplicated because we copied the parent event’s data down each time.

That “long” layout is perfect when you want to filter on specific qualifiers (e.g., all right-footed shots), but if you just want one row per event, pivot it back to wide form or deduplicate.

Option A – collapse back to one row per event (wide form)

wide = (
    decoded                         # <- the exploded DataFrame
      .pivot_table(
          index=["eventId", "eventName", "periodId", "timeMin", "timeSec",
                 "contestantId", "playerId", "playerName", "x", "y"],
          columns="qualifierName",
          values="qualValue",
          aggfunc="first"           # keep the first value if a qualifier appears twice
      )
      .reset_index()
)

print(wide.head())

Result: one row per eventId, every qualifier becomes its own column ("Right footed", "Big Chance", "xG", …).

Option B – just strip the duplicates

If you only needed core event fields and don’t care about qualifiers right now:

events_only = (
    events_raw                      # <- before explode
      .drop(columns=["qualifier"])  # dump the big list
      .drop_duplicates("eventId")   # remove repeats (still safe: one JSON object per eventId)
)

print(events_only.head())

Quick sanity check

print(len(events_raw))     # ≈ (#events) × (avg #qualifiers)
print(events_only.shape[0])
print(wide.shape[0])

events_only and wide should both equal the true number of events (e.g., ~1 800 for a typical match), while events_raw is much larger because of the exploded qualifiers.

Take-away: the “repetition” is just the tidy-data trick we used; your events are not duplicated by Opta. Pick the shape—long (one qualifier per row) or wide (one event per row)—that best fits the question you want to answer.

Recap: “Event” vs “Qualifier”

Layer	What it is	Key field in the feed	Example
Event	The verb – the base thing that happened.	`typeId` (and therefore `eventName` once you map it).	`16 → Goal`, `1 → Pass`, `4 → Yellow card`, `34 → Line-ups` citeturn0search0
Qualifier(s)	The adjectives that describe that event in as much detail as Opta can capture.	`qualifierId` + `value` (many per event).	`52 → Left foot`, `152 → Big Chance`, `223 → xG = 0.17`, `245 → Goal mouth Y = 48.5`, `210 → Penalty`, `140 → Shot speed = 33.9 km/h` citeturn0search1

Why so many?
A single on-ball action can have lots of attributes – technique, body part, outcome, exact location, assist chain, pressure state, match context, model outputs (xG/xThreat), refereeing context (VAR), etc.
Opta keeps the event taxonomy tight (≈ 60 football event types) and hangs every extra detail off that base event as modular qualifiers instead of inventing hundreds of bespoke “event-plus-context” types.

The categories most qualifiers fall into

Category	Typical football examples	What it lets you analyse / design
Spatial	Box-centre, Goal-mouth y/z co-ordinates, Pass end-x/y	Draw heat-maps, shot charts, “goalmouth” engravings.
Technical	Right-footed, Volley, Chip pass, Low centre finish	Label technique on highlight reels; etch the body part or finish type on a trophy facet.
Tactical/contextual	Big Chance, Fast break, From corner, Penalty	Flag high-leverage moments; colour-code timeline LEDs.
Outcome/result	Assist, Own Goal, Shot on target, Interception retained	Summaries, score attribution, player scorecards.
Advanced model outputs	xG, xA, Shot speed, Sequence number	Convert numbers into trophy dimensions or weightings.
Linking/meta	Related event ID (ties a goal to the preceding shot), Player IDs & shirt numbers	Stitch multiple feeds together; show assist-goal chains on an NFC dashboard.

A Goal in your sample has ~20 qualifiers because Opta attaches all of these layers: placement (“Low left”), goalkeeper posture (“Standing Goalkeeper”), body part (“Right footed”), whether it was a Big Chance, modelled probabilities, the clock time stamp, x/y/z goal-mouth co-ords, related preceding events, etc. The explosion step in Pandas turned every one of those qualifier pairs into its own row, which is why it looked like 20 identical goals.

How the feed stores them

{
  "typeId": 16,            // Goal
  "playerId": "…",
  "x": 88.5, "y": 50.0,
  "qualifier": [
      { "qualifierId": 52,  "value": "Right Foot" },
      { "qualifierId": 152, "value": "" },            // Big Chance (flag only)
      { "qualifierId": 140, "value": "33.9" },        // Shot speed km/h
      { "qualifierId": 245, "value": "48.5" },        // Goal-mouth y
      … many more …
  ]
}

One JSON object, many qualifier mini-objects inside.

Where the ID → name mapping comes from

Stats Perform Developer Portal – F24 spec PDF (Appendix 1 & 2). This is the “source of truth”. citeturn0search0
Public “Opta Event Definitions” page if you just need prose explanations. citeturn0search1
Open-source CSV / JSON mirrors (GitHub projects, Kloppy, Floodlight) – handy for code, but update them when Opta revises the spec. citeturn0search6

Load those tables once, keep them in a dict (qual_map), and every qualifierId is instantly readable.

Quick mental model to keep you oriented

event (verb)   : “Goal”
+ qualifiers   : “Right foot” + “Low left” + “Big Chance” + “xG 0.17” + …
= full sentence: “Right-footed goal, low left, scored from a big chance (xG 0.17)…”

Whenever you see repeated rows in the exploded DataFrame, remember they’re just that one sentence broken into word-by-word metadata. Collapse back to one row per event when you need a clean event list; keep the long form when you want to filter or count specific adjectives.

Let me know if you’d like code to pivot those qualifiers into columns automatically or guidance on which qualifier buckets are most useful for MVP-trophy storytelling!

Exactly — if you skip the .explode("qualifier") step you keep a one-row-per-event table and the entire list of qualifiers sits in a single cell.
You can then dip into that list only when you need extra detail.

What the non-exploded DataFrame looks like

events_raw = pd.json_normalize(j["liveData"]["event"])
print(events_raw.iloc[0][["eventId", "typeId", "qualifier"]])

eventId                                     813
typeId                                       16          # 16 = Goal
qualifier   [{'qualifierId': 52, 'value': 'Right foote...
Name: 0, dtype: object

One row per event (eventId is unique).
Column qualifier contains a list of dicts.

Peeking inside the qualifiers on demand

# pick a single event – here the goal with eventId 813
row = events_raw.query("eventId == 813").iloc[0]

# row["qualifier"] is just a Python list; inspect it or turn it into a mini-DF
qual_df = pd.DataFrame(row["qualifier"])
print(qual_df.head())

qualifierId	value
52	Right footed
152	Big Chance
245	48.5
246	52.6
210	Penalty

Do this only for the events you care about (e.g., goals, shots, passes by the MVP).
The rest of your DataFrame stays tidy and small.

Later, when you do need every qualifier as its own column

You can still pivot just those rows:

wide = (
    events_raw
      .loc[events_raw["typeId"] == 16]        # goals only, for instance
      .explode("qualifier")
      .assign(
          qual_id=lambda d: d["qualifier"].str["qualifierId"],
          qual_val=lambda d: d["qualifier"].str["value"]
      )
      .pivot_table(index="eventId",
                   columns="qual_id",
                   values="qual_val",
                   aggfunc="first")
      .reset_index()
)

That produces one goal per row with qualifier IDs (or mapped names) as columns.

When to keep it nested vs. explode early

Keep nested (no explode)	Explode immediately
You mostly work event-level (count passes, plot shot locations, compute xG) and only drill into qualifiers occasionally.	You need to filter on qualifiers straight away (all left-footed shots, aerial duels, passes under pressure) or want a fully wide analytics table.
Lighter in memory; fewer duplicates in printouts.	Simpler boolean filters (`qualifierName == "Right footed"`).

So yes—leave them nested to keep the event list clean, and “explode” only when a deeper qualifier attribute becomes relevant.

Yes — those two .apply() lines only make sense after you’ve exploded the qualifier list so that each row contains a single little dictionary.
If you keep the feed in its original one-row-per-event shape, the qualifier column is a list of dictionaries, so you need to walk through that list and translate the IDs in-place.

Below are two common patterns.

1 ️⃣ Keep the structure, just add a “name” key inside every qualifier dict

# step 0 – build the lookup once
qual_map = (
    pd.read_csv("qualifier_ids.csv")        # cols: id,name
      .set_index("id")["name"]
      .to_dict()
)

def add_names(q_list):
    """
    q_list is a list[dict] like
    [{'qualifierId': 52, 'value': 'Right footed'}, …]
    """
    if not isinstance(q_list, list):
        return q_list                      # guard against NaNs
    for q in q_list:
        q["qualifierName"] = qual_map.get(q["qualifierId"], f"Q{q['qualifierId']}")
    return q_list

events_raw["qualifier"] = events_raw["qualifier"].apply(add_names)

Result: the column still holds a list, but each dict now looks like

{'qualifierId': 52, 'qualifierName': 'Right footed', 'value': 'Right footed'}

When you drill into one event:

row = events_raw.query("eventId == 813").iloc[0]
for q in row["qualifier"]:
    print(q["qualifierName"], "→", q["value"])

2 ️⃣ Collapse the whole list into one dictionary of name → value (handy for quick look-ups)

def to_named_dict(q_list):
    if not isinstance(q_list, list):
        return {}
    return {
        qual_map.get(q["qualifierId"], f"Q{q['qualifierId']}"): q.get("value", "")
        for q in q_list
    }

events_raw["qualifiersDecoded"] = events_raw["qualifier"].apply(to_named_dict)

Now each cell in qualifiersDecoded is something like

{
  'Right footed': '',
  'Low left': '',
  'Big Chance': '',
  'xG': '0.17',
  'Goal mouth y co-ordinate': '48.5',
  …
}

and you can query it on the fly:

row = events_raw.loc[events_raw.eventId == 813, "qualifiersDecoded"].iloc[0]
print(row.get("xG"))            # -> '0.17'
print(row.get("Big Chance"))    # -> ''   (flag type has empty value)

Why this is nice

One clean event table – no duplicated rows.
Qualifiers ready on demand – you don’t pay the memory price until you open the cell.
Flexible – you can still explode later if you need to filter by qualifier.

What changed compared with your previous code

Before (exploded)	After (nested)
`.explode("qualifier")` first, then pull out `'qualifierId'` and `'value'`.	Skip `.explode`. The whole qualifier list lives in one cell.
Two `.apply(lambda d: …)` lines to grab single keys from a single dict.	One `.apply()` that iterates over the list and maps every `qualifierId` via `qual_map`.

Drop this snippet into your script and you’ll have readable qualifier names without duplicating events. Ping me if you want a quick demo of turning those named-dict columns into wide columns later (e.g., xG, Body Part, Shot Speed as separate fields).

Here’s a quick, three-liner pattern you can drop straight into your notebook to list every distinct event type that appears in the match, translated from typeId to its human-readable name:

# assumes you already have:
#   • events_raw  ← your one-row-per-event DataFrame (no qualifier explode)
#   • evt_map     ← the {typeId: "Event name"} dictionary built from event_ids.csv

event_names = (
    events_raw["typeId"]         # grab the numeric codes
      .map(evt_map)              # translate to names
      .dropna()                  # in case a rare code is missing from evt_map
      .unique()                  # keep each name once
      .tolist()                  # turn the numpy array into a plain Python list
)

print(event_names)

Typical output (for a fully coded Opta match) might be:

['Line-ups',
 'Direction Indicator',
 'Formation Set-up',
 'Pass / Kick-off',
 'Duel',
 'Shot',
 'Save',
 'Goal',
 'Substitution',
 'Yellow Card',
 'Corner Taken',
 'Clearance',
 ... ]

Notes

map(evt_map) is the look-up step; anything unmapped becomes NaN, which dropna() removes.
unique() collapses duplicates so each event type appears only once.
If you’d like them sorted alphabetically (or by first appearance), just wrap sorted() around the list: sorted(event_names).

That’s all you need to print (or log, or export) the catalogue of event types for the match without touching the qualifiers.

Below’s a simple pattern you can paste into the same script to print every single event in human-readable form, without flattening the qualifiers.

import pandas as pd

# --------------------------------------------
# 0)  what we already have from earlier
# --------------------------------------------
# j            = json.load(...)      ← full Opta JSON
# events_raw   = pd.json_normalize(j["liveData"]["event"])
# evt_map      = {typeId: "Event name"}        (built from event_ids.csv)

# --------------------------------------------
# 1) add the event name column
# --------------------------------------------
events_raw["eventName"] = events_raw["typeId"].map(evt_map)

# --------------------------------------------
# 2) pick the columns you want to see
#    (add/remove fields as you like)
# --------------------------------------------
print_cols = [
    "eventId", "eventName",
    "periodId", "timeMin", "timeSec",
    "contestantId", "playerId", "playerName",
    "x", "y"
]
events_view = events_raw[print_cols]

# --------------------------------------------
# 3) optional: sort them in the exact order they
#    happened on the pitch
# --------------------------------------------
events_view = events_view.sort_values(
    ["periodId", "timeMin", "timeSec", "eventId"]
)

# --------------------------------------------
# 4) print *every* row (no truncation)
# --------------------------------------------
pd.set_option("display.max_rows", None)   # show all rows in console
print(events_view.to_markdown(index=False))

What this does

Adds eventName so the numeric typeId is translated.
Keeps one row per event (qualifiers stay tucked inside that nested list).
Sorts by half → clock → eventId so the print-out follows real match flow.
Uses to_markdown() (nice, readable table) but you can swap for to_string() or export to CSV if you prefer.

If the table is too wide for your console, drop columns or export:

events_view.to_csv("match_events.csv", index=False)

Now you have a tidy CSV with every event ready for Excel, R, Tableau—or just open it in a text editor.

Let me know if you want to print specific qualifier info for each event (e.g., show the xG value right next to goals) or if you’d like a quick chart of the timeline instead!

Below is a compact pattern that does exactly what you asked:

keeps every row (one per event, qualifiers still nested)
drops the numeric eventId column
replaces the numeric typeId with a readable eventName column

import pandas as pd, json, pathlib

# ------------------------------------------------------------------
# 0) one-off look-up table for event types
# ------------------------------------------------------------------
evt_map = (                        # id → English name
    pd.read_csv("event_ids.csv")   #  two columns: id,name
      .set_index("id")["name"]
      .to_dict()
)

# ------------------------------------------------------------------
# 1) load the match file and keep it one-row-per-event
# ------------------------------------------------------------------
with open("match_71pif9hi.json", encoding="utf-8") as f:
    j = json.load(f)

events = pd.json_normalize(j["liveData"]["event"])

# ------------------------------------------------------------------
# 2) translate typeId → eventName, then drop the original IDs
# ------------------------------------------------------------------
events["eventName"] = events["typeId"].map(evt_map).fillna(events["typeId"])
events = events.drop(columns=["typeId", "eventId"])

# optional: order columns so eventName comes first
cols = ["eventName"] + [c for c in events.columns if c != "eventName"]
events = events[cols]

# ------------------------------------------------------------------
# 3) print the whole thing (no row truncation)
# ------------------------------------------------------------------
pd.set_option("display.max_rows", None)
print(events.to_markdown(index=False))

What each block does

Block	Purpose
0	Loads the CSV look-up once, giving you a dictionary like `{16: "Goal", 4: "Yellow Card", …}`.
1	Reads the Opta JSON but does not explode the qualifier list, so you keep one tidy row per event.
2	Creates `eventName` by mapping `typeId`; then drops `typeId` and `eventId` so no numeric IDs remain.
3	Forces Pandas to show every row in the console (handy for quick inspection). Replace `to_markdown()` with `to_csv("all_events.csv", index=False)` if you’d rather open it in Excel.

Run that and you’ll see a full table whose first column is something like

| eventName | periodId | timeMin | timeSec | contestantId | … | qualifier |
|-----------|----------|---------|---------|--------------|---|-----------|
| Line-ups  | 16       | 0       | 0       | …            |   | […]       |
| Goal      | 2        | 73      | 39      | …            |   | […]       |
| Substitution | …     | …       | …       | …            |   | […]       |

No eventId, no typeId—just readable event names plus the rest of your data, ready for analysis or export.

You just need to rebuild the column order and re-index the DataFrame:

# `events` is your DataFrame that already contains `eventName`
cols = ["eventName"] + [c for c in events.columns if c != "eventName"]
events = events[cols]          # re-order in place (or assign to a new df)

# sanity-check
print(events.head())

What’s happening

["eventName"] – starts the list with the column you want first.
[c for c in events.columns if c != "eventName"] – gathers every other column in their current order.
events[cols] – re-indexes the DataFrame to that new column sequence.

That’s all—eventName is now the left-most column, and nothing else changes.

Yep—one‐liner fast:

print(events["eventName"].unique().tolist())

events["eventName"] – grabs the column.
.unique() – returns each distinct value once (as a NumPy array).
.tolist() – turns that array into a plain Python list for a clean print.

If you’d like them alphabetically:

print(sorted(events["eventName"].unique()))

That’s it—no loops, no extra imports.

Exactly — those numeric leftovers are the typeId values that weren’t found in your lookup dictionary. When you did

events["eventName"] = events["typeId"].map(evt_map).fillna(events["typeId"])

map(evt_map) inserts the English name if it exists in evt_map.
Unrecognised IDs turn into NaN, and .fillna(events["typeId"]) drops the raw number back in.

Why IDs might be missing

Lookup file out-of-date – Stats Perform add new events every couple of seasons (e.g., “VAR-overturn”).
Feed variant – women’s, youth, or tracking-enhanced feeds sometimes have extra types.
Simple oversight – the open-source CSV you grabbed never included them.

Quick way to see which IDs are unmapped

unknown_ids = (
    events["typeId"]
      .loc[~events["typeId"].isin(evt_map.keys())]   # not in the dict
      .unique()
)

print("Unmapped event typeIds:", unknown_ids.tolist())

Typical output:

Unmapped event typeIds: [90, 94]

Updating your map on the fly (temporary fix)

evt_map.update({
    90: "VAR review",
    94: "Goal disallowed",
})
events["eventName"] = events["typeId"].map(evt_map).fillna(events["typeId"])

Permanent fix

Pull the latest “F24 Event & Qualifier IDs” PDF from the Stats Perform developer portal.
Append the new rows to your event_ids.csv, then reload:

evt_map = (
    pd.read_csv("event_ids.csv")
      .set_index("id")["name"]
      .to_dict()
)

Re-run your mapping step; all IDs should resolve.

Bonus: flag missing IDs early

If you want your script to warn you whenever a new type appears:

missing = set(events["typeId"]) - set(evt_map.keys())
if missing:
    print("⚠️  Unknown event types:", missing)

That way you notice the moment Opta add something new and can patch your CSV before downstream code breaks.

Let me know if you need help tracking down the official spec or want a similar check for qualifierIds!

Below is a minimal pattern you can drop straight into the same script you’ve been using.
It assumes you already have the tidy events DataFrame that:

has eventName (readable) instead of typeId,
has dropped the numeric eventId,
still keeps the nested qualifier list exactly as it came from the JSON.

# 1)  Pick a descriptive file name
out_path = "hamburg_sandhausen_2021-09-11_events.csv"

# 2)  Dump the DataFrame
events.to_csv(out_path,                # ← where to write
              index=False,             # ← don't add a numeric row index
              encoding="utf-8")        # ← keep any accented names safe

print(f"✅  Export complete → {out_path}")

A couple of optional tweaks

Need	Quick change
Qualifiers as JSON strings rather than Python-repr lists (handy for re-loading later).	```python
import json
events_copy = events.copy()
events_copy[“qualifier”] = events_copy[“qualifier”].apply(json.dumps)
events_copy.to_csv(out_path, index=False, encoding=“utf-8”)

| **Flat CSV without the qualifiers** (just core event fields). | ```python
events.drop(columns=["qualifier"]).to_csv(out_path, index=False)
``` |

That’s it—run the snippet and you’ll find a fully readable CSV (one row per event, first column `eventName`) in the working directory, ready for Excel, Tableau, or sharing with your trophy-design teammates.

Opta / Stats Perform pitch‑coordinate system in a nutshell

Axis	Range	Zero‑point	100‑point	What it represents	Typical real‑world metre value*
x	0 – 100	Left‑hand touch‑line (as you see it on the main TV camera)	Right‑hand touch‑line	Length of the pitch	0 m → 105 m
y	0 – 100	Near‑side touch‑line (bottom of the TV screen)	Far‑side touch‑line (top)	Width of the pitch	0 m → 68 m

* FIFA’s reference 105×68 m; clubs can vary a little. Multiply the % by the stadium’s actual length/width when you need metres.

Key things to remember

Absolute, TV‑camera view
Opta never flips the grid at half‑time.
• Home team might attack left→right in the 1st half and right→left in the 2nd.
• The coordinates stay fixed; the team’s sense of “left” and “right” changes.
Centre spot is always (50 , 50).
Penalty spots sit roughly at (11 % from each goal‑line) → (11, 50) and (89, 50).
Goal‑mouth qualifiers
Shots/goals get extra qualifiers for the frame of the goal:
- Goal‑mouth y (0 – 100 across the face, 0 = keeper’s left post)
- Goal‑mouth z (0 – 100 height, 0 = ground, 100 = cross‑bar)
Start vs. end positions
‑ Passes, carries and clearances keep only their start (x, y) in the core record.
‑ The end point arrives via qualifiers (End location x/y) or a companion “Outcome” event.
Why 0‑100?
• Scale‑free: plots look identical for youth and senior pitches.
• Easy math for heat‑maps (each integer is 1 % of the surface).

Quick conversion example (code clip)

# where 'row' is one event
metres_x = row["x"] / 100 * 105   # length in metres
metres_y = row["y"] / 100 * 68    # width in metres

Change 105 / 68 to the actual ground size if you have it.

How this matters for your trophy work

Laser‑etch a shot map – you can draw every goal or key pass directly on a 0–100 grid and scale it to the metal face.
Dynamic LED ring – ring segments could light up proportional to x‑distance of a decisive action (e.g., last‑minute tackle at x = 15 flashes a segment near the team’s own goal).
Story labels – “Scored from 11 m, dead‑centre” is just (x=90,y=50) × pitch length/width.

Whenever you pull a single event from the JSON, remember that:

(x, y) = (0, 0)  → bottom‑left corner on TV
(x, y) = (100, 100) → top‑right corner on TV

…and everything else is a percentage of the full dimensions.