Event-Matching

Das ProblemPermalink for this section

Jeder Sportsbook verwendet seine eigenen internen Event-IDs. Dasselbe Spiel Lakers gegen Celtics kann auf DraftKings das Event 33483200, auf FanDuel nba-bos-lal-20260208 und auf Pinnacle 556677889 sein. Ohne einen einheitlichen Identifikator erfordert der Aufbau von buchübergreifenden Vergleichswerkzeugen die Implementierung einer eigenen Event-Matching-Logik.

Wie SharpAPI dies löstPermalink for this section

SharpAPI generiert eine kanonische Event-ID für jedes Event. Diese ID ist deterministisch — dasselbe reale Event erhält immer die gleiche id, unabhängig davon, von welchem Sportsbook es stammt.

Format: {league}_{teamA}_{teamB}_{YYYY-MM-DD}_b{N}

Das abschließende _b{N} ist ein 6-Stunden-Startzeit-Bucket — siehe Startzeit-Bucket-Suffix unten.

Beispiel: Ein Spiel Celtics gegen Lakers am 8. Februar 2026 erzeugt dieselbe ID über alle Sportsbooks hinweg:

Zwei Arten von Event-IDsPermalink for this section

Jedes Event in der API verfügt über zwei ID-Felder:

{
  "id": "nba_celtics_lakers_2026-02-08_b3",
  "external_ids": {
    "draftkings": "33483200",
    "fanduel": "nba-bos-lal-20260208",
    "pinnacle": "556677889",
    "betmgm": "ms_44556"
  }
}

Wie kanonische IDs erzeugt werdenPermalink for this section

Die kanonische ID wird aus vier Komponenten aufgebaut:

1. Liga-Code — Sportart einer Liga zugeordnet (z. B. basketball → nba)
2. Teamnamen — normalisiert und alphabetisch sortiert
3. Datum — Event-Startdatum im Format YYYY-MM-DD
4. Startzeit-Bucket — Suffix _b{N}, wobei N in 0..3 liegt

Normalisierung von TeamnamenPermalink for this section

Teamnamen werden normalisiert, um Variationen über Sportsbooks hinweg auszugleichen:

• "Los Angeles Lakers" → lakers
• "LA Lakers" → lakers
• "LAL" → lakers

Die Normalisierung entfernt Präfixe (“The”, “Los”, “Las”), Suffixe (“FC”, “United”, “City”), Interpunktion und Akzente. Anschließend werden die Teams alphabetisch sortiert, sodass die ID unabhängig von der Heim-/Auswärts-Reihenfolge identisch ist.

Startzeit-Bucket-Suffix (_b{N})Permalink for this section

Das Suffix _b{N} ist ein 6-Stunden-Startzeit-Bucket. N liegt in 0..3:

Für US-Liga-Sportarten (NBA, NFL, NHL, MLB, NCAAB, NCAAF, WNBA, NCAAW) ist der Bucket an der Eastern Time verankert, sodass ein Tip-off um 19:30 Uhr ET in _b3 landet — unabhängig davon, wie die Bücher ihre UTC-Offsets stempeln. Für alle anderen Sportarten (Fußball, Tennis, Cricket usw.) ist der Bucket an UTC verankert.

Warum es das gibt. Gleiches Matchup, gleiches Kalenderdatum, aber unterschiedliche reale Spiele sind möglich:

• Ein MLB-Doubleheader mit zwei Spielen am selben Tag.
• Ein MLB-Spiel am US-Abend, dessen UTC-Stempel auf den nächsten Kalendertag fällt, plus ein echtes Rückspiel am Folgetag, dessen UTC-Stempel auf dasselbe Datum fällt.

Ohne den Bucket würden beide Spiele auf einer ID kollidieren und die Quoten würden vermischt. Mit ihm landen die beiden Spiele auf unterschiedlichen _bN-Suffixen und bleiben getrennt.

Was das für buchübergreifendes Matching bedeutet. Innerhalb eines Spiels konvergieren alle Bücher, die eine Startzeit im selben 6-Stunden-Fenster melden, auf dasselbe _b{N}. Über eine Bucket-Grenze hinweg — zum Beispiel stempelt ein Buch einen Fußball-Anstoß auf 17:55 UTC (_b2) und ein anderes auf 18:10 UTC (_b3) — können Bücher auf zwei kanonische IDs fragmentieren. Dies ist eine bekannte Einschränkung. Wenn Sie dies beobachten, erstellen Sie ein Ticket mit den Event-Details.

Doubleheader-Suffix (_g{N})Permalink for this section

Wenn ein Buch beide Spiele eines Doubleheaders am selben Tag in einem einzigen Update meldet, werden die beiden Spiele mit einem nachgestellten _g{N}-Suffix hinter dem Bucket unterschieden — z. B. mlb_athletics_mariners_2026-05-02_b0 und mlb_athletics_mariners_2026-05-02_b0_g1. Bücher, die nur eines der beiden Spiele sehen, emittieren die reine gebucketete ID. Die verbleibende buchübergreifende Diskrepanz bei Doubleheadern ist daher: gleiche _b{N}-Basis, wobei eine Seite ein _g{N}-Suffix trägt und die andere nicht.

Ein Matchup über mehrere IDs gruppierenPermalink for this section

Um Zeilen zusammenzuführen, die zu einem einzigen physischen Spiel gehören, aber auf unterschiedlichen kanonischen IDs gelandet sind, wählen Sie die Ebene, die Ihrer Toleranz für das Zusammenführen entspricht:

1. Same-Fixture-Collapse (empfohlen). Entfernen Sie ein nachgestelltes _g{N}-Suffix und vergleichen Sie den Rest, wobei der _b{N}-Bucket erhalten bleibt:

   key = event_id ohne nachgestelltes _g{N}          # ..._b0_g1 → ..._b0
   Events gruppieren, deren bereinigter key identisch ist

   Dies führt die oben beschriebene Doubleheader-Suffix-Diskrepanz wieder zusammen, ohne unterschiedliche Spiele zu vermischen. Es spiegelt das serverseitige Same-Event-Prädikat wider.

2. Loses Matchup-Grouping (Anzeige). Um jeden Preis für ein Matchup an einem Datum unabhängig vom Bucket zu sammeln — z. B. um in einer UI eine Karte pro Spiel darzustellen und die oben beschriebene Fragmentierung an Bucket-Grenzen aufzufangen — entfernen Sie sowohl das _g{N}- als auch das _b{N}-Suffix und gruppieren Sie nach {league}_{teamA}_{teamB}_{date}, mit einer Toleranz von ±1 Tag für Startzeiten, die die UTC-Mitternacht überschreiten:

   key = "{league}_{teamA}_{teamB}_{date}"           # Teams sind bereits alphabetisch sortiert; _b{N}/_g{N} entfernt
   keys gruppieren, die Liga + Teams teilen und deren Daten höchstens 1 Tag auseinanderliegen

   Kompromiss: Da hierbei der Bucket verworfen wird, kollabiert ein echter Doubleheader am selben Tag in eine Gruppe. Verwenden Sie Ebene 1, wenn die beiden Spiele getrennt bleiben müssen.

Verwendung kanonischer IDs in Ihrer AnwendungPermalink for this section

Als PrimärschlüsselPermalink for this section

Verwenden Sie das Feld id als Primärschlüssel Ihrer Datenbank beim Speichern von Events:

// Fetch events from the API
const { data: events } = await fetch(
  'https://api.sharpapi.io/api/v1/events?league=nba',
  { headers: { 'X-API-Key': API_KEY } }
).then(r => r.json());
 
// Store using canonical ID as primary key
for (const event of events) {
  await db.events.upsert({
    id: event.id,  // "nba_celtics_lakers_2026-02-08_b3"
    home_team: event.home_team,
    away_team: event.away_team,
    start_time: event.start_time,
    external_ids: event.external_ids
  });
}

Buchübergreifender QuotenvergleichPermalink for this section

Die kanonische ID ermöglicht es Ihnen, Quoten für dasselbe Event über alle Bücher hinweg zu vergleichen:

// Get odds filtered to a specific event
const { data } = await fetch(
  'https://api.sharpapi.io/api/v1/events/nba_celtics_lakers_2026-02-08_b3/odds',
  { headers: { 'X-API-Key': API_KEY } }
).then(r => r.json());
 
// All odds in the response are for the same canonical event
// Group by sportsbook to compare
const byBook = {};
for (const odds of data.odds) {
  byBook[odds.sportsbook] = byBook[odds.sportsbook] || [];
  byBook[odds.sportsbook].push(odds);
}

Deep-Linking zu SportsbooksPermalink for this section

Verwenden Sie external_ids, um Nutzer auf die Event-Seite eines bestimmten Sportsbooks zu verlinken:

const event = await getEvent('nba_celtics_lakers_2026-02-08_b3');
 
// Build a sportsbook-specific link
const dkEventId = event.external_ids['draftkings'];
// → "33483200"

Wie dies EV- und Arbitrage-Erkennung ermöglichtPermalink for this section

Die Engines zur Erkennung von Opportunitäten von SharpAPI greifen intern auf kanonische Event-IDs zurück:

• EV-Berechnung ermittelt die Referenzquoten des scharfen Buchs (Pinnacle) für dieselbe eventId und vergleicht sie mit den Quoten weicher Bücher
• Arbitrage-Erkennung gruppiert alle Quoten nach eventId und Markttyp, um buchübergreifende Preisabweichungen zu finden
• Middles-Erkennung findet überlappende Linien über Bücher hinweg für dieselbe eventId

Dies ist dasselbe Matching-System, das Ihnen über die API zur Verfügung gestellt wird — wenn Sie eine Arbitrage-Möglichkeit mit Legs von verschiedenen Sportsbooks sehen, ist die kanonische Event-ID das, was diese Quoten miteinander verbunden hat.

Wesentliche EigenschaftenPermalink for this section