odds-api-io 1.3.1 → 1.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +325 -244
- package/dist/cjs/client.d.ts +278 -0
- package/dist/cjs/client.js +536 -292
- package/dist/cjs/client.js.map +1 -1
- package/dist/cjs/errors.d.ts +63 -0
- package/dist/cjs/errors.js +54 -36
- package/dist/cjs/errors.js.map +1 -1
- package/dist/cjs/helpers.d.ts +5 -0
- package/dist/cjs/helpers.js +13 -0
- package/dist/cjs/helpers.js.map +1 -0
- package/dist/cjs/index.d.ts +15 -0
- package/dist/cjs/index.js +15 -3
- package/dist/cjs/index.js.map +1 -1
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/types.d.ts +770 -0
- package/dist/cjs/types.js +4 -1
- package/dist/cjs/types.js.map +1 -1
- package/dist/cjs/version.d.ts +1 -0
- package/dist/cjs/version.js +5 -0
- package/dist/cjs/version.js.map +1 -0
- package/dist/cjs/websocket.d.ts +210 -0
- package/dist/cjs/websocket.js +405 -0
- package/dist/cjs/websocket.js.map +1 -0
- package/dist/esm/client.d.ts +278 -0
- package/dist/esm/client.js +537 -293
- package/dist/esm/client.js.map +1 -1
- package/dist/esm/errors.d.ts +63 -0
- package/dist/esm/errors.js +49 -34
- package/dist/esm/errors.js.map +1 -1
- package/dist/esm/helpers.d.ts +5 -0
- package/dist/esm/helpers.js +9 -0
- package/dist/esm/helpers.js.map +1 -0
- package/dist/esm/index.d.ts +15 -0
- package/dist/esm/index.js +5 -2
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/package.json +1 -0
- package/dist/esm/types.d.ts +770 -0
- package/dist/esm/types.js +4 -1
- package/dist/esm/types.js.map +1 -1
- package/dist/esm/version.d.ts +1 -0
- package/dist/esm/version.js +2 -0
- package/dist/esm/version.js.map +1 -0
- package/dist/esm/websocket.d.ts +210 -0
- package/dist/esm/websocket.js +367 -0
- package/dist/esm/websocket.js.map +1 -0
- package/dist/types/client.d.ts +155 -195
- package/dist/types/client.d.ts.map +1 -1
- package/dist/types/errors.d.ts +48 -24
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/helpers.d.ts +6 -0
- package/dist/types/helpers.d.ts.map +1 -0
- package/dist/types/index.d.ts +8 -3
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/types.d.ts +659 -187
- package/dist/types/types.d.ts.map +1 -1
- package/dist/types/version.d.ts +2 -0
- package/dist/types/version.d.ts.map +1 -0
- package/dist/types/websocket.d.ts +211 -0
- package/dist/types/websocket.d.ts.map +1 -0
- package/package.json +46 -16
package/README.md
CHANGED
|
@@ -7,291 +7,378 @@
|
|
|
7
7
|
[](https://www.typescriptlang.org/)
|
|
8
8
|
[](https://nodejs.org)
|
|
9
9
|
|
|
10
|
-
Official Node.js SDK for [**Odds-API.io**](https://odds-api.io)
|
|
10
|
+
Official Node.js and TypeScript SDK for the [**Odds-API.io**](https://odds-api.io) sports betting odds API: real-time and pre-match odds from 450+ bookmakers across 34 sports, over REST and WebSocket.
|
|
11
11
|
|
|
12
|
-
Building with AI? See the [AI and vibe coding guide](https://docs.odds-api.io/ai-vibe-coding). Prefer Python? Check out the [Python SDK](https://github.com/odds-api-io/odds-api-python).
|
|
12
|
+
Building with AI? See the [AI and vibe coding guide](https://docs.odds-api.io/ai-vibe-coding). Prefer Python? Check out the [Python SDK](https://github.com/odds-api-io/odds-api-python). Prefer the terminal? Try the [CLI](https://github.com/odds-api-io/odds-api-cli).
|
|
13
13
|
|
|
14
|
-
##
|
|
14
|
+
## Quickstart
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
- 📊 **Comprehensive Odds Data** - Real-time odds from 450+ bookmakers
|
|
18
|
-
- 💰 **Arbitrage Detection** - Find risk-free betting opportunities
|
|
19
|
-
- 📈 **Value Bets** - Identify positive expected value bets
|
|
20
|
-
- 📉 **Dropping Odds** - Track sharp bookmaker line movements
|
|
21
|
-
- 🔴 **Live Events** - Track in-play events and odds
|
|
22
|
-
- 🔍 **Advanced Search** - Search events, participants, and leagues
|
|
23
|
-
- ⚡ **TypeScript First** - Full type safety with TypeScript
|
|
24
|
-
- 📦 **Dual Package** - Works with both ESM and CommonJS
|
|
25
|
-
- 🛡️ **Error Handling** - Custom error classes for better debugging
|
|
26
|
-
|
|
27
|
-
## Installation
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
npm install odds-api-io
|
|
31
|
-
```
|
|
16
|
+
1. Install:
|
|
32
17
|
|
|
33
|
-
|
|
18
|
+
```bash
|
|
19
|
+
npm install odds-api-io
|
|
20
|
+
```
|
|
34
21
|
|
|
35
|
-
|
|
22
|
+
2. Set your API key ([get one here](https://odds-api.io/pricing?ref=npm)):
|
|
36
23
|
|
|
37
|
-
|
|
24
|
+
```bash
|
|
25
|
+
export ODDS_API_KEY="your-api-key"
|
|
26
|
+
```
|
|
38
27
|
|
|
39
|
-
|
|
28
|
+
3. Make your first request:
|
|
40
29
|
|
|
41
|
-
```typescript
|
|
42
|
-
import { OddsAPIClient } from 'odds-api-io';
|
|
30
|
+
```typescript
|
|
31
|
+
import { OddsAPIClient } from 'odds-api-io';
|
|
43
32
|
|
|
44
|
-
const client = new OddsAPIClient({
|
|
45
|
-
apiKey: 'your-api-key-here'
|
|
46
|
-
});
|
|
33
|
+
const client = new OddsAPIClient({ apiKey: process.env.ODDS_API_KEY! });
|
|
47
34
|
|
|
48
|
-
|
|
49
|
-
const
|
|
50
|
-
console.log(
|
|
35
|
+
const events = await client.getEvents({ sport: 'football', league: 'england-premier-league' });
|
|
36
|
+
const odds = await client.getEventOdds({ eventId: String(events[0].id), bookmakers: 'Bet365,Unibet' });
|
|
37
|
+
console.log(odds);
|
|
38
|
+
```
|
|
51
39
|
|
|
52
|
-
|
|
53
|
-
const events = await client.getEvents({
|
|
54
|
-
sport: 'basketball',
|
|
55
|
-
league: 'usa-nba'
|
|
56
|
-
});
|
|
40
|
+
## Get an API key
|
|
57
41
|
|
|
58
|
-
|
|
59
|
-
const lakersGames = await client.searchEvents('Lakers');
|
|
42
|
+
The odds API needs a key from a paid plan. Pick a plan at [**odds-api.io/pricing**](https://odds-api.io/pricing?ref=npm). Rate limits, the number of bookmakers you can select and WebSocket access depend on the plan.
|
|
60
43
|
|
|
61
|
-
|
|
62
|
-
const liveEvents = await client.getLiveEvents('basketball');
|
|
63
|
-
```
|
|
44
|
+
## Sports and bookmakers
|
|
64
45
|
|
|
65
|
-
|
|
46
|
+
| Sport | Example leagues |
|
|
47
|
+
|-------|-----------------|
|
|
48
|
+
| Football (soccer) | Premier League, La Liga, Champions League |
|
|
49
|
+
| Basketball | NBA, EuroLeague |
|
|
50
|
+
| American football | NFL, NCAAF |
|
|
51
|
+
| Baseball | MLB |
|
|
52
|
+
| Ice hockey | NHL |
|
|
53
|
+
| Tennis | ATP, WTA |
|
|
54
|
+
| Esports | CS2, League of Legends, Dota 2 |
|
|
55
|
+
| ...and 27 more | 34 sports in total |
|
|
66
56
|
|
|
67
|
-
|
|
68
|
-
const { OddsAPIClient } = require('odds-api-io');
|
|
57
|
+
Odds come from **450+ bookmakers**, including Bet365, DraftKings, FanDuel, Betfair, Unibet and SingBet. See the [full coverage list](https://odds-api.io/sportsbooks#coverage).
|
|
69
58
|
|
|
70
|
-
|
|
71
|
-
apiKey: 'your-api-key-here'
|
|
72
|
-
});
|
|
59
|
+
## Documentation
|
|
73
60
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
league: 'usa-nba'
|
|
78
|
-
});
|
|
79
|
-
|
|
80
|
-
const odds = await client.getEventOdds({
|
|
81
|
-
eventId: events[0].id,
|
|
82
|
-
bookmakers: 'singbet,bet365'
|
|
83
|
-
});
|
|
84
|
-
|
|
85
|
-
console.log(odds);
|
|
86
|
-
}
|
|
61
|
+
- [API documentation](https://docs.odds-api.io/)
|
|
62
|
+
- [API reference](https://docs.odds-api.io/api-reference)
|
|
63
|
+
- [AI and vibe coding guide](https://docs.odds-api.io/ai-vibe-coding)
|
|
87
64
|
|
|
88
|
-
|
|
89
|
-
```
|
|
65
|
+
## Features
|
|
90
66
|
|
|
91
|
-
|
|
67
|
+
- REST client for every public v3 endpoint: events, odds, odds summary, movements, value bets, arbitrage, dropping odds, historical odds and closing lines, settlement and grading, golf outrights, participants, bookmaker mappings
|
|
68
|
+
- `OddsWebSocket`: real-time odds, scores and status with reconnects that resume from the last `seq`
|
|
69
|
+
- Async iterators for paginated endpoints (`iterateEvents`, `iterateClosingLines`, `iterateMappings`, `iterateDroppingOdds`, `iterateHistoricalEvents`) and `pollUpdatedOdds` for the `/odds/updated` delta
|
|
70
|
+
- Types that match the responses, including the period score keys (`p1`..`pN`, `ft`, `ot`, `ap`)
|
|
71
|
+
- Error classes that keep the server's message, with `retryAfter` on rate limits and optional retries with backoff
|
|
72
|
+
- ESM and CommonJS, Node.js 18+
|
|
92
73
|
|
|
93
|
-
|
|
74
|
+
## Usage
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
94
77
|
import { OddsAPIClient } from 'odds-api-io';
|
|
95
78
|
|
|
96
|
-
const client = new OddsAPIClient({
|
|
97
|
-
|
|
79
|
+
const client = new OddsAPIClient({ apiKey: process.env.ODDS_API_KEY! });
|
|
80
|
+
|
|
81
|
+
// Exact market names for a sport (no key needed)
|
|
82
|
+
const { markets } = await client.getMarkets('football');
|
|
83
|
+
|
|
84
|
+
// Upcoming and live Premier League matches
|
|
85
|
+
const events = await client.getEvents({
|
|
86
|
+
sport: 'football',
|
|
87
|
+
league: 'england-premier-league',
|
|
88
|
+
status: ['pending', 'live'],
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
// Odds for one match. Pass `markets` to keep responses small.
|
|
92
|
+
const odds = await client.getEventOdds({
|
|
93
|
+
eventId: events[0].id,
|
|
94
|
+
bookmakers: ['Bet365', 'SingBet'],
|
|
95
|
+
markets: ['ML', 'Spread', 'Totals'],
|
|
98
96
|
});
|
|
97
|
+
for (const [bookmaker, bookMarkets] of Object.entries(odds.bookmakers)) {
|
|
98
|
+
const ml = bookMarkets.find((m) => m.name === 'ML');
|
|
99
|
+
console.log(bookmaker, ml?.odds[0]); // { home: '2.10', draw: '3.40', away: '3.20' }
|
|
100
|
+
}
|
|
99
101
|
|
|
100
|
-
|
|
102
|
+
// Search, including in-play matches
|
|
103
|
+
const live = await client.searchEvents('Liverpool', { status: 'live' });
|
|
101
104
|
```
|
|
102
105
|
|
|
103
|
-
|
|
106
|
+
CommonJS works the same way:
|
|
104
107
|
|
|
105
|
-
|
|
108
|
+
```javascript
|
|
109
|
+
const { OddsAPIClient } = require('odds-api-io');
|
|
110
|
+
```
|
|
106
111
|
|
|
107
|
-
|
|
108
|
-
import { OddsAPIClient } from 'odds-api-io';
|
|
112
|
+
Comma-separated parameters (`bookmakers`, `markets`, `eventIds`, `leagues`, `status`) accept either a string (`'Bet365,SingBet'`) or an array.
|
|
109
113
|
|
|
110
|
-
|
|
114
|
+
Market names must match in full: there is no `Match Winner` (use `ML`) and no bare `Over/Under`. Call `getMarkets(sport)` to see the names a sport serves.
|
|
111
115
|
|
|
112
|
-
|
|
113
|
-
bookmakers: 'singbet,bet365',
|
|
114
|
-
limit: 10,
|
|
115
|
-
includeEventDetails: true
|
|
116
|
-
});
|
|
116
|
+
## Odds comparison and summary
|
|
117
117
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
118
|
+
```typescript
|
|
119
|
+
// Best, average, median, worst and fair price per line across bookmakers (Growth plans and above)
|
|
120
|
+
const summary = await client.getOddsSummary({ eventId: 123456, markets: ['ML', 'Totals'], includeExchanges: true });
|
|
121
|
+
const home = summary.markets[0].lines[0].outcomes.home;
|
|
122
|
+
console.log(home.best, home.bestBookmakers, home.fair);
|
|
123
|
+
|
|
124
|
+
// Price history for one market (prematch)
|
|
125
|
+
const history = await client.getOddsMovement({ eventId: 123456, bookmaker: 'Bet365', market: 'Totals', marketLine: 2.5 });
|
|
126
|
+
console.log(history.opening, history.latest);
|
|
122
127
|
```
|
|
123
128
|
|
|
124
|
-
|
|
129
|
+
## Polling for changes
|
|
125
130
|
|
|
126
|
-
|
|
127
|
-
// Get odds for a specific event
|
|
128
|
-
const odds = await client.getEventOdds({
|
|
129
|
-
eventId: '62924717',
|
|
130
|
-
bookmakers: 'singbet,bet365'
|
|
131
|
-
});
|
|
131
|
+
`/odds/updated` returns only the market groups that changed. `pollUpdatedOdds` passes each `X-Next-Since` header back as the next `since`:
|
|
132
132
|
|
|
133
|
-
|
|
134
|
-
const
|
|
135
|
-
|
|
136
|
-
bookmaker: '
|
|
137
|
-
|
|
138
|
-
|
|
133
|
+
```typescript
|
|
134
|
+
const controller = new AbortController();
|
|
135
|
+
for await (const batch of client.pollUpdatedOdds({
|
|
136
|
+
bookmaker: 'Bet365',
|
|
137
|
+
sport: 'football',
|
|
138
|
+
markets: ['ML', 'Spread', 'Totals'], // required, max 40
|
|
139
|
+
intervalMs: 10_000,
|
|
140
|
+
signal: controller.signal,
|
|
141
|
+
})) {
|
|
142
|
+
for (const event of batch.data) {
|
|
143
|
+
// merge by event, bookmaker and market name; an absent market has not changed
|
|
144
|
+
}
|
|
145
|
+
}
|
|
139
146
|
```
|
|
140
147
|
|
|
141
|
-
|
|
148
|
+
For live odds the WebSocket is cheaper than any poll interval.
|
|
149
|
+
|
|
150
|
+
## WebSocket
|
|
151
|
+
|
|
152
|
+
`OddsWebSocket` connects to `wss://api.odds-api.io/v3/ws`, tracks the highest `seq` and reconnects with `lastSeq`, so missed updates are replayed. In Node.js install the `ws` package (`npm install ws`); the server requires permessage-deflate compression, which `ws` and browsers negotiate by default. WebSocket access is a plan add-on.
|
|
142
153
|
|
|
143
154
|
```typescript
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
155
|
+
import { OddsAPIClient, OddsWebSocket } from 'odds-api-io';
|
|
156
|
+
|
|
157
|
+
const client = new OddsAPIClient({ apiKey });
|
|
158
|
+
const eventIds = [123456, 123457];
|
|
159
|
+
const store = new Map();
|
|
160
|
+
|
|
161
|
+
// 1. Snapshot with its sequence number
|
|
162
|
+
const { data, seq } = await client.getOddsSnapshot({ eventIds, bookmakers: ['Bet365'], markets: ['ML', 'Totals'] });
|
|
163
|
+
for (const event of data) for (const [book, markets] of Object.entries(event.bookmakers)) store.set(`${event.id}:${book}`, markets);
|
|
164
|
+
|
|
165
|
+
// 2. Stream from that point
|
|
166
|
+
const feed = new OddsWebSocket({
|
|
167
|
+
apiKey,
|
|
168
|
+
markets: ['ML', 'Totals'], // required for the odds channel, max 40
|
|
169
|
+
channels: ['odds', 'scores', 'status'], // optional, default odds only
|
|
170
|
+
eventIds, // or sport / leagues, status: 'live' | 'prematch'
|
|
171
|
+
lastSeq: seq ?? undefined,
|
|
148
172
|
});
|
|
149
173
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
174
|
+
feed.on('resync_required', async () => {
|
|
175
|
+
// replay could not be served: rebuild from REST, then continue
|
|
176
|
+
const snap = await client.getOddsSnapshot({ eventIds, bookmakers: ['Bet365'], markets: ['ML', 'Totals'] });
|
|
177
|
+
feed.lastSeq = snap.seq ?? undefined;
|
|
153
178
|
});
|
|
179
|
+
feed.on('reconnecting', ({ attempt, delay, lastSeq }) => console.log(`reconnect #${attempt} in ${delay}ms from ${lastSeq}`));
|
|
180
|
+
|
|
181
|
+
for await (const msg of feed) {
|
|
182
|
+
if (msg.type === 'created' || msg.type === 'updated') store.set(`${msg.id}:${msg.bookie}`, msg.markets); // replace, do not merge
|
|
183
|
+
if (msg.type === 'deleted' || msg.type === 'no_markets') store.delete(`${msg.id}:${msg.bookie}`);
|
|
184
|
+
if (msg.type === 'score') console.log(msg.id, msg.scores, msg.clock);
|
|
185
|
+
}
|
|
154
186
|
```
|
|
155
187
|
|
|
156
|
-
|
|
188
|
+
Events: `open`, `message`, one per message type (`welcome`, `created`, `updated`, `deleted`, `no_markets`, `score`, `status`, `resync_required`, `replay_complete`), `reconnecting`, `close` and `error`. `feed.close()` stops it; `feed.lastSeq` is the resume point to persist.
|
|
189
|
+
|
|
190
|
+
Close codes: 1012 (server restart) reconnects at once, 1013 (cooldown) waits at least 3 seconds, 1008 because a newer connection replaced this one stops instead of fighting it (two connections per key). A refused handshake (401, 403, 426) is not retried and rejects `connect()` / the iterator with `OddsWebSocketError`. Options: `reconnect` (default true), `maxReconnectAttempts`, `initialReconnectDelay`, `maxReconnectDelay`, `replayComplete` (default true) and `WebSocket` to pass your own implementation.
|
|
191
|
+
|
|
192
|
+
## Historical odds and closing lines
|
|
157
193
|
|
|
158
194
|
```typescript
|
|
159
|
-
//
|
|
160
|
-
const
|
|
195
|
+
// Finished events for one league (31 days per call)
|
|
196
|
+
const past = await client.getHistoricalEvents({
|
|
161
197
|
sport: 'football',
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
includeEventDetails: true
|
|
198
|
+
league: 'england-premier-league',
|
|
199
|
+
from: '2026-09-01T00:00:00Z',
|
|
200
|
+
to: '2026-09-30T23:59:59Z',
|
|
166
201
|
});
|
|
167
202
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
console.log(
|
|
171
|
-
}
|
|
172
|
-
```
|
|
203
|
+
// Any range: fetched in 31-day windows
|
|
204
|
+
for await (const event of client.iterateHistoricalEvents({ sport: 'football', league: 'england-premier-league', from: '2026-01-01T00:00:00Z', to: '2026-10-31T00:00:00Z' })) {
|
|
205
|
+
console.log(event.home, event.away, event.scores?.periods?.ft);
|
|
206
|
+
}
|
|
173
207
|
|
|
174
|
-
|
|
208
|
+
// Odds for one finished event
|
|
209
|
+
const closing = await client.getHistoricalOdds({ eventId: past[0].id, bookmakers: ['Bet365'], markets: ['ML'] });
|
|
175
210
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
211
|
+
// Closing lines for every settled event across up to 10 leagues (paid plans; 366 days per call, 100 per page)
|
|
212
|
+
for await (const event of client.iterateClosingLines({
|
|
213
|
+
sport: 'football',
|
|
214
|
+
leagues: ['england-premier-league', 'spain-laliga'],
|
|
215
|
+
from: '2026-08-01T00:00:00Z',
|
|
216
|
+
to: '2026-10-31T23:59:59Z',
|
|
217
|
+
markets: ['ML', 'Totals'],
|
|
218
|
+
bookmakers: ['Bet365', 'SingBet'],
|
|
219
|
+
})) {
|
|
220
|
+
console.log(event.id, event.bookmakers['Bet365']?.[0]?.odds[0]);
|
|
221
|
+
}
|
|
182
222
|
|
|
183
|
-
//
|
|
184
|
-
const
|
|
223
|
+
// Search finished events by team name
|
|
224
|
+
const arsenal = await client.searchHistoricalEvents({ query: 'Arsenal', sport: 'football' });
|
|
185
225
|
```
|
|
186
226
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
```typescript
|
|
190
|
-
// Get all available bookmakers
|
|
191
|
-
const bookmakers = await client.getBookmakers();
|
|
192
|
-
|
|
193
|
-
// Select specific bookmakers for your account
|
|
194
|
-
await client.selectBookmakers('singbet,bet365');
|
|
227
|
+
## Settlement and grading
|
|
195
228
|
|
|
196
|
-
|
|
197
|
-
const selected = await client.getSelectedBookmakers();
|
|
229
|
+
Paid plans. `getSettlements` returns status, a `final` flag and final scores; `gradeBets` grades selections against the result. Batches over 50 are split for you.
|
|
198
230
|
|
|
199
|
-
|
|
200
|
-
await client.
|
|
231
|
+
```typescript
|
|
232
|
+
const { settlements, notFound } = await client.getSettlements([74919888, 73101436]);
|
|
233
|
+
|
|
234
|
+
const { grades } = await client.gradeBets([
|
|
235
|
+
{ ref: 'bet-1', eventId: 74919888, market: 'ML', side: 'home' },
|
|
236
|
+
{ ref: 'bet-2', eventId: 74919888, market: 'Spread', hdp: -0.75, side: 'home' },
|
|
237
|
+
{ ref: 'bet-3', eventId: 74919888, market: 'Correct Score', label: '2-1' },
|
|
238
|
+
]);
|
|
239
|
+
for (const g of grades) {
|
|
240
|
+
console.log(g.ref, g.result, g.reason, g.final); // 'won' | 'lost' | 'void' | 'half_won' | 'half_lost' | 'pending' | 'ungradeable'
|
|
241
|
+
}
|
|
201
242
|
```
|
|
202
243
|
|
|
203
|
-
|
|
244
|
+
Re-send selections that are not `final`, at most once a minute.
|
|
204
245
|
|
|
205
|
-
|
|
246
|
+
## Outrights (golf)
|
|
206
247
|
|
|
207
|
-
|
|
208
|
-
|--------|-------------|------|
|
|
209
|
-
| `getSports()` | Get all available sports | [Docs](https://docs.odds-api.io/api-reference/sports/get-sports) |
|
|
210
|
-
| `getLeagues(sport)` | Get leagues for a sport | [Docs](https://docs.odds-api.io/api-reference/leagues/get-leagues) |
|
|
248
|
+
Outrights are a paid add-on: PGA Tour, DP World Tour, LIV Golf and the majors. A key without the add-on gets a `ForbiddenError` whose message links to the billing page.
|
|
211
249
|
|
|
212
|
-
|
|
250
|
+
```typescript
|
|
251
|
+
import { ForbiddenError, isPriceRunner } from 'odds-api-io';
|
|
213
252
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
253
|
+
try {
|
|
254
|
+
const tournaments = await client.getOutrights({ sport: 'golf', league: 'pga-tour' });
|
|
255
|
+
const odds = await client.getOutrightOdds({ id: tournaments[0].id, bookmakers: ['DraftKings', 'Betfair Exchange'] });
|
|
256
|
+
|
|
257
|
+
for (const market of odds.bookmakers['Betfair Exchange'] ?? []) {
|
|
258
|
+
// Winner, Top 5, Top 5 (Incl. Ties), Top 10, Top 10 (Incl. Ties), Top 20, Top 20 (Incl. Ties), Make Cut
|
|
259
|
+
for (const runner of market.odds.slice(0, 3)) {
|
|
260
|
+
if (isPriceRunner(runner)) console.log(market.name, runner.label, runner.odds, runner.layOdds);
|
|
261
|
+
else console.log(market.name, runner.label, runner.yes, runner.no); // Make Cut
|
|
262
|
+
}
|
|
263
|
+
}
|
|
220
264
|
|
|
221
|
-
|
|
265
|
+
const results = await client.getOutrightResults(tournaments[0].id);
|
|
266
|
+
console.log(results.winners['Top 10 (Incl. Ties)']);
|
|
267
|
+
} catch (err) {
|
|
268
|
+
if (err instanceof ForbiddenError && err.isAddOnRequired) console.log(err.message);
|
|
269
|
+
}
|
|
270
|
+
```
|
|
222
271
|
|
|
223
|
-
|
|
224
|
-
|--------|-------------|------|
|
|
225
|
-
| `getHistoricalEvents(params)` | Get finished historical events in a date range | [Docs](https://docs.odds-api.io/api-reference/historical/get-historical-events) |
|
|
226
|
-
| `getHistoricalOdds(params)` | Get closing odds for a historical event | [Docs](https://docs.odds-api.io/api-reference/historical/get-historical-odds) |
|
|
272
|
+
"Top N" settles a boundary tie under the bookmaker's dead-heat rules; "Top N (Incl. Ties)" pays it in full. They are separate markets.
|
|
227
273
|
|
|
228
|
-
|
|
274
|
+
## Value bets, arbitrage and dropping odds
|
|
229
275
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
| `getOddsMovement(params)` | Track odds changes | [Docs](https://docs.odds-api.io/api-reference/odds/get-odds-movements) |
|
|
234
|
-
| `getOddsForMultipleEvents(params)` | Get odds for multiple events | [Docs](https://docs.odds-api.io/api-reference/odds/get-odds-for-multiple-events) |
|
|
235
|
-
| `getUpdatedOddsSince(params)` | Get odds updated since timestamp. `markets` is required by the API from 15 October 2026 | [Docs](https://docs.odds-api.io/api-reference/odds/get-updated-event-odds-since-a-given-timestamp) |
|
|
276
|
+
```typescript
|
|
277
|
+
const valueBets = await client.getValueBets({ bookmaker: 'Bet365', sport: 'football', includeEventDetails: true });
|
|
278
|
+
valueBets.forEach((bet) => console.log(bet.market.name, bet.betSide, `${(bet.expectedValue * 100).toFixed(2)}% EV`));
|
|
236
279
|
|
|
237
|
-
|
|
280
|
+
// Price gaps across your bookmakers. Prices move and bookmakers limit stakes, so check every leg before acting.
|
|
281
|
+
const arbs = await client.getArbitrageBets({ bookmakers: ['Bet365', 'SingBet'], sport: 'football', markets: ['Totals'], minProfit: 1 });
|
|
282
|
+
arbs.forEach((arb) => console.log(arb.profitMargin, arb.legs.map((l) => `${l.bookmaker} ${l.side} @ ${l.odds}`)));
|
|
238
283
|
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
284
|
+
// Dropping odds from sharp bookmakers (paid plans)
|
|
285
|
+
const drops = await client.getDroppingOdds({ sport: 'football', markets: ['ML'], minDrop: 10, sort: 'recent', includeEventDetails: true });
|
|
286
|
+
drops.forEach((d) => console.log(`${d.market.name} ${d.betSide}: ${d.odds.opening} -> ${d.odds.current} (-${d.odds.drop.sinceOpening}%)`));
|
|
287
|
+
```
|
|
243
288
|
|
|
244
|
-
|
|
289
|
+
## Participants, logos and mappings
|
|
245
290
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
| `getBookmakers()` | Get all available bookmakers | [Docs](https://docs.odds-api.io/api-reference/bookmakers/get-bookmakers) |
|
|
249
|
-
| `getSelectedBookmakers()` | Get your selected bookmakers | [Docs](https://docs.odds-api.io/api-reference/bookmakers/get-selected-bookmakers) |
|
|
250
|
-
| `selectBookmakers(bookmakers)` | Select bookmakers for your account | [Docs](https://docs.odds-api.io/api-reference/bookmakers/select-bookmakers) |
|
|
251
|
-
| `clearSelectedBookmakers()` | Clear bookmaker selection | [Docs](https://docs.odds-api.io/api-reference/bookmakers/clear-selected-bookmakers) |
|
|
291
|
+
```typescript
|
|
292
|
+
const teams = await client.getParticipants({ sport: 'football', search: 'Chelsea' });
|
|
252
293
|
|
|
253
|
-
|
|
294
|
+
// PNG crest; the URL carries your key, so proxy it with getParticipantLogo() for public pages
|
|
295
|
+
const url = client.getParticipantLogoUrl(events[0].homeId!);
|
|
296
|
+
const png = await client.getParticipantLogo(events[0].homeId!); // ArrayBuffer
|
|
254
297
|
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
298
|
+
// A bookmaker's own market and outcome ids for our events (paid plans)
|
|
299
|
+
const { data } = await client.getMappings({ bookmaker: 'Polymarket', eventId: 71515842 });
|
|
300
|
+
for await (const row of client.iterateMappings({ bookmaker: 'Kalshi', sport: 'american-football' })) {
|
|
301
|
+
console.log(row.eventId, row.market, row.side, row.marketId, row.outcomeId);
|
|
302
|
+
}
|
|
303
|
+
```
|
|
260
304
|
|
|
261
|
-
##
|
|
305
|
+
## Bookmakers
|
|
262
306
|
|
|
263
|
-
|
|
307
|
+
```typescript
|
|
308
|
+
const bookmakers = await client.getBookmakers(); // name, active, createdAt, status ('ok' | 'degraded' | 'down'), reason
|
|
309
|
+
await client.selectBookmakers(['Bet365', 'SingBet']);
|
|
310
|
+
const { bookmakers: selected } = await client.getSelectedBookmakers();
|
|
311
|
+
await client.clearSelectedBookmakers(); // once every 12 hours
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
## Methods
|
|
315
|
+
|
|
316
|
+
| Area | Method | Endpoint |
|
|
317
|
+
|------|--------|----------|
|
|
318
|
+
| Catalogue | `getSports()` | `GET /sports` |
|
|
319
|
+
| | `getMarkets(sport?)` | `GET /markets` |
|
|
320
|
+
| | `getLeagues(sport, { all? })` | `GET /leagues` |
|
|
321
|
+
| | `getBookmakers()` | `GET /bookmakers` |
|
|
322
|
+
| | `getSelectedBookmakers()` | `GET /bookmakers/selected` |
|
|
323
|
+
| | `selectBookmakers(bookmakers)` | `PUT /bookmakers/selected/select` |
|
|
324
|
+
| | `clearSelectedBookmakers()` | `PUT /bookmakers/selected/clear` |
|
|
325
|
+
| Events | `getEvents(params)`, `iterateEvents(params, { pageSize?, maxPages? })` | `GET /events` |
|
|
326
|
+
| | `getEventById(id)` | `GET /events/{id}` |
|
|
327
|
+
| | `getLiveEvents(sport?)` | `GET /events/live` |
|
|
328
|
+
| | `searchEvents(query, { status? })` | `GET /events/search` |
|
|
329
|
+
| Odds | `getEventOdds(params)` | `GET /odds` |
|
|
330
|
+
| | `getOddsForMultipleEvents(params)`, `getOddsSnapshot(params)` | `GET /odds/multi` |
|
|
331
|
+
| | `getUpdatedOddsSince(params)`, `getUpdatedOddsSinceWithMeta(params)`, `pollUpdatedOdds(params)` | `GET /odds/updated` |
|
|
332
|
+
| | `getOddsMovement(params)` | `GET /odds/movements` |
|
|
333
|
+
| | `getOddsSummary(params)` | `GET /odds/summary` |
|
|
334
|
+
| | `getOddsSummaryMulti(params)` | `GET /odds/summary/multi` |
|
|
335
|
+
| Analysis | `getValueBets(params)` | `GET /value-bets` |
|
|
336
|
+
| | `getArbitrageBets(params)` | `GET /arbitrage-bets` |
|
|
337
|
+
| | `getDroppingOdds(params)`, `getDroppingOddsPage(params)`, `iterateDroppingOdds(params)` | `GET /dropping-odds` |
|
|
338
|
+
| Historical | `getHistoricalEvents(params)`, `iterateHistoricalEvents(params)` | `GET /historical/events` |
|
|
339
|
+
| | `searchHistoricalEvents(params)` | `GET /historical/events/search` |
|
|
340
|
+
| | `getHistoricalOdds(params)` | `GET /historical/odds` |
|
|
341
|
+
| | `getClosingLines(params)`, `iterateClosingLines(params)` | `GET /historical/closing-lines` |
|
|
342
|
+
| Settlement | `getSettlements(eventIds)` | `GET /settlements` |
|
|
343
|
+
| | `gradeBets(selections)` (alias `gradeSelections`) | `POST /settlements/grade` |
|
|
344
|
+
| Outrights | `getOutrights(params)` | `GET /outrights` |
|
|
345
|
+
| | `getOutrightOdds(params)` | `GET /outrights/odds` |
|
|
346
|
+
| | `getOutrightResults(id)` | `GET /outrights/results` |
|
|
347
|
+
| Participants | `getParticipants(params)` | `GET /participants` |
|
|
348
|
+
| | `getParticipantById(id)` | `GET /participants/{id}` |
|
|
349
|
+
| | `getParticipantLogo(id)`, `getParticipantLogoUrl(id)` | `GET /participants/{id}/logo` |
|
|
350
|
+
| Mappings | `getMappings(params)`, `iterateMappings(params)` | `GET /mappings` |
|
|
351
|
+
| WebSocket | `new OddsWebSocket(options)` | `wss://api.odds-api.io/v3/ws` |
|
|
352
|
+
|
|
353
|
+
Full parameter and response reference: [docs.odds-api.io/api-reference](https://docs.odds-api.io/api-reference).
|
|
354
|
+
|
|
355
|
+
## Errors
|
|
356
|
+
|
|
357
|
+
Every error extends `OddsAPIError` and carries the server's own message, plus `status`, `body` and `rateLimit` when there was a response.
|
|
358
|
+
|
|
359
|
+
| Class | When |
|
|
360
|
+
|-------|------|
|
|
361
|
+
| `BadRequestError` | 400: a parameter is missing or invalid (the message says which) |
|
|
362
|
+
| `InvalidAPIKeyError` | 401 |
|
|
363
|
+
| `ForbiddenError` | 403: the plan does not include the endpoint or bookmaker, or an add-on is missing (`isAddOnRequired`) |
|
|
364
|
+
| `NotFoundError` | 404: the message often lists what does exist |
|
|
365
|
+
| `RateLimitError` | 429, with `retryAfter` in seconds (`RateLimitExceededError` is the same class) |
|
|
366
|
+
| `ServerError` | 5xx |
|
|
367
|
+
| `TimeoutError`, `NetworkError` | no response |
|
|
368
|
+
| `OddsWebSocketError` | WebSocket handshake refused or the helper gave up (`code` = HTTP status or close code) |
|
|
264
369
|
|
|
265
370
|
```typescript
|
|
266
|
-
import {
|
|
267
|
-
OddsAPIClient,
|
|
268
|
-
OddsAPIError,
|
|
269
|
-
InvalidAPIKeyError,
|
|
270
|
-
RateLimitExceededError,
|
|
271
|
-
NotFoundError,
|
|
272
|
-
TimeoutError,
|
|
273
|
-
NetworkError
|
|
274
|
-
} from 'odds-api-io';
|
|
275
|
-
|
|
276
|
-
const client = new OddsAPIClient({ apiKey: 'your-api-key' });
|
|
371
|
+
import { OddsAPIError, RateLimitError, ForbiddenError } from 'odds-api-io';
|
|
277
372
|
|
|
278
373
|
try {
|
|
279
|
-
|
|
280
|
-
} catch (
|
|
281
|
-
if (
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
console.error('Rate limit exceeded - wait before retrying');
|
|
285
|
-
} else if (error instanceof NotFoundError) {
|
|
286
|
-
console.error('Resource not found');
|
|
287
|
-
} else if (error instanceof TimeoutError) {
|
|
288
|
-
console.error('Request timeout');
|
|
289
|
-
} else if (error instanceof NetworkError) {
|
|
290
|
-
console.error('Network error');
|
|
291
|
-
} else if (error instanceof OddsAPIError) {
|
|
292
|
-
console.error('API error:', error.message);
|
|
293
|
-
}
|
|
374
|
+
await client.getClosingLines({ /* ... */ });
|
|
375
|
+
} catch (err) {
|
|
376
|
+
if (err instanceof RateLimitError) console.log(`retry in ${err.retryAfter}s`);
|
|
377
|
+
else if (err instanceof ForbiddenError) console.log(err.message);
|
|
378
|
+
else if (err instanceof OddsAPIError) console.log(err.status, err.message);
|
|
294
379
|
}
|
|
380
|
+
|
|
381
|
+
console.log(client.lastRateLimit); // { limit, remaining, reset } from the last response
|
|
295
382
|
```
|
|
296
383
|
|
|
297
384
|
## Configuration
|
|
@@ -299,52 +386,49 @@ try {
|
|
|
299
386
|
```typescript
|
|
300
387
|
const client = new OddsAPIClient({
|
|
301
388
|
apiKey: 'your-api-key',
|
|
302
|
-
baseUrl: 'https://
|
|
303
|
-
timeout: 10000
|
|
389
|
+
baseUrl: 'https://api.odds-api.io/v3', // default
|
|
390
|
+
timeout: 10000, // ms per attempt
|
|
391
|
+
maxRetries: 2, // retries on 5xx, network errors and short 429 waits; 0 turns them off
|
|
392
|
+
maxRetryDelay: 10000, // a 429 asking for a longer wait is thrown, not waited out
|
|
304
393
|
});
|
|
305
394
|
```
|
|
306
395
|
|
|
307
|
-
|
|
396
|
+
Bookmaker selection changes (PUT) are never retried.
|
|
308
397
|
|
|
309
|
-
|
|
398
|
+
## Migrating from 1.3
|
|
310
399
|
|
|
311
|
-
|
|
312
|
-
import type {
|
|
313
|
-
Sport,
|
|
314
|
-
League,
|
|
315
|
-
Event,
|
|
316
|
-
HistoricalEvent,
|
|
317
|
-
Participant,
|
|
318
|
-
Bookmaker,
|
|
319
|
-
EventOdds,
|
|
320
|
-
HistoricalEventOdds,
|
|
321
|
-
ArbitrageBet,
|
|
322
|
-
ValueBet,
|
|
323
|
-
DroppingOddsEntry,
|
|
324
|
-
GetEventsParams,
|
|
325
|
-
GetHistoricalEventsParams,
|
|
326
|
-
GetHistoricalOddsParams
|
|
327
|
-
} from 'odds-api-io';
|
|
328
|
-
```
|
|
400
|
+
1.5.0 aligns the types with what the API returns. Code that used the old, inaccurate field names needs updating:
|
|
329
401
|
|
|
330
|
-
|
|
402
|
+
- `Event`: `date`, `home`, `away`, `homeId`, `awayId`, `status` (`pending | live | settled | cancelled`), `sport`/`league` as `{ name, slug }`, `scores.periods`.
|
|
403
|
+
- Period keys are `p1`..`pN`, `ft`, `ot`, `ap`. The old `period1`, `overtime`, `penalties` and `fulltime` keys stop being served on 12 November 2026.
|
|
404
|
+
- `EventOdds.bookmakers` is a map of bookmaker name to markets; `OddsMovement` has `opening`, `latest` and `movements`.
|
|
405
|
+
- `ArbitrageBet` uses `profitMargin` and `legs[].side`; `ValueBet` uses `expectedValue` and `betSide`.
|
|
406
|
+
- `Bookmaker` is `{ name, active, createdAt, status, reason }`; `getSelectedBookmakers()` returns `{ bookmakers, count }`.
|
|
407
|
+
- `getDroppingOdds` now sends `markets` (the old `market` option was ignored by the API; it is still accepted and sent as `markets`).
|
|
408
|
+
- Errors keep the server message instead of a fixed text.
|
|
409
|
+
- The default base URL is `https://api.odds-api.io/v3`.
|
|
410
|
+
|
|
411
|
+
## Examples
|
|
331
412
|
|
|
332
|
-
|
|
413
|
+
See [`examples/`](./examples):
|
|
333
414
|
|
|
334
|
-
|
|
415
|
+
- `basic-usage.ts` / `basic-usage.js`: getting started
|
|
416
|
+
- `premier-league-odds.ts`: odds for a league
|
|
417
|
+
- `odds-tracking.ts`: price history and the updated-odds delta
|
|
418
|
+
- `arbitrage-betting.ts`: price gaps across bookmakers
|
|
419
|
+
- `websocket-feed.ts`: REST snapshot plus `OddsWebSocket`
|
|
420
|
+
- `golf-outrights-and-settlement.ts`: outrights and bet grading
|
|
335
421
|
|
|
336
|
-
|
|
337
|
-
- 🌐 [**Odds-API.io Website**](https://odds-api.io)
|
|
338
|
-
- 💳 [**Get Your API Key**](https://odds-api.io/pricing)
|
|
339
|
-
- 🐛 [**Report Issues**](https://github.com/odds-api-io/odds-api-node/issues)
|
|
422
|
+
## Plans and Limits
|
|
340
423
|
|
|
341
|
-
|
|
424
|
+
An API key from a paid plan is required. Rate limits, bookmaker selection and WebSocket access depend on your plan; see [**odds-api.io/pricing**](https://odds-api.io/pricing?ref=npm).
|
|
342
425
|
|
|
343
|
-
|
|
426
|
+
## Resources
|
|
344
427
|
|
|
345
|
-
-
|
|
346
|
-
-
|
|
347
|
-
-
|
|
428
|
+
- [API documentation](https://docs.odds-api.io/)
|
|
429
|
+
- [Odds-API.io website](https://odds-api.io)
|
|
430
|
+
- [Get your API key](https://odds-api.io/pricing?ref=npm)
|
|
431
|
+
- [Report issues](https://github.com/odds-api-io/odds-api-node/issues)
|
|
348
432
|
|
|
349
433
|
## License
|
|
350
434
|
|
|
@@ -354,14 +438,11 @@ Check the [`examples/`](./examples) directory for more comprehensive examples:
|
|
|
354
438
|
|
|
355
439
|
This is the official SDK for Odds-API.io. This tool is for informational purposes only and should not be used as the sole basis for betting decisions.
|
|
356
440
|
|
|
357
|
-
---
|
|
358
|
-
|
|
359
|
-
Built with ❤️ for the sports betting and analytics community
|
|
360
441
|
|
|
361
442
|
## Citation
|
|
362
443
|
|
|
363
444
|
If you use this package in research or a publication, please cite it. Citation metadata is in [CITATION.cff](CITATION.cff) (GitHub renders a "Cite this repository" button from it) and Zenodo metadata is in `.zenodo.json`.
|
|
364
445
|
|
|
365
446
|
```
|
|
366
|
-
Outlier AS. odds-api-io: Official Node.js SDK for Odds-API.io (version 1.
|
|
447
|
+
Outlier AS. odds-api-io: Official Node.js SDK for Odds-API.io (version 1.5.1). https://github.com/odds-api-io/odds-api-node
|
|
367
448
|
```
|