odds-api-io 1.3.1 → 1.5.2
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 +330 -245
- 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,382 @@
|
|
|
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
|
-
|
|
204
|
-
|
|
205
|
-
### Sports & Leagues
|
|
244
|
+
Re-send selections that are not `final`, at most once a minute.
|
|
206
245
|
|
|
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) |
|
|
246
|
+
## Outrights (golf)
|
|
211
247
|
|
|
212
|
-
|
|
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.
|
|
213
249
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
| `getEvents(params)` | Get events with filters | [Docs](https://docs.odds-api.io/api-reference/events/get-events) |
|
|
217
|
-
| `getEventById(eventId)` | Get specific event details | [Docs](https://docs.odds-api.io/api-reference/events/get-event-by-id) |
|
|
218
|
-
| `getLiveEvents(sport)` | Get currently live events | [Docs](https://docs.odds-api.io/api-reference/events/get-live-events) |
|
|
219
|
-
| `searchEvents(query)` | Search for events by keyword | [Docs](https://docs.odds-api.io/api-reference/events/search-events) |
|
|
250
|
+
```typescript
|
|
251
|
+
import { ForbiddenError, isPriceRunner } from 'odds-api-io';
|
|
220
252
|
|
|
221
|
-
|
|
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
|
+
}
|
|
222
264
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
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
|
+
```
|
|
227
271
|
|
|
228
|
-
|
|
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.
|
|
229
273
|
|
|
230
|
-
|
|
231
|
-
|--------|-------------|------|
|
|
232
|
-
| `getEventOdds(params)` | Get odds for an event | [Docs](https://docs.odds-api.io/api-reference/odds/get-event-odds) |
|
|
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) |
|
|
274
|
+
## Value bets, arbitrage and dropping odds
|
|
236
275
|
|
|
237
|
-
|
|
276
|
+
```typescript
|
|
277
|
+
const valueBets = await client.getValueBets({ bookmaker: 'Bet365', sport: 'football', includeEventDetails: true });
|
|
278
|
+
// expectedValue is bookmaker odds / fair odds x 100, so the edge in percent is expectedValue - 100 (103.42 = 3.42% edge)
|
|
279
|
+
valueBets
|
|
280
|
+
.filter((bet) => bet.expectedValue - 100 >= 3)
|
|
281
|
+
.forEach((bet) => console.log(bet.market.name, bet.betSide, `${(bet.expectedValue - 100).toFixed(2)}% edge`));
|
|
282
|
+
|
|
283
|
+
// Price gaps across your bookmakers. Prices move and bookmakers limit stakes, so check every leg before acting.
|
|
284
|
+
const arbs = await client.getArbitrageBets({ bookmakers: ['Bet365', 'SingBet'], sport: 'football', markets: ['Totals'], minProfit: 1 });
|
|
285
|
+
// profitMargin is already a percentage (2.48 = 2.48%)
|
|
286
|
+
arbs.forEach((arb) => console.log(`${arb.profitMargin.toFixed(2)}%`, arb.legs.map((l) => `${l.bookmaker} ${l.side} @ ${l.odds}`)));
|
|
287
|
+
|
|
288
|
+
// Dropping odds from sharp bookmakers (paid plans)
|
|
289
|
+
const drops = await client.getDroppingOdds({ sport: 'football', markets: ['ML'], minDrop: 10, sort: 'recent', includeEventDetails: true });
|
|
290
|
+
drops.forEach((d) => console.log(`${d.market.name} ${d.betSide}: ${d.odds.opening} -> ${d.odds.current} (-${d.odds.drop.sinceOpening}%)`));
|
|
291
|
+
```
|
|
238
292
|
|
|
239
|
-
|
|
240
|
-
|--------|-------------|------|
|
|
241
|
-
| `getParticipants(params)` | Get participants/teams | [Docs](https://docs.odds-api.io/api-reference/participants/get-participants) |
|
|
242
|
-
| `getParticipantById(id)` | Get participant by ID | [Docs](https://docs.odds-api.io/api-reference/participants/get-participant-by-id) |
|
|
293
|
+
## Participants, logos and mappings
|
|
243
294
|
|
|
244
|
-
|
|
295
|
+
```typescript
|
|
296
|
+
const teams = await client.getParticipants({ sport: 'football', search: 'Chelsea' });
|
|
245
297
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
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) |
|
|
298
|
+
// PNG crest; the URL carries your key, so proxy it with getParticipantLogo() for public pages
|
|
299
|
+
const url = client.getParticipantLogoUrl(events[0].homeId!);
|
|
300
|
+
const png = await client.getParticipantLogo(events[0].homeId!); // ArrayBuffer
|
|
252
301
|
|
|
253
|
-
|
|
302
|
+
// A bookmaker's own market and outcome ids for our events (paid plans)
|
|
303
|
+
const { data } = await client.getMappings({ bookmaker: 'Polymarket', eventId: 71515842 });
|
|
304
|
+
for await (const row of client.iterateMappings({ bookmaker: 'Kalshi', sport: 'american-football' })) {
|
|
305
|
+
console.log(row.eventId, row.market, row.side, row.marketId, row.outcomeId);
|
|
306
|
+
}
|
|
307
|
+
```
|
|
254
308
|
|
|
255
|
-
|
|
256
|
-
|--------|-------------|------|
|
|
257
|
-
| `getArbitrageBets(params)` | Find arbitrage opportunities | [Docs](https://docs.odds-api.io/api-reference/arbitrage-bets/get-arbitrage-betting-opportunities) |
|
|
258
|
-
| `getValueBets(params)` | Find value bets | [Docs](https://docs.odds-api.io/api-reference/value-bets/get-value-bets) |
|
|
259
|
-
| `getDroppingOdds(params)` | Track sharp bookmaker line movements | [Docs](https://docs.odds-api.io/api-reference/dropping-odds/get-dropping-odds) |
|
|
309
|
+
## Bookmakers
|
|
260
310
|
|
|
261
|
-
|
|
311
|
+
```typescript
|
|
312
|
+
const bookmakers = await client.getBookmakers(); // name, active, createdAt, status ('ok' | 'degraded' | 'down'), reason
|
|
313
|
+
await client.selectBookmakers(['Bet365', 'SingBet']);
|
|
314
|
+
const { bookmakers: selected } = await client.getSelectedBookmakers();
|
|
315
|
+
await client.clearSelectedBookmakers(); // once every 12 hours
|
|
316
|
+
```
|
|
262
317
|
|
|
263
|
-
|
|
318
|
+
## Methods
|
|
319
|
+
|
|
320
|
+
| Area | Method | Endpoint |
|
|
321
|
+
|------|--------|----------|
|
|
322
|
+
| Catalogue | `getSports()` | `GET /sports` |
|
|
323
|
+
| | `getMarkets(sport?)` | `GET /markets` |
|
|
324
|
+
| | `getLeagues(sport, { all? })` | `GET /leagues` |
|
|
325
|
+
| | `getBookmakers()` | `GET /bookmakers` |
|
|
326
|
+
| | `getSelectedBookmakers()` | `GET /bookmakers/selected` |
|
|
327
|
+
| | `selectBookmakers(bookmakers)` | `PUT /bookmakers/selected/select` |
|
|
328
|
+
| | `clearSelectedBookmakers()` | `PUT /bookmakers/selected/clear` |
|
|
329
|
+
| Events | `getEvents(params)`, `iterateEvents(params, { pageSize?, maxPages? })` | `GET /events` |
|
|
330
|
+
| | `getEventById(id)` | `GET /events/{id}` |
|
|
331
|
+
| | `getLiveEvents(sport?)` | `GET /events/live` |
|
|
332
|
+
| | `searchEvents(query, { status? })` | `GET /events/search` |
|
|
333
|
+
| Odds | `getEventOdds(params)` | `GET /odds` |
|
|
334
|
+
| | `getOddsForMultipleEvents(params)`, `getOddsSnapshot(params)` | `GET /odds/multi` |
|
|
335
|
+
| | `getUpdatedOddsSince(params)`, `getUpdatedOddsSinceWithMeta(params)`, `pollUpdatedOdds(params)` | `GET /odds/updated` |
|
|
336
|
+
| | `getOddsMovement(params)` | `GET /odds/movements` |
|
|
337
|
+
| | `getOddsSummary(params)` | `GET /odds/summary` |
|
|
338
|
+
| | `getOddsSummaryMulti(params)` | `GET /odds/summary/multi` |
|
|
339
|
+
| Analysis | `getValueBets(params)` | `GET /value-bets` |
|
|
340
|
+
| | `getArbitrageBets(params)` | `GET /arbitrage-bets` |
|
|
341
|
+
| | `getDroppingOdds(params)`, `getDroppingOddsPage(params)`, `iterateDroppingOdds(params)` | `GET /dropping-odds` |
|
|
342
|
+
| Historical | `getHistoricalEvents(params)`, `iterateHistoricalEvents(params)` | `GET /historical/events` |
|
|
343
|
+
| | `searchHistoricalEvents(params)` | `GET /historical/events/search` |
|
|
344
|
+
| | `getHistoricalOdds(params)` | `GET /historical/odds` |
|
|
345
|
+
| | `getClosingLines(params)`, `iterateClosingLines(params)` | `GET /historical/closing-lines` |
|
|
346
|
+
| Settlement | `getSettlements(eventIds)` | `GET /settlements` |
|
|
347
|
+
| | `gradeBets(selections)` (alias `gradeSelections`) | `POST /settlements/grade` |
|
|
348
|
+
| Outrights | `getOutrights(params)` | `GET /outrights` |
|
|
349
|
+
| | `getOutrightOdds(params)` | `GET /outrights/odds` |
|
|
350
|
+
| | `getOutrightResults(id)` | `GET /outrights/results` |
|
|
351
|
+
| Participants | `getParticipants(params)` | `GET /participants` |
|
|
352
|
+
| | `getParticipantById(id)` | `GET /participants/{id}` |
|
|
353
|
+
| | `getParticipantLogo(id)`, `getParticipantLogoUrl(id)` | `GET /participants/{id}/logo` |
|
|
354
|
+
| Mappings | `getMappings(params)`, `iterateMappings(params)` | `GET /mappings` |
|
|
355
|
+
| WebSocket | `new OddsWebSocket(options)` | `wss://api.odds-api.io/v3/ws` |
|
|
356
|
+
|
|
357
|
+
Full parameter and response reference: [docs.odds-api.io/api-reference](https://docs.odds-api.io/api-reference).
|
|
358
|
+
|
|
359
|
+
## Errors
|
|
360
|
+
|
|
361
|
+
Every error extends `OddsAPIError` and carries the server's own message, plus `status`, `body` and `rateLimit` when there was a response.
|
|
362
|
+
|
|
363
|
+
| Class | When |
|
|
364
|
+
|-------|------|
|
|
365
|
+
| `BadRequestError` | 400: a parameter is missing or invalid (the message says which) |
|
|
366
|
+
| `InvalidAPIKeyError` | 401 |
|
|
367
|
+
| `ForbiddenError` | 403: the plan does not include the endpoint or bookmaker, or an add-on is missing (`isAddOnRequired`) |
|
|
368
|
+
| `NotFoundError` | 404: the message often lists what does exist |
|
|
369
|
+
| `RateLimitError` | 429, with `retryAfter` in seconds (`RateLimitExceededError` is the same class) |
|
|
370
|
+
| `ServerError` | 5xx |
|
|
371
|
+
| `TimeoutError`, `NetworkError` | no response |
|
|
372
|
+
| `OddsWebSocketError` | WebSocket handshake refused or the helper gave up (`code` = HTTP status or close code) |
|
|
264
373
|
|
|
265
374
|
```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' });
|
|
375
|
+
import { OddsAPIError, RateLimitError, ForbiddenError } from 'odds-api-io';
|
|
277
376
|
|
|
278
377
|
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
|
-
}
|
|
378
|
+
await client.getClosingLines({ /* ... */ });
|
|
379
|
+
} catch (err) {
|
|
380
|
+
if (err instanceof RateLimitError) console.log(`retry in ${err.retryAfter}s`);
|
|
381
|
+
else if (err instanceof ForbiddenError) console.log(err.message);
|
|
382
|
+
else if (err instanceof OddsAPIError) console.log(err.status, err.message);
|
|
294
383
|
}
|
|
384
|
+
|
|
385
|
+
console.log(client.lastRateLimit); // { limit, remaining, reset } from the last response
|
|
295
386
|
```
|
|
296
387
|
|
|
297
388
|
## Configuration
|
|
@@ -299,52 +390,49 @@ try {
|
|
|
299
390
|
```typescript
|
|
300
391
|
const client = new OddsAPIClient({
|
|
301
392
|
apiKey: 'your-api-key',
|
|
302
|
-
baseUrl: 'https://
|
|
303
|
-
timeout: 10000
|
|
393
|
+
baseUrl: 'https://api.odds-api.io/v3', // default
|
|
394
|
+
timeout: 10000, // ms per attempt
|
|
395
|
+
maxRetries: 2, // retries on 5xx, network errors and short 429 waits; 0 turns them off
|
|
396
|
+
maxRetryDelay: 10000, // a 429 asking for a longer wait is thrown, not waited out
|
|
304
397
|
});
|
|
305
398
|
```
|
|
306
399
|
|
|
307
|
-
|
|
400
|
+
Bookmaker selection changes (PUT) are never retried.
|
|
308
401
|
|
|
309
|
-
|
|
402
|
+
## Migrating from 1.3
|
|
310
403
|
|
|
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
|
-
```
|
|
404
|
+
1.5.0 aligns the types with what the API returns. Code that used the old, inaccurate field names needs updating:
|
|
329
405
|
|
|
330
|
-
|
|
406
|
+
- `Event`: `date`, `home`, `away`, `homeId`, `awayId`, `status` (`pending | live | settled | cancelled`), `sport`/`league` as `{ name, slug }`, `scores.periods`.
|
|
407
|
+
- Period keys are `p1`..`pN`, `ft`, `ot`, `ap`. The old `period1`, `overtime`, `penalties` and `fulltime` keys stop being served on 12 November 2026.
|
|
408
|
+
- `EventOdds.bookmakers` is a map of bookmaker name to markets; `OddsMovement` has `opening`, `latest` and `movements`.
|
|
409
|
+
- `ArbitrageBet` uses `profitMargin` and `legs[].side`; `ValueBet` uses `expectedValue` and `betSide`.
|
|
410
|
+
- `Bookmaker` is `{ name, active, createdAt, status, reason }`; `getSelectedBookmakers()` returns `{ bookmakers, count }`.
|
|
411
|
+
- `getDroppingOdds` now sends `markets` (the old `market` option was ignored by the API; it is still accepted and sent as `markets`).
|
|
412
|
+
- Errors keep the server message instead of a fixed text.
|
|
413
|
+
- The default base URL is `https://api.odds-api.io/v3`.
|
|
414
|
+
|
|
415
|
+
## Examples
|
|
331
416
|
|
|
332
|
-
|
|
417
|
+
See [`examples/`](./examples):
|
|
333
418
|
|
|
334
|
-
|
|
419
|
+
- `basic-usage.ts` / `basic-usage.js`: getting started
|
|
420
|
+
- `premier-league-odds.ts`: odds for a league
|
|
421
|
+
- `odds-tracking.ts`: price history and the updated-odds delta
|
|
422
|
+
- `arbitrage-betting.ts`: price gaps across bookmakers
|
|
423
|
+
- `websocket-feed.ts`: REST snapshot plus `OddsWebSocket`
|
|
424
|
+
- `golf-outrights-and-settlement.ts`: outrights and bet grading
|
|
335
425
|
|
|
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)
|
|
426
|
+
## Plans and Limits
|
|
340
427
|
|
|
341
|
-
|
|
428
|
+
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
429
|
|
|
343
|
-
|
|
430
|
+
## Resources
|
|
344
431
|
|
|
345
|
-
-
|
|
346
|
-
-
|
|
347
|
-
-
|
|
432
|
+
- [API documentation](https://docs.odds-api.io/)
|
|
433
|
+
- [Odds-API.io website](https://odds-api.io)
|
|
434
|
+
- [Get your API key](https://odds-api.io/pricing?ref=npm)
|
|
435
|
+
- [Report issues](https://github.com/odds-api-io/odds-api-node/issues)
|
|
348
436
|
|
|
349
437
|
## License
|
|
350
438
|
|
|
@@ -354,14 +442,11 @@ Check the [`examples/`](./examples) directory for more comprehensive examples:
|
|
|
354
442
|
|
|
355
443
|
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
444
|
|
|
357
|
-
---
|
|
358
|
-
|
|
359
|
-
Built with ❤️ for the sports betting and analytics community
|
|
360
445
|
|
|
361
446
|
## Citation
|
|
362
447
|
|
|
363
448
|
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
449
|
|
|
365
450
|
```
|
|
366
|
-
Outlier AS. odds-api-io: Official Node.js SDK for Odds-API.io (version 1.
|
|
451
|
+
Outlier AS. odds-api-io: Official Node.js SDK for Odds-API.io (version 1.5.2). https://github.com/odds-api-io/odds-api-node
|
|
367
452
|
```
|