|
| 1 | +--- |
| 2 | +description: "Entitäts-Referenz-IDs — numerical_id-Semantik, verschachtelte Team/Sport/Liga/Market/Sportsbook-Objekte und deren Verwendung für Joins, Indizierung und Cross-Feed-Mapping." |
| 3 | +--- |
| 4 | + |
| 5 | +import { Callout } from 'nextra/components' |
| 6 | + |
| 7 | +# Entitäts-Referenz-IDs |
| 8 | + |
| 9 | +SharpAPI gibt stabile, ganzzahlig-kodierte Bezeichner (`numerical_id`) für jede Referenzentität aus, sowie selbstbeschreibende verschachtelte Referenzobjekte für jede Odds-Zeile und jedes Opportunity-Leg. Diese Seite dokumentiert, was diese IDs garantieren, wie sie verwendet werden und wie sie mit den bestehenden String-IDs zusammenhängen. |
| 10 | + |
| 11 | +<Callout type="info"> |
| 12 | + **Neu (Mai 2026).** Sowohl `numerical_id` als auch die verschachtelten Referenzobjekte sind **additiv**. Bestehende String-IDs (`sport: "baseball"`, `league: "mlb"`, `sportsbook: "pinnacle"`, `home_team: "New York Yankees"`) bleiben in jeder Antwort erhalten und sind nicht veraltet. Es gibt keinen Zeitplan für deren Entfernung — beide Formen werden dauerhaft unterstützt. |
| 13 | +</Callout> |
| 14 | + |
| 15 | +## Was ist neu |
| 16 | + |
| 17 | +Jeder Referenz-Endpoint (`/sports`, `/leagues`, `/sportsbooks`, `/markets`, `/teams`) gibt jetzt zusätzlich zur bestehenden Slug-`id` einen `numerical_id`-Ganzzahlwert zurück. `/teams` gibt zusätzlich ein `abbreviation`-Feld zurück, sofern bekannt. |
| 18 | + |
| 19 | +Jede Odds-Zeile (und jedes Leg einer EV- / Arbitrage- / Middle-Opportunity) enthält nun sechs optionale **verschachtelte Referenzobjekte**, die `id`, Anzeigename und `numerical_id` der Entität direkt mit der Zeile bündeln — ohne zusätzliche Abfrage gegen `/sports` oder `/teams`: |
| 20 | + |
| 21 | +```json |
| 22 | +{ |
| 23 | + "home": { |
| 24 | + "id": "new_york_yankees", |
| 25 | + "numerical_id": 20, |
| 26 | + "name": "New York Yankees", |
| 27 | + "abbreviation": "NYY", |
| 28 | + "logo": "https://cdn.opticodds.com/team-logos/baseball/36.png", |
| 29 | + "city": "New York", |
| 30 | + "mascot": "Yankees", |
| 31 | + "conference": "AL", |
| 32 | + "division": "East Division" |
| 33 | + }, |
| 34 | + "away": { |
| 35 | + "id": "boston_red_sox", |
| 36 | + "numerical_id": 5, |
| 37 | + "name": "Boston Red Sox", |
| 38 | + "abbreviation": "BOS", |
| 39 | + "logo": "https://cdn.opticodds.com/team-logos/baseball/14.png", |
| 40 | + "city": "Boston", |
| 41 | + "mascot": "Red Sox", |
| 42 | + "conference": "AL", |
| 43 | + "division": "East Division" |
| 44 | + }, |
| 45 | + "sport_ref": { "id": "baseball", "numerical_id": 3, "name": "Baseball" }, |
| 46 | + "league_ref": { "id": "mlb", "numerical_id": 354, "label": "MLB" }, |
| 47 | + "market_ref": { "id": "moneyline", "numerical_id": 878, "label": "Moneyline" }, |
| 48 | + "sportsbook_ref": { "id": "pinnacle", "numerical_id": 28, "label": "Pinnacle" } |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +## `numerical_id`-Semantik |
| 53 | + |
| 54 | +Jede `numerical_id` wird aus einem einmal festgelegten, domänenspezifischen Registry unter `api-adapters/sharp_atlas/` vergeben. Der Vertrag lautet: |
| 55 | + |
| 56 | +| Eigenschaft | Garantie | |
| 57 | +|---|---| |
| 58 | +| **Eingefroren** | Einmal vergeben, wird eine `numerical_id` niemals wiederverwendet, neu ausgestellt oder einer anderen Entität zugeordnet. Die `numerical_id: 20` der Yankees bleibt `20`, bis die API eingestellt wird. | |
| 59 | +| **Dicht ab 1** | IDs beginnen bei `1` und werden sequenziell pro Domäne vergeben. Es gibt keine negativen oder null-IDs und keine großen Lücken. Sports, Ligen, Sportsbooks, Markets und Teams haben jeweils einen eigenen dichten Bereich. | |
| 60 | +| **Domänen-begrenzt** | Eine `numerical_id` ist nur innerhalb ihrer Domäne (Sport, Liga, Sportsbook, Market, Team) eindeutig. `numerical_id: 3` bei einem Sport hat keinen Bezug zu `numerical_id: 3` bei einem Team. Zur Unterscheidung muss die Ganzzahl mit der Domäne kombiniert werden. | |
| 61 | +| **Vergeben, nicht abgeleitet** | IDs werden explizit in den Atlas-JSONs verfolgt — sie sind keine Hashes des Slugs und werden nicht aus der Sortierreihenfolge berechnet. Das Hinzufügen einer neuen Entität vergibt die nächste freie Ganzzahl; das Umbenennen eines Slugs ändert dessen `numerical_id` nicht. | |
| 62 | +| **Keine Sportsbook-ID** | Dies ist SharpAPIs Bezeichner, nicht die interne des Sportsbooks. Die nativen Event-/Market-/Selection-IDs eines Bookmakers werden weiterhin zeilenweise ausgegeben — siehe `external_event_id`, `selection_id`, `market_id` und `external_ids` am [Events](/de/api-reference/events)-Endpoint. | |
| 63 | + |
| 64 | +## Wenn Felder fehlen |
| 65 | + |
| 66 | +Die verschachtelten Referenzobjekte werden **nur ausgegeben, wenn die zugrundeliegende Entität im Atlas gemappt wurde**. Bei nicht gemappten Entitäten — typischerweise Long-Tail-Ligen, exotische Markets oder neu hinzugefügte Sportsbooks vor der Katalogzuweisung — wird der entsprechende `*_ref`-Block weggelassen (oder hat `numerical_id: null`), und das vorhandene String-Feld in der Zeile ist die einzige sichtbare ID. |
| 67 | + |
| 68 | +In der Praxis: |
| 69 | + |
| 70 | +- Wichtige Sports, Ligen und Books sind vollständig gemappt — jeder `*_ref`-Block ist zu erwarten. |
| 71 | +- Player-Prop-Markets und Ecken/Karten/Perioden-Markets im Fußball haben den breitesten Katalog; einige Nischen-Prop-Typen werden noch zugewiesen. |
| 72 | +- Team-`abbreviation` ist dort befüllt, wo ein Kürzel allgemein bekannt ist (US-Major-Ligen, EPL, ATP/WTA-Kürzel). Bei kleineren / internationalen Teams kann es fehlen. |
| 73 | + |
| 74 | +Konsumenten sollten jeden verschachtelten Block als **optional** behandeln. Generische Clients sollten auf das flache String-Feld (`sport`, `league`, `sportsbook`, `home_team`, `away_team`, `market_type`) zurückfallen, wenn der entsprechende `*_ref` nicht vorhanden ist. |
| 75 | + |
| 76 | +## Empfohlene Verwendung |
| 77 | + |
| 78 | +### Indizierung & Joins |
| 79 | +Verwende `numerical_id` als Primärschlüssel beim Speichern von Odds/Opportunities in deiner eigenen Datenbank. Ganzzahlschlüssel sind kleiner, günstiger zu indizieren und bleiben stabil bei Slug-Umbenennungen oder Änderungen von Anzeigenamen. |
| 80 | + |
| 81 | +### Cross-Feed-Mapping |
| 82 | +Wenn du von mehreren Datenanbietern importierst, bietet `numerical_id` eine schnelle Gleichheitsprüfung innerhalb von SharpAPI-Zeilen. Für das Mapping **über** Anbieter hinweg ist der Slug-`id` nach wie vor der portablere Join-Schlüssel — Slugs sind lesbar und tendieren dazu, sich über Anbieter hinweg stärker zu überschneiden als Ganzzahl-IDs. |
| 83 | + |
| 84 | +### UI-Anzeige |
| 85 | +Verwende `name` (Sports, Teams) oder `label` (Ligen, Markets, Sportsbooks) zur Anzeige; `abbreviation` bei `home`/`away` eignet sich für kompakte Zellen. |
| 86 | + |
| 87 | +### Streaming |
| 88 | +Dieselben verschachtelten Objekte erscheinen auf `/api/v1/stream/odds` SSE-Frames und auf WebSocket v1 / v1.5 Odds-Payloads — kein separater Stream ist erforderlich. |
| 89 | + |
| 90 | +## Feldreferenz |
| 91 | + |
| 92 | +### Referenz-Endpoints |
| 93 | + |
| 94 | +Jeder Referenz-Endpoint fügt seinem bestehenden Objektschema `numerical_id` hinzu. `/teams` fügt zusätzlich `abbreviation` hinzu. |
| 95 | + |
| 96 | +| Endpoint | Hinzugefügtes Feld | Typ | Hinweise | |
| 97 | +|---|---|---|---| |
| 98 | +| [`/sports`](/de/api-reference/sports) | `numerical_id` | integer \| null | Sport-begrenzte Domäne | |
| 99 | +| [`/leagues`](/de/api-reference/leagues) | `numerical_id` | integer \| null | Liga-begrenzte Domäne | |
| 100 | +| [`/sportsbooks`](/de/api-reference/sportsbooks) | `numerical_id` | integer \| null | Sportsbook-begrenzte Domäne | |
| 101 | +| [`/markets`](/de/api-reference/markets) | `numerical_id` | integer \| null | Market-Typ-begrenzte Domäne | |
| 102 | +| [`/teams`](/de/api-reference/teams) | `numerical_id`, `abbreviation`, `logo`, `city`, `mascot`, `conference`, `division` | integer \| null, string \| null | Team-begrenzte Domäne. Die letzten fünf sind Atlas-Metadaten aus OpticOdds. | |
| 103 | + |
| 104 | +### Verschachtelte Referenzblöcke bei Odds & Opportunity-Legs |
| 105 | + |
| 106 | +| Block | Wo | Felder | Zweck | |
| 107 | +|---|---|---|---| |
| 108 | +| `home`, `away` | Jede Odds-Zeile, jedes Opportunity-Leg | `id`, `numerical_id`, `name`, `abbreviation`, `logo`, `city`, `mascot`, `conference`, `division` | Löst die beiden Kontrahenten ohne separaten `/teams`-Aufruf auf. | |
| 109 | +| `sport_ref` | Wie oben | `id`, `numerical_id`, `name` | Anzeigebereiter Sport-Verweis. | |
| 110 | +| `league_ref` | Wie oben | `id`, `numerical_id`, `label` | Anzeigebereiter Liga-Verweis. | |
| 111 | +| `market_ref` | Wie oben | `id`, `numerical_id`, `label` | Anzeigebereiter Market-Verweis (kanonischer Market-Typ). | |
| 112 | +| `sportsbook_ref` | Wie oben | `id`, `numerical_id`, `label` | Anzeigebereiter Sportsbook-Verweis. | |
| 113 | + |
| 114 | +Alle inneren Felder sind **optional** innerhalb eines Blocks. Ein Block kann mit einer `null`-`numerical_id` vorhanden sein, wenn der Slug gemappt wurde, die Ganzzahlzuweisung aber noch aussteht; sowohl `numerical_id` als auch der gesamte Block können bei nicht gemappten Entitäten fehlen. |
| 115 | + |
| 116 | +### Team-Metadatenfelder |
| 117 | + |
| 118 | +Die `home`- / `away`-Blöcke enthalten fünf zusätzliche optionale Metadatenfelder über `id` / `numerical_id` / `name` / `abbreviation` hinaus. Sie stammen aus dem SharpAPI-Atlas und sind für die große Mehrheit der Teams befüllt (ca. 93 % bei `logo`, mit vergleichbarer Abdeckung für den Rest): |
| 119 | + |
| 120 | +| Feld | Beispiel | Hinweise | |
| 121 | +|---|---|---| |
| 122 | +| `logo` | `"https://cdn.opticodds.com/team-logos/baseball/36.png"` | Vollständige CDN-URL für ein Team-Wappen. Behandle den Host als undurchsichtig; SharpAPI kann dasselbe Asset in Zukunft unter seiner eigenen Domain neu hosten. | |
| 123 | +| `city` | `"New York"` | Der geografische Ankerpunkt des Teams. Bei Teams mit mehreren Städten (z. B. die New York Football Giants, die in NJ spielen) folgen wir der konventionellen Bezeichnung der Liga. | |
| 124 | +| `mascot` | `"Yankees"` | Das Maskottchen / der Spitznamensteil des vollständigen Namens. | |
| 125 | +| `conference` | `"AL"`, `"AFC"`, `"Western"` | Liga-definierte Konferenz / Gruppierung. Format variiert je Liga. | |
| 126 | +| `division` | `"East Division"`, `"NL East"`, `"Pacific Division"` | Untergruppierung innerhalb der Konferenz, liga-definiert. | |
| 127 | + |
| 128 | +Einzelsport-Teilnehmer (Tennisspieler, MMA-Kämpfer, Golfer, Fahrer) haben diese Felder in der Regel nicht befüllt — sie sind keine "Teams" im konventionellen Sinne und erben nur `id` / `numerical_id` / `name`. |
| 129 | + |
| 130 | +## Migration |
| 131 | + |
| 132 | +Es gibt nichts zu migrieren. Fahre mit den flachen String-Feldern fort, wenn sie deinen Bedarf decken. Übernimm die `*_ref`-Blöcke und `numerical_id` selektiv, wenn: |
| 133 | + |
| 134 | +- du einen stabilen Ganzzahlschlüssel für die Speicherung benötigst, |
| 135 | +- du anzeigebereite Labels ohne einen zweiten API-Aufruf möchtest, |
| 136 | +- oder du eine Cross-Feed-Normalisierungsschicht aufbaust. |
| 137 | + |
| 138 | +Die flachen Felder und die verschachtelten Blöcke beschreiben dieselbe Zeile — sie werden sich nicht widersprechen. |
| 139 | + |
| 140 | +## Verwandte Themen |
| 141 | + |
| 142 | +- [Sports](/de/api-reference/sports), [Leagues](/de/api-reference/leagues), [Sportsbooks](/de/api-reference/sportsbooks), [Markets](/de/api-reference/markets), [Teams](/de/api-reference/teams) — Referenz-Endpoints mit dem neuen `numerical_id`-Feld |
| 143 | +- [Odds Snapshot](/de/api-reference/odds), [+EV Opportunities](/de/api-reference/opportunities-ev), [Arbitrage](/de/api-reference/opportunities-arbitrage), [Middles](/de/api-reference/opportunities-middles) — Endpoints mit verschachtelten Referenzblöcken |
| 144 | +- [Event Matching](/de/concepts/event-matching) — wie SharpAPI dasselbe Spiel über verschiedene Books hinweg zusammenführt |
![paperclip-resolver[bot]](https://github.githubassets.com/images/gravatars/gravatar-user-420.png?size=40){kind=avatar}
0 commit comments