diff --git a/content/en/api-reference/events-by-id.mdx b/content/en/api-reference/events-by-id.mdx index de81414..2b1fb5f 100644 --- a/content/en/api-reference/events-by-id.mdx +++ b/content/en/api-reference/events-by-id.mdx @@ -20,7 +20,7 @@ Requires API key via `X-API-Key` header, `Authorization: Bearer` header, or `api | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `eventId` | string | Yes | Unique event identifier (e.g., `evt_nba_bos_lal_20260208`) | +| `eventId` | string | Yes | Unique event identifier (e.g., `nba_celtics_lakers_2026-02-08_b3`) | ## Response Headers @@ -76,13 +76,13 @@ Each entry in the `markets` array summarizes an available market type for this e ```bash -curl -X GET "https://api.sharpapi.io/api/v1/events/evt_nba_bos_lal_20260208" \ +curl -X GET "https://api.sharpapi.io/api/v1/events/nba_celtics_lakers_2026-02-08_b3" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript -const eventId = 'evt_nba_bos_lal_20260208'; +const eventId = 'nba_celtics_lakers_2026-02-08_b3'; const response = await fetch( `https://api.sharpapi.io/api/v1/events/${eventId}`, { headers: { 'X-API-Key': 'YOUR_API_KEY' } } @@ -96,7 +96,7 @@ console.log(`Markets: ${data.markets.map(m => m.type).join(', ')}`); ```python import requests -event_id = 'evt_nba_bos_lal_20260208' +event_id = 'nba_celtics_lakers_2026-02-08_b3' response = requests.get( f'https://api.sharpapi.io/api/v1/events/{event_id}', headers={'X-API-Key': 'YOUR_API_KEY'} @@ -119,7 +119,7 @@ Single-resource responses wrap the object in `data` as a single object (not an a ```json { "data": { - "id": "evt_nba_bos_lal_20260208", + "id": "nba_celtics_lakers_2026-02-08_b3", "external_ids": { "draftkings": "12345678", "fanduel": "87654321", @@ -188,7 +188,7 @@ Single-resource responses wrap the object in `data` as a single object (not an a ] }, "meta": { - "event_id": "evt_nba_bos_lal_20260208" + "event_id": "nba_celtics_lakers_2026-02-08_b3" } } ``` diff --git a/content/en/api-reference/events-markets.mdx b/content/en/api-reference/events-markets.mdx index ec507bc..a7ea2d0 100644 --- a/content/en/api-reference/events-markets.mdx +++ b/content/en/api-reference/events-markets.mdx @@ -20,7 +20,7 @@ Requires API key via `X-API-Key` header, `Authorization: Bearer` header, or `api | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `eventId` | string | Yes | Unique event identifier (e.g., `evt_nba_bos_lal_20260208`) | +| `eventId` | string | Yes | Unique event identifier (e.g., `nba_celtics_lakers_2026-02-08_b3`) | ## Response Headers @@ -57,13 +57,13 @@ All responses include standard rate limit and metadata headers: ```bash -curl -X GET "https://api.sharpapi.io/api/v1/events/evt_nba_bos_lal_20260208/markets" \ +curl -X GET "https://api.sharpapi.io/api/v1/events/nba_celtics_lakers_2026-02-08_b3/markets" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript -const eventId = 'evt_nba_bos_lal_20260208'; +const eventId = 'nba_celtics_lakers_2026-02-08_b3'; const response = await fetch( `https://api.sharpapi.io/api/v1/events/${eventId}/markets`, { headers: { 'X-API-Key': 'YOUR_API_KEY' } } @@ -83,7 +83,7 @@ for (const market of data) { ```python import requests -event_id = 'evt_nba_bos_lal_20260208' +event_id = 'nba_celtics_lakers_2026-02-08_b3' response = requests.get( f'https://api.sharpapi.io/api/v1/events/{event_id}/markets', headers={'X-API-Key': 'YOUR_API_KEY'} @@ -158,7 +158,7 @@ for market in result['data']: } ], "meta": { - "event_id": "evt_nba_bos_lal_20260208", + "event_id": "nba_celtics_lakers_2026-02-08_b3", "count": 5, "updated_at": "2026-02-08T12:05:00Z" } diff --git a/content/en/api-reference/events-odds.mdx b/content/en/api-reference/events-odds.mdx index 0c43308..2d2d4fa 100644 --- a/content/en/api-reference/events-odds.mdx +++ b/content/en/api-reference/events-odds.mdx @@ -24,7 +24,7 @@ Requires API key via `X-API-Key` header, `Authorization: Bearer` header, or `api | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `eventId` | string | Yes | Unique event identifier (e.g., `evt_nba_bos_lal_20260208`) | +| `eventId` | string | Yes | Unique event identifier (e.g., `nba_celtics_lakers_2026-02-08_b3`) | ## Query Parameters @@ -71,13 +71,13 @@ All responses include standard rate limit and metadata headers: ```bash -curl -X GET "https://api.sharpapi.io/api/v1/events/evt_nba_bos_lal_20260208/odds" \ +curl -X GET "https://api.sharpapi.io/api/v1/events/nba_celtics_lakers_2026-02-08_b3/odds" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript -const eventId = 'evt_nba_bos_lal_20260208'; +const eventId = 'nba_celtics_lakers_2026-02-08_b3'; const response = await fetch( `https://api.sharpapi.io/api/v1/events/${eventId}/odds`, { headers: { 'X-API-Key': 'YOUR_API_KEY' } } @@ -90,7 +90,7 @@ console.log(`${meta.total} total odds for this event`); ```python import requests -event_id = 'evt_nba_bos_lal_20260208' +event_id = 'nba_celtics_lakers_2026-02-08_b3' response = requests.get( f'https://api.sharpapi.io/api/v1/events/{event_id}/odds', headers={'X-API-Key': 'YOUR_API_KEY'} @@ -106,13 +106,13 @@ print(f"{result['meta']['total']} total odds for this event") ```bash -curl -X GET "https://api.sharpapi.io/api/v1/events/evt_nba_bos_lal_20260208/odds?sportsbook=draftkings,pinnacle&market=moneyline,spread" \ +curl -X GET "https://api.sharpapi.io/api/v1/events/nba_celtics_lakers_2026-02-08_b3/odds?sportsbook=draftkings,pinnacle&market=moneyline,spread" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript -const eventId = 'evt_nba_bos_lal_20260208'; +const eventId = 'nba_celtics_lakers_2026-02-08_b3'; const response = await fetch( `https://api.sharpapi.io/api/v1/events/${eventId}/odds?sportsbook=draftkings,pinnacle&market=moneyline,spread`, { headers: { 'X-API-Key': 'YOUR_API_KEY' } } @@ -124,7 +124,7 @@ const { data } = await response.json(); ```python import requests -event_id = 'evt_nba_bos_lal_20260208' +event_id = 'nba_celtics_lakers_2026-02-08_b3' response = requests.get( f'https://api.sharpapi.io/api/v1/events/{event_id}/odds', params={ @@ -144,17 +144,17 @@ odds = response.json()['data'] ```bash # First page -curl -X GET "https://api.sharpapi.io/api/v1/events/evt_nba_bos_lal_20260208/odds?limit=50&offset=0" \ +curl -X GET "https://api.sharpapi.io/api/v1/events/nba_celtics_lakers_2026-02-08_b3/odds?limit=50&offset=0" \ -H "X-API-Key: YOUR_API_KEY" # Next page -curl -X GET "https://api.sharpapi.io/api/v1/events/evt_nba_bos_lal_20260208/odds?limit=50&offset=50" \ +curl -X GET "https://api.sharpapi.io/api/v1/events/nba_celtics_lakers_2026-02-08_b3/odds?limit=50&offset=50" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript -const eventId = 'evt_nba_bos_lal_20260208'; +const eventId = 'nba_celtics_lakers_2026-02-08_b3'; let offset = 0; const limit = 50; let allOdds = []; @@ -178,7 +178,7 @@ console.log(`Fetched all ${allOdds.length} odds`); ```python import requests -event_id = 'evt_nba_bos_lal_20260208' +event_id = 'nba_celtics_lakers_2026-02-08_b3' all_odds = [] offset = 0 limit = 50 @@ -209,9 +209,9 @@ print(f"Fetched all {len(all_odds)} odds") { "data": [ { - "id": "dk_evt_nba_bos_lal_20260208_ml_home", + "id": "dk_nba_celtics_lakers_2026-02-08_b3_ml_home", "sportsbook": "draftkings", - "event_id": "evt_nba_bos_lal_20260208", + "event_id": "nba_celtics_lakers_2026-02-08_b3", "market_type": "moneyline", "selection": "Boston Celtics", "selection_type": "home", @@ -224,9 +224,9 @@ print(f"Fetched all {len(all_odds)} odds") "last_seen_at": "2026-02-08T12:05:00Z" }, { - "id": "dk_evt_nba_bos_lal_20260208_ml_away", + "id": "dk_nba_celtics_lakers_2026-02-08_b3_ml_away", "sportsbook": "draftkings", - "event_id": "evt_nba_bos_lal_20260208", + "event_id": "nba_celtics_lakers_2026-02-08_b3", "market_type": "moneyline", "selection": "Los Angeles Lakers", "selection_type": "away", @@ -239,9 +239,9 @@ print(f"Fetched all {len(all_odds)} odds") "last_seen_at": "2026-02-08T12:05:00Z" }, { - "id": "pin_evt_nba_bos_lal_20260208_ml_home", + "id": "pin_nba_celtics_lakers_2026-02-08_b3_ml_home", "sportsbook": "pinnacle", - "event_id": "evt_nba_bos_lal_20260208", + "event_id": "nba_celtics_lakers_2026-02-08_b3", "market_type": "moneyline", "selection": "Boston Celtics", "selection_type": "home", @@ -254,9 +254,9 @@ print(f"Fetched all {len(all_odds)} odds") "last_seen_at": "2026-02-08T12:03:00Z" }, { - "id": "dk_evt_nba_bos_lal_20260208_spread_home", + "id": "dk_nba_celtics_lakers_2026-02-08_b3_spread_home", "sportsbook": "draftkings", - "event_id": "evt_nba_bos_lal_20260208", + "event_id": "nba_celtics_lakers_2026-02-08_b3", "market_type": "spread", "selection": "Boston Celtics", "selection_type": "home", @@ -269,9 +269,9 @@ print(f"Fetched all {len(all_odds)} odds") "last_seen_at": "2026-02-08T12:05:00Z" }, { - "id": "dk_evt_nba_bos_lal_20260208_total_over", + "id": "dk_nba_celtics_lakers_2026-02-08_b3_total_over", "sportsbook": "draftkings", - "event_id": "evt_nba_bos_lal_20260208", + "event_id": "nba_celtics_lakers_2026-02-08_b3", "market_type": "total", "selection": "Over", "selection_type": "over", diff --git a/content/en/api-reference/events.mdx b/content/en/api-reference/events.mdx index 62e66d8..ae4e43b 100644 --- a/content/en/api-reference/events.mdx +++ b/content/en/api-reference/events.mdx @@ -233,7 +233,7 @@ data = response.json() { "data": [ { - "id": "evt_nba_bos_lal_20260208", + "id": "nba_celtics_lakers_2026-02-08_b3", "external_ids": { "draftkings": "33483200", "fanduel": "nba-bos-lal-20260208" @@ -250,7 +250,7 @@ data = response.json() "books": ["betmgm", "caesars", "draftkings", "fanduel"] }, { - "id": "evt_nba_gsw_mia_20260208", + "id": "nba_heat_warriors_2026-02-08_b3", "external_ids": { "draftkings": "33483205" }, diff --git a/content/en/api-reference/historical-odds-closing.mdx b/content/en/api-reference/historical-odds-closing.mdx index 5c04bb0..6db16fa 100644 --- a/content/en/api-reference/historical-odds-closing.mdx +++ b/content/en/api-reference/historical-odds-closing.mdx @@ -114,7 +114,7 @@ for event in data['events']: "league": "nba", "events": [ { - "event_id": "evt_nba_bos_mia_20260410", + "event_id": "nba_celtics_heat_2026-04-10_b3", "sport": "basketball", "league": "nba", "home_team": "Boston Celtics", diff --git a/content/en/api-reference/odds-batch.mdx b/content/en/api-reference/odds-batch.mdx index 49e20c9..c77b115 100644 --- a/content/en/api-reference/odds-batch.mdx +++ b/content/en/api-reference/odds-batch.mdx @@ -51,7 +51,7 @@ curl -X POST "https://api.sharpapi.io/api/v1/odds/batch" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ - "event_ids": ["evt_nba_lal_bos_20260126", "evt_nba_gsw_mia_20260126"], + "event_ids": ["nba_celtics_lakers_2026-01-26_b3", "nba_heat_warriors_2026-01-26_b3"], "sportsbook": "draftkings", "market": "moneyline" }' @@ -66,7 +66,7 @@ const response = await fetch('https://api.sharpapi.io/api/v1/odds/batch', { 'Content-Type': 'application/json' }, body: JSON.stringify({ - event_ids: ['evt_nba_lal_bos_20260126', 'evt_nba_gsw_mia_20260126'], + event_ids: ['nba_celtics_lakers_2026-01-26_b3', 'nba_heat_warriors_2026-01-26_b3'], sportsbook: 'draftkings', market: 'moneyline' }) @@ -96,7 +96,7 @@ response = requests.post( 'Content-Type': 'application/json' }, json={ - 'event_ids': ['evt_nba_lal_bos_20260126', 'evt_nba_gsw_mia_20260126'], + 'event_ids': ['nba_celtics_lakers_2026-01-26_b3', 'nba_heat_warriors_2026-01-26_b3'], 'sportsbook': 'draftkings', 'market': 'moneyline' } @@ -125,7 +125,7 @@ if result['data']['missing_events']: "data": { "events": [ { - "event_id": "evt_nba_lal_bos_20260126", + "event_id": "nba_celtics_lakers_2026-01-26_b3", "event_name": "Los Angeles Lakers @ Boston Celtics", "sport": "basketball", "league": "nba", @@ -155,7 +155,7 @@ if result['data']['missing_events']: ] }, { - "event_id": "evt_nba_gsw_mia_20260126", + "event_id": "nba_heat_warriors_2026-01-26_b3", "event_name": "Golden State Warriors @ Miami Heat", "sport": "basketball", "league": "nba", diff --git a/content/en/api-reference/odds-best.mdx b/content/en/api-reference/odds-best.mdx index b628663..f0b7aaf 100644 --- a/content/en/api-reference/odds-best.mdx +++ b/content/en/api-reference/odds-best.mdx @@ -92,7 +92,7 @@ for item in result['data']: "success": true, "data": [ { - "event_id": "evt_nba_lal_bos_20260126", + "event_id": "nba_celtics_lakers_2026-01-26_b3", "event_name": "Los Angeles Lakers @ Boston Celtics", "sport": "basketball", "league": "nba", diff --git a/content/en/api-reference/opportunities-arbitrage.mdx b/content/en/api-reference/opportunities-arbitrage.mdx index 505b6b3..60e4d06 100644 --- a/content/en/api-reference/opportunities-arbitrage.mdx +++ b/content/en/api-reference/opportunities-arbitrage.mdx @@ -100,7 +100,7 @@ for arb in data['data']: "data": [ { "id": "arb_dk_pin_nba_lal_bos_ml", - "event_id": "evt_nba_lal_bos_20260208", + "event_id": "nba_celtics_lakers_2026-02-08_b3", "event_name": "Los Angeles Lakers @ Boston Celtics", "sport": "basketball", "league": "nba", diff --git a/content/en/api-reference/opportunities-ev.mdx b/content/en/api-reference/opportunities-ev.mdx index 77e9292..2c18e7f 100644 --- a/content/en/api-reference/opportunities-ev.mdx +++ b/content/en/api-reference/opportunities-ev.mdx @@ -120,7 +120,7 @@ for opp in data['data']: "data": [ { "id": "ev_dk_nba_33483153_ml_PHO", - "game_id": "evt_nba_phi_pho_20260208", + "game_id": "nba_76ers_suns_2026-02-08_b3", "ev_percentage": 4.2, "odds_american": -105, "odds_decimal": 1.952, @@ -155,7 +155,7 @@ for opp in data['data']: }, { "id": "ev_fd_nba_33483153_ml_PHO", - "game_id": "evt_nba_phi_pho_20260208", + "game_id": "nba_76ers_suns_2026-02-08_b3", "ev_percentage": 2.8, "odds_american": -108, "odds_decimal": 1.926, diff --git a/content/en/api-reference/opportunities-low-hold.mdx b/content/en/api-reference/opportunities-low-hold.mdx index f4b9e34..12af572 100644 --- a/content/en/api-reference/opportunities-low-hold.mdx +++ b/content/en/api-reference/opportunities-low-hold.mdx @@ -102,7 +102,7 @@ for hold in data['data']: "data": [ { "id": "lh_nba_lal_bos_ml_0", - "event_id": "evt_nba_lal_bos_20260208", + "event_id": "nba_celtics_lakers_2026-02-08_b3", "event_name": "Los Angeles Lakers @ Boston Celtics", "sport": "basketball", "league": "nba", diff --git a/content/en/api-reference/opportunities-middles.mdx b/content/en/api-reference/opportunities-middles.mdx index 9e303ec..2d7f207 100644 --- a/content/en/api-reference/opportunities-middles.mdx +++ b/content/en/api-reference/opportunities-middles.mdx @@ -92,7 +92,7 @@ for middle in data['data']: "data": [ { "id": "a1b2c3d4e5f67890", - "event_id": "evt_nfl_buf_kc_20260217", + "event_id": "nfl_bills_chiefs_2026-02-17_b2", "event_name": "Buffalo Bills @ Kansas City Chiefs", "sport": "football", "league": "nfl", diff --git a/content/en/api-reference/overview.mdx b/content/en/api-reference/overview.mdx index 28d20ea..01fe05d 100644 --- a/content/en/api-reference/overview.mdx +++ b/content/en/api-reference/overview.mdx @@ -168,7 +168,7 @@ Used for singletons (`/account`, `/events/:eventId`) and non-paginated reference ```json { "data": { - "id": "evt_abc123", + "id": "nba_celtics_lakers_2026-02-08_b3", "sport": "nba", "home_team": "PHI 76ers", "away_team": "PHO Suns", @@ -278,7 +278,7 @@ All list endpoints support filtering via query parameters. Filters use **singula | `sport` | string | `basketball,football` | Filter by sport | | `league` | string | `nba,nfl` | Filter by league | | `market` | string | `moneyline,spread` | Filter by market type | -| `event` | string | `evt_abc123` | Filter by event ID | +| `event` | string | `nba_celtics_lakers_2026-02-08_b3` | Filter by event ID | | `live` | boolean | `true` | Only live/in-progress events | | `sort` | string | `-odds_american` | Sort field with optional `-` prefix for descending | | `fields` | string | `id,sportsbook,odds_american` | Comma-separated fields to include in response | diff --git a/content/en/api-reference/stream.mdx b/content/en/api-reference/stream.mdx index b4e835f..7fa92dc 100644 --- a/content/en/api-reference/stream.mdx +++ b/content/en/api-reference/stream.mdx @@ -180,7 +180,7 @@ A previously detected arbitrage opportunity is no longer available. ``` event: arb:expired id: evt_00046 -data: {"expired":["evt_abc123:moneyline:opp_a1b2c3"],"timestamp":"2026-01-26T02:10:39.500Z"} +data: {"expired":["nba_celtics_lakers_2026-02-08_b3:moneyline:opp_a1b2c3"],"timestamp":"2026-01-26T02:10:39.500Z"} ``` ### `middles:detected` diff --git a/content/en/concepts/event-matching.mdx b/content/en/concepts/event-matching.mdx index 280c699..fb8eb55 100644 --- a/content/en/concepts/event-matching.mdx +++ b/content/en/concepts/event-matching.mdx @@ -1,5 +1,5 @@ --- -description: "How SharpAPI matches identical events across 32 sportsbooks using canonical event IDs. Solves the problem of different sportsbook-specific event naming and identifiers." +description: "How SharpAPI matches identical events across 32 sportsbooks using canonical event IDs. Explains the canonical-ID format including the 6-hour start-time bucket suffix and how live and pre-match odds share the same event ID." --- # Event Matching @@ -13,17 +13,19 @@ Each sportsbook uses its own internal event IDs. The same Lakers vs Celtics game SharpAPI generates a **canonical event ID** for every event. This ID is deterministic — the same real-world event always gets the same `id`, regardless of which sportsbook it comes from. ``` -Format: {league}_{teamA}_{teamB}_{YYYY-MM-DD} +Format: {league}_{teamA}_{teamB}_{YYYY-MM-DD}_b{N} ``` +The trailing `_b{N}` is a 6-hour start-time bucket — see [Start-time bucket suffix](#start-time-bucket-suffix-_bn) below. + **Example:** A Celtics vs Lakers game on February 8, 2026 produces the same ID across all sportsbooks: | Sportsbook | Native Event ID | SharpAPI `id` | |------------|----------------|---------------| -| DraftKings | `33483200` | `nba_celtics_lakers_20260208` | -| FanDuel | `nba-bos-lal-20260208` | `nba_celtics_lakers_20260208` | -| Pinnacle | `556677889` | `nba_celtics_lakers_20260208` | -| BetMGM | `ms_44556` | `nba_celtics_lakers_20260208` | +| DraftKings | `33483200` | `nba_celtics_lakers_2026-02-08_b3` | +| FanDuel | `nba-bos-lal-20260208` | `nba_celtics_lakers_2026-02-08_b3` | +| Pinnacle | `556677889` | `nba_celtics_lakers_2026-02-08_b3` | +| BetMGM | `ms_44556` | `nba_celtics_lakers_2026-02-08_b3` | ## Two Types of Event IDs @@ -36,7 +38,7 @@ Every event in the API has two ID fields: ```json { - "id": "nba_celtics_lakers_20260208", + "id": "nba_celtics_lakers_2026-02-08_b3", "external_ids": { "draftkings": "33483200", "fanduel": "nba-bos-lal-20260208", @@ -53,6 +55,7 @@ The canonical ID is built from four components: 1. **League code** — sport mapped to league (e.g., `basketball` → `nba`) 2. **Team names** — normalized and alphabetically sorted 3. **Date** — event start date in `YYYY-MM-DD` format +4. **Start-time bucket** — `_b{N}` suffix where `N` is in `0..3` ### Team Name Normalization @@ -64,6 +67,50 @@ Team names are normalized to handle variations across sportsbooks: Normalization strips prefixes ("The", "Los", "Las"), suffixes ("FC", "United", "City"), punctuation, and accents. Teams are then sorted alphabetically so the ID is identical regardless of home/away ordering. +### Start-time bucket suffix (`_b{N}`) + +The `_b{N}` suffix is a 6-hour start-time bucket. `N` is in `0..3`: + +| Bucket | Hour range | +|--------|------------| +| `_b0` | `00:00`–`05:59` | +| `_b1` | `06:00`–`11:59` | +| `_b2` | `12:00`–`17:59` | +| `_b3` | `18:00`–`23:59` | + +For US-league sports (NBA, NFL, NHL, MLB, NCAAB, NCAAF, WNBA, NCAAW) the bucket is anchored to **Eastern Time** so a 7:30 PM ET tip-off lands in `_b3` regardless of how books stamp their UTC offsets. For all other sports (soccer, tennis, cricket, etc.) the bucket is anchored to **UTC**. + +**Why this exists.** Same matchup, same calendar date, different real-world fixtures are possible: + +- An MLB doubleheader with two games on the same day. +- A US-evening MLB game UTC-stamped onto the next calendar day, plus a real next-day rematch UTC-stamped onto the same date. + +Without the bucket, both fixtures would collide on one ID and odds would be mixed. With it, the two games land on different `_bN` suffixes and stay separate. + +**What this means for cross-book matching.** Inside one fixture, every book that reports a start time within the same 6-hour window converges on the same `_b{N}`. Across a bucket boundary — for example, one book stamps a soccer kick-off at 17:55 UTC (`_b2`) and another at 18:10 UTC (`_b3`) — books can fragment across two canonical IDs. This is a known limitation. If you observe this, file a ticket with the event details. + +## Live vs Pre-Match Share The Same Event ID + +A given fixture has **one canonical event ID** that covers both pre-match and live (in-play) odds. The `is_live` field on each odds row tells you which state the price was collected in: + +```json +{ + "event_id": "nba_celtics_lakers_2026-02-08_b3", + "sportsbook": "pinnacle", + "market_type": "moneyline", + "is_live": false, + "odds_american": -140 +} +``` + +When the game tips off, new odds for the same fixture flow in under the same `event_id` with `is_live: true`. To get the live snapshot for a specific game, filter on both: + +```bash +GET /api/v1/odds?event_id=nba_celtics_lakers_2026-02-08_b3&live=true +``` + +See [Live vs Pre-Match Odds](/en/concepts/live-vs-prematch/) for the per-book quality picture during live play. + ## Using Canonical IDs in Your Application ### As a Primary Key @@ -80,7 +127,7 @@ const { data: events } = await fetch( // Store using canonical ID as primary key for (const event of events) { await db.events.upsert({ - id: event.id, // "nba_celtics_lakers_20260208" + 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, @@ -96,7 +143,7 @@ The canonical ID lets you compare odds for the same event across all books: ```javascript // Get odds filtered to a specific event const { data } = await fetch( - 'https://api.sharpapi.io/api/v1/events/nba_celtics_lakers_20260208/odds', + '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()); @@ -114,7 +161,7 @@ for (const odds of data.odds) { Use `external_ids` to link users back to a specific sportsbook's event page: ```javascript -const event = await getEvent('nba_celtics_lakers_20260208'); +const event = await getEvent('nba_celtics_lakers_2026-02-08_b3'); // Build a sportsbook-specific link const dkEventId = event.external_ids['draftkings']; @@ -137,5 +184,6 @@ This is the same matching system exposed to you through the API — when you see |----------|--------| | **Deterministic** | Same inputs always produce the same ID — no random UUIDs | | **Stable** | The ID doesn't change once generated | -| **Human-readable** | `nba_celtics_lakers_20260208` is meaningful at a glance | +| **Human-readable** | `nba_celtics_lakers_2026-02-08_b3` is meaningful at a glance | | **Sortable** | IDs sort naturally by league, team, and date | +| **No prefix** | Canonical IDs do **not** carry an `evt_` prefix. Treat the ID as an opaque string and pass it through unchanged when calling the API. | diff --git a/content/en/sdks/python.mdx b/content/en/sdks/python.mdx index 208a58a..d7b6b98 100644 --- a/content/en/sdks/python.mdx +++ b/content/en/sdks/python.mdx @@ -61,10 +61,10 @@ client.odds.get(sport="basketball", league="nba", limit=100) client.odds.best(league="nfl", market="moneyline") # Side-by-side comparison for an event -client.odds.comparison(event_id="evt_abc123") +client.odds.comparison(event_id="nba_celtics_lakers_2026-02-08_b3") # Batch lookup -client.odds.batch(event_ids=["evt_abc123", "evt_def456"]) +client.odds.batch(event_ids=["nba_celtics_lakers_2026-02-08_b3", "nfl_bills_chiefs_2026-02-17_b2"]) ``` ### +EV Opportunities (Pro+) @@ -248,7 +248,7 @@ client.stream.opportunities(min_ev=3.0) client.stream.all(sport="basketball") # Single event -client.stream.event("evt_abc123") +client.stream.event("nba_celtics_lakers_2026-02-08_b3") ``` ## Data Quality diff --git a/content/en/streaming/single-connection.mdx b/content/en/streaming/single-connection.mdx index 8447c96..aa8a339 100644 --- a/content/en/streaming/single-connection.mdx +++ b/content/en/streaming/single-connection.mdx @@ -22,7 +22,7 @@ Every identity filter on the stream endpoint accepts a **comma-separated list**, | `league` | `league=nba` | `league=nba,nfl,mlb,nhl` | | `sportsbook` | `sportsbook=draftkings` | `sportsbook=draftkings,fanduel,pinnacle` | | `market` | `market=moneyline` | `market=moneyline,point_spread,total_points` | -| `event` | `event=evt_abc` | `event=evt_abc,evt_def,evt_ghi` | +| `event` | `event=nba_celtics_lakers_2026-02-08_b3` | `event=nba_celtics_lakers_2026-02-08_b3,nfl_bills_chiefs_2026-02-17_b2,mlb_red_sox_yankees_2026-04-10_b0` | | `channel` (SSE) | `channel=odds` | `channel=all` (odds + opportunities) | | `channels` (WS) | `channels=ev` | `channels=ev,odds,arbitrage,middles,low_hold` |