reep

Reep

The football entity register. Maps player, team, coach, competition, and season identities across Transfermarkt, FBref, UEFA, Sofascore, and 30+ data providers.

Named after Charles Reep (1904–2002), an RAF wing commander who hand-recorded every action in over 2,200 football matches starting in the 1950s. He’s considered the grandfather of football analytics – decades before expected goals or tracking data, Reep was tallying passes, shots, and sequences with pen and paper, pioneering the idea that football could be understood through data.

Start here: the current register

The living register is Reep v1, published at reep.football. It is open infrastructure: complete, dated snapshots of the provider-ID crosswalk — Reep IDs, provider namespaces and identifiers, redirects and confidence labels — free to download and use.

Why isn’t the v1 engine in this repository? The register is open; the engine that builds and repairs it is not. Producing a trustworthy crosswalk repeatably is the work we do commercially, and it funds the public register. What is open is the output and the method: the snapshots, the evidence rules, the identity policy, and the measured precision and recall of each release. No part of the public register is held back to make sponsorship or consultancy more attractive — see the independence policy.

This repository is the frozen v0 register and RapidAPI/D1 API surface. It remains available for existing users during the migration bridge, and everything below documents it. New integrations should start from the v1 surfaces above; see the RapidAPI migration guide. v0 reep_... IDs are not interchangeable with Reep v1 IDs.

The data files are frozen too, not just the API. The last CSV release was 2026.25 (21 June 2026), and the API’s database has taken no writes since 25 April 2026. Neither receives further updates or corrections.

v0 reference (frozen)

Everything from here down describes the frozen v0 data files and API.

What is this?

A canonical identity file for football. Every person, club, competition, and season gets a stable Reep ID (reep_<type_prefix><8hex>), linked to their IDs on other platforms. If you have a Transfermarkt ID and need the FBref ID for the same player — or want to resolve an Opta competition ID to its FBref equivalent — this register gives you the answer.

The unique key is reep_id. Wikidata QIDs are available as a provider mapping where the entity exists in Wikidata, but entities can exist independently (e.g. lower-league players sourced from Opta).

People who are both players and coaches (e.g. Pep Guardiola) have separate records with distinct Reep IDs — reep_p* for the player record, reep_c* for the coach record.

Think of it as the football equivalent of the Chadwick Baseball Bureau Register.

Data

These CSVs are the v0 public files. The v1 release files use a different bridge-register contract with canonical CSVs, a DuckDB convenience bundle, release metadata, namespace-scoped bridges, bridge-only provider roles and overlay-only Wikidata aliases. Use reep.football/downloads for the current v1 download surface.

People schema

Teams schema

Competitions schema

Seasons schema

Names schema

Coverage

Not every entity has every ID. Coverage depends on what the Wikidata community has mapped plus independently verified mappings. GET /stats returns the frozen v0 counts; they no longer change.

Wikidata IDs are community-maintained; they updated automatically with each refresh while v0 was live, and are now fixed at the 2026.25 snapshot. Verified IDs were matched independently using DOB, name, and cross-provider bridges, then validated before inclusion.

Usage

Python

import csv

# Load people into a dict keyed by Reep ID
people = {}
with open("data/people.csv") as f:
    for row in csv.DictReader(f):
        people[row["reep_id"]] = row

# Look up by Transfermarkt ID
tm_index = {row["key_transfermarkt"]: row for row in people.values() if row["key_transfermarkt"]}
palmer = tm_index["568177"]
print(palmer["reep_id"])    # "reep_p2804f5db"
print(palmer["key_fbref"])  # "dc7f8a28"

R

library(readr)
people <- read_csv("data/people.csv")

# All Premier League-registered players
pl_players <- people |> filter(key_premier_league != "")

# Cross-reference: Transfermarkt -> FBref
people |>
  filter(key_transfermarkt == "568177") |>
  select(reep_id, name, key_fbref, key_sofascore)

SQL (load into SQLite)

sqlite3 reep.db <<EOF
.mode csv
.import data/people.csv people
.import data/teams.csv teams
.import data/competitions.csv competitions
.import data/seasons.csv seasons
.import data/names.csv names
EOF

-- Find all IDs for a player
SELECT * FROM people WHERE name LIKE '%Salah%';

-- Reverse lookup: FBref ID -> everything
SELECT * FROM people WHERE key_fbref = 'e342ad68';

-- Lookup by Reep ID
SELECT * FROM people WHERE reep_id = 'reep_p2804f5db';

API

The API in this repository is the v0 REST interface served through RapidAPI and the legacy Cloudflare Worker. It remains available for existing users during the migration bridge. All providers (Wikidata + custom verified) are available to all plans.

Get your API key on RapidAPI.

For new integrations, use the v1 release API at reep.football/api. The v1 API is release-backed, uses direct Reep API keys, and requires namespace-aware provider ID resolution:

curl -H "Authorization: Bearer $REEP_API_KEY" \
  "https://reep.football/api/v1/resolve/transfermarkt/568177?namespace=spieler&type=player"

See the RapidAPI migration guide before moving a v0 consumer. v1 is not a drop-in continuity layer for v0 reep_... IDs.

The /lookup endpoint auto-detects the ID type: Reep IDs start with reep_, Wikidata QIDs start with Q. The legacy ?qid= parameter is still supported.

All endpoints that return entities accept an optional type parameter (player, team, coach, competition, season). For dual-role people, /lookup without type returns all records. Default search excludes seasons to avoid noise — use type=season to search seasons explicitly.

Reep IDs

Every entity in the register has a self-minted Reep ID as its canonical identifier. The format is reep_<type_prefix><8hex>:

Reep IDs are stable — they never change, even if a player’s Wikidata QID is merged or deleted. Wikidata QIDs are available as a provider mapping (key_wikidata in CSVs, qid in API responses) but are not the identity backbone.

This design follows the Chadwick Baseball Bureau Register model: self-minted UUIDs as primary keys, with all provider IDs (including Wikidata) as cross-references.

CLI

A Python CLI for the register lives in its own repo: withqwerty/reep-cli.

pip install git+https://github.com/withqwerty/reep-cli.git

# Search by name
reep search "Cole Palmer"

# Resolve: Transfermarkt -> all IDs
reep resolve transfermarkt 568177

# Translate: just output the target ID (pipe-friendly)
reep translate transfermarkt 568177 fbref
# dc7f8a28

# Download CSVs for offline use
reep download

# Search offline
reep local "Salah"

Source

Most data is extracted from Wikidata via SPARQL. Wikidata is a free, collaborative knowledge base maintained by thousands of volunteers. The cross-provider ID mappings exist because the Wikidata community has systematically added external identifier properties for football data sources.

Entities not in Wikidata (e.g. lower-league players) are sourced from authoritative provider databases like Opta’s F1 player database.

Wikidata properties used

Provider notes

Opta / Stats Perform — Three distinct ID systems exist within Stats Perform’s ecosystem:

• opta — 25-char alphanumeric UUIDs (e.g. 7cwgrmorsb42qaj5vrhp8fhzp) from the current SD API / Stats Perform F1 database. Used for players (50K), teams, competitions, and seasons. This is the canonical Opta provider.
• opta_numeric — Legacy numeric codes (e.g. 244851 for Cole Palmer). Same as FPL code field, The Analyst sc- URL IDs, and Wikidata P8735/P8736/P8737. Players (3.8K), teams (255), competitions (73), coaches (28). Sources: FPL data, Wikidata dump, Opta Web Archive feeds.
• optacore — A separate numeric system with different numbers (e.g. FA Cup = 93 vs opta_numeric 1). Competitions only (47). From the SD API mapping file.

WorldFootball.net / heim:spiel — WorldFootball.net (owned by heim:spiel) migrated from slug-based URLs (e.g. cole-palmer) to numeric IDs in November 2025. The old slugs still work via redirect. Wikidata P2020 contains the old slug format. The heim:spiel numeric IDs in Reep are the same as the new WorldFootball.net IDs — the URL prefix indicates entity type:

Soccerway / Flashscore — Both owned by Livesport (Czech data company), but use separate ID systems. Soccerway changed their URL/ID scheme in September 2025. Reep has 139K Soccerway IDs in the old numeric format from Wikidata P2369 (e.g. 45569). The old URLs still redirect:

A new Wikidata property for the new format has been proposed but not yet approved.

Updates

The v0 register is no longer refreshed. The last data release was 2026.25, generated on 21 June 2026, and the D1 database behind the API has taken no writes since 25 April 2026. No further refreshes are planned, and reported faults are not back-ported here — they are fixed in the v1 register instead. The data/meta.json file records when the current CSVs were generated.

Historically, v0 was refreshed periodically from Wikidata, plus monthly reconciliation against the full Wikidata dump to catch drift (deleted entities, lost occupations, missed IDs). Each refresh picked up new entities, updated IDs, and corrections made by the Wikidata community, and custom provider mappings persisted across refreshes.

Contributing

Share ID mappings

Have a dataset that maps football player or team IDs across providers? We’d love to include it. Send us a CSV with these columns:

The more columns you include, the more accurately we can match to existing entities. A Transfermarkt ID or date of birth alone is usually enough.

How to submit:

• Open an issue with your CSV attached or linked
• Email [email protected] if you prefer to contribute anonymously

We validate and match all submissions before adding them. Your IDs go into our verified custom mappings. Note that submissions now land in the v1 register — the frozen v0 files and API here are not updated.

Edit Wikidata directly

If a player is missing a Transfermarkt ID or FBref ID, the ideal fix is to add it to their Wikidata page — the next v1 refresh picks it up automatically. The frozen v0 files here will not pick it up.

• How to edit Wikidata
• Add an external identifier

Wikidata requires ~50 manual edits and a 4-day waiting period before bulk edits are possible. If you have a large dataset, send it to us (see above) and we’ll handle the Wikidata submission on your behalf.

Code contributions

PRs to the Worker (src/) and documentation are welcome in this repo. CLI PRs belong in withqwerty/reep-cli. Note that the data CSVs are regenerated upstream from Wikidata + verified mappings — don’t PR data changes directly.

What this repo doesn’t contain

This repo publishes IDs, the API, and the published CSVs — not scraping logic or raw data dumps from providers. Matching and ingestion scripts are maintained in a separate private repo.

Support the register

Keeping a football identity register true is continuous work: cutting and publishing releases, repairing wrong merges, adding competitions and sources, and measuring accuracy on every release. That upkeep is funded by sponsorship, and the record of it is public — releases published, corrections applied and measured precision and recall are all on reep.football/sponsorship.

Sponsorship buys acknowledgement and nothing else. It never buys favourable identity decisions, suppressed corrections, exclusive fields or earlier access, and a data provider that sponsors the register is named publicly as a provider sponsor. The full terms are in the independence policy.

If you use the register yourself, the simplest way to keep it going is GitHub Sponsors — recurring or one-off, from a few pounds a month.

If your organisation depends on it, sponsorship runs by agreement, with an invoice, a named contact and your logo on the sponsors section of reep.football/sponsorship. Support starts to make a real difference at around £500 a month, and a founding sponsor at £1,500–2,500 a month covers a substantial share of what it costs to keep the register published and repaired. Those are indications for sizing a budget, not a price list — get in touch at [email protected].

Nobody sponsors the register yet, and the sponsors section says so. It will name every sponsor for as long as they support it.

Reporting a correction is worth as much as money. If you spot a wrong ID or a bad merge, open an issue.

License

The data is derived from Wikidata and is available under CC0 1.0.