Entity reference IDs

SharpAPI emits stable, integer-keyed identifiers (numerical_id) on every reference entity, plus self-describing nested reference objects on every odds row and opportunity leg. This page documents what those IDs guarantee, how to use them, and how they relate to the existing string IDs.

What’s new

Each reference endpoint (/sports, /leagues, /sportsbooks, /markets, /teams) now returns a numerical_id integer alongside the existing slug id. /teams additionally returns an abbreviation field where one is known.

Each odds row (and each leg of an EV / arbitrage / middle opportunity) now carries six optional nested reference objects that bundle the entity’s id, display label, and numerical_id directly with the row — no second lookup against /sports or /teams needed:

{
  "home": {
    "id": "new_york_yankees",
    "numerical_id": 20,
    "name": "New York Yankees",
    "abbreviation": "NYY",
    "logo": "https://cdn.opticodds.com/team-logos/baseball/36.png",
    "city": "New York",
    "mascot": "Yankees",
    "conference": "AL",
    "division": "East Division"
  },
  "away": {
    "id": "boston_red_sox",
    "numerical_id":  5,
    "name": "Boston Red Sox",
    "abbreviation": "BOS",
    "logo": "https://cdn.opticodds.com/team-logos/baseball/14.png",
    "city": "Boston",
    "mascot": "Red Sox",
    "conference": "AL",
    "division": "East Division"
  },
  "sport_ref":      { "id": "baseball",         "numerical_id":  3, "name": "Baseball" },
  "league_ref":     { "id": "mlb",              "numerical_id": 354, "label": "MLB" },
  "market_ref":     { "id": "moneyline",        "numerical_id": 878, "label": "Moneyline" },
  "sportsbook_ref": { "id": "pinnacle",         "numerical_id":  28, "label": "Pinnacle" }
}

numerical_id semantics

Each numerical_id is allocated from a frozen, per-domain registry under api-adapters/sharp_atlas/. The contract is:

When fields are absent

The nested reference objects are emitted only when the underlying entity has been mapped in the atlas. For unmapped entities — typically long-tail leagues, exotic markets, or freshly added sportsbooks before catalog assignment — the corresponding *_ref block is omitted (or has numerical_id: null) and the existing string field on the row is the only ID you’ll see.

In practice:

• Major sports, leagues, and books are fully mapped — expect every *_ref block to be present.
• Player-prop markets and corners/cards/period markets in soccer have the broadest catalog; some niche prop types are still being assigned.
• Team abbreviation is populated where one is broadly known (US major leagues, EPL, ATP/WTA short codes). For minor / international teams it may be absent.

Consumers should treat every nested block as optional. Generic clients should fall back to the flat string field (sport, league, sportsbook, home_team, away_team, market_type) when the corresponding *_ref is not present.

Recommended usage

Indexing & joins

Use numerical_id as the primary key when storing odds/opportunities in your own database. Integer keys are smaller, cheaper to index, and stable across slug renames or display-label tweaks.

Cross-feed mapping

If you ingest from multiple data providers, numerical_id gives you a fast equality check inside SharpAPI rows. For mapping across vendors, the slug id (mlb, pinnacle, new_york_yankees) is still the more portable join key — slugs are human-readable and tend to overlap across vendors more than integer IDs do.

UI display

Use name (sports, teams) or label (leagues, markets, sportsbooks) for display; the abbreviation on home/away is appropriate for compact cells.

Streaming

The same nested objects appear on /api/v1/stream/odds SSE frames and on WebSocket v1 / v1.5 odds payloads — no separate stream is required.

Field reference

Reference endpoints

Every reference endpoint adds numerical_id to its existing object schema. /teams additionally adds abbreviation.

Nested reference blocks on odds & opportunity legs

All inner fields are optional within a block. A block may be present with a null numerical_id if the slug has been mapped but the integer assignment is pending; both numerical_id and the entire block may also be absent for unmapped entities.

Team metadata fields

The home / away blocks expose five additional optional metadata fields beyond id / numerical_id / name / abbreviation. They are sourced from the SharpAPI atlas and populated for the broad majority of teams (≈93% on logo, with comparable coverage on the rest):

Individual-sport competitors (tennis players, MMA fighters, golfers, drivers) generally have none of these fields populated — they are not “teams” in the conventional sense and inherit only id / numerical_id / name.

Migration

There is nothing to migrate. Continue using the flat string fields if they cover your needs. Adopt the *_ref blocks and numerical_id selectively when:

• you need a stable integer key for storage,
• you want display-ready labels without a second API call,
• or you’re building a cross-feed normalization layer.

The flat fields and the nested blocks describe the same row — they will not contradict each other.

Related

• Sports, Leagues, Sportsbooks, Markets, Teams — reference endpoints with the new numerical_id field
• Odds Snapshot, +EV Opportunities, Arbitrage, Middles — endpoints with nested reference blocks
• Event Matching — how SharpAPI joins the same fixture across books