@scorio/client-sdk

TypeScript SDK for the Scorio Sports API — real-time odds, live scores, price history & analytics across 80+ sports.

Zero dependencies. Fully typed. ESM (Node 18+, Deno, Bun, and modern browsers via import).

npm i @scorio/client-sdk

→ Get an API key on RapidAPI — free Basic plan, no card for testing. Pricing below.

Quick Start

import ScorioSDK from '@scorio/client-sdk';

const client = new ScorioSDK({
  apiKey: 'YOUR_RAPIDAPI_KEY',       // from your RapidAPI subscription
  host: 'scorio.p.rapidapi.com',     // the RapidAPI proxy host
});

// Get all sports
const sports = await client.getSports();
console.log(sports.data);
// [{ id: "01KNS...", name: "Football", alias: "Soccer", category: "sport" }, ...]

// Get live games with scores
const live = await client.getAllLiveGames();
for (const game of live.data) {
  console.log(`${game.home_team} ${game.score_text} ${game.away_team}`);
}
// Arsenal 2:1 (67') Chelsea
// Real Madrid 0:0 (12') Barcelona

// Get full game detail with all markets & odds.
// Path IDs accept stable tokens too: 'demo' resolves to a live game that always
// has data, and a sport alias like 'football' works wherever a sport_id is asked.
const detail = await client.getGameDetail('demo');
for (const market of detail.data.markets) {
  console.log(market.name, market.outcomes.map(o => `${o.name} @ ${o.price}`));
}
// Match Result ["Arsenal @ 1.85", "Draw @ 3.40", "Chelsea @ 4.50"]
// Total Goals  ["Over 2.5 @ 1.72", "Under 2.5 @ 2.10"]

// Track odds movements — find where sharp money is going
const movers = await client.getOddsMovers({ minutes: 60, limit: 10 });
// [{ event_name: "Chelsea", change_percent: 18.42, current_price: 4.50, opening_price: 3.80 }]

What You Get

| Feature | Details | |---------|---------| | Live scores & odds | Real-time in-play pipeline, poll every 1-2s | | Prematch coverage | Fixtures 1-3 months ahead, full market depth | | Price history | Every odds tick recorded, 60-day retention | | Odds intelligence | Steam moves, min/max/avg summaries, % change tracking | | Full catalog | Sports > Regions > Competitions hierarchy | | Search | Find games by team name, browse by date, starting-soon filter |

Data Coverage

• 80+ sports — football, basketball, tennis, cricket, esports, virtuals, racing, MMA
• 1-3 months of prematch fixtures ahead (outrights and futures reach further)
• 60-day historical price retention per outcome
• Thousands of markets per game for major competitions
• Global coverage — all major leagues, tournaments, and regions worldwide

All Methods

Catalog

| Method | Description | |--------|-------------| | getSports() | List all available sports | | getSportsCounts() | Sports with live and prematch game counts | | getRegions(sportId) | Regions (countries) for a sport | | getCompetitions(regionId) | Competitions for a region | | getCompetitionsBySport(sportId) | All competitions for a sport (flat list) |

Live

| Method | Description | |--------|-------------| | getAllLiveGames() | Every live game across all sports | | getLiveGamesBySport(sportId) | Live games for one sport | | getLiveSnapshot() | Full dashboard: sport counts + all live games in one call |

Prematch

| Method | Description | |--------|-------------| | getPrematchGames(sportId, opts?) | Upcoming games for a sport (paginated) |

Games

| Method | Description | |--------|-------------| | getGamesByCompetition(competitionId, opts?) | Games for a competition (paginated) | | getGamesStartingSoon(opts?) | Games starting within N minutes | | searchGames(query, opts?) | Search by team name | | getGameDetail(gameId) | Full game with all markets and odds | | getResults(opts?) | Finished games with final scores |

Odds Intelligence — requires Ultra or Mega

| Method | Description | |--------|-------------| | getGameOddsSummary(gameId) | Min/max/avg price per outcome | | getOddsMovers(opts?) | Biggest price movements (steam moves) | | getEventPriceHistory(eventId, opts?) | Full tick-level price history for an outcome | | getEventDailyPriceHistory(eventId, opts?) | Daily open/close/min/max candles (longer window) |

Schedule

| Method | Description | |--------|-------------| | getSchedule(opts?) | Games by date or date range, filterable by sport/competition |

System

| Method | Description | |--------|-------------| | health() | API health check (no auth required) | | ping() | Connectivity check (no auth required) |

Configuration

const client = new ScorioSDK({
  apiKey: 'YOUR_RAPIDAPI_KEY',        // Required — from your RapidAPI subscription
  host: 'scorio.p.rapidapi.com',      // Required — RapidAPI proxy host
  logger: true,                       // Optional — log requests to stdout (default: false)
  timeout: 15_000,                    // Optional — request timeout in ms (default: 30000)
});

Response Format

All list endpoints return:

{
  data: T[],
  meta: { count: number }
}

Single-resource endpoints return:

{
  data: T
}

Types

Every response is fully typed. Hover over any method to see JSDoc with plan info, polling recommendations, and examples.

import type {
  Sport, SportCount, Region, Competition,
  Game, GameInfo, GameStats, Market, Outcome,
  LiveSnapshot, OddsSummary, OddsMover, PricePoint,
  ListResponse, SingleResponse,
} from '@scorio/client-sdk';

Game Object

interface Game {
  id: string;              // Stable opaque ID (26 chars) — treat as a string, not time-sortable
  home_team: string;       // "Arsenal"
  away_team: string;       // "Chelsea"
  status: 'prematch' | 'live' | 'ended';
  start_time: number;      // Unix timestamp (seconds)
  is_live: boolean;
  markets_count: number;   // Number of available markets
  competition_id: string;
  sport_id: string;
  score_text: string;      // "2:1 (67')" or "" for prematch
  info: GameInfo | null;   // Structured scores, game state, timer
  stats: GameStats | null; // Goals, corners, cards, set scores
  updated_at: string;      // ISO 8601
  markets: Market[];       // Nested markets with outcomes
}

Market & Outcome

interface Market {
  id: string;
  name: string;            // "Match Result", "Total Goals"
  type: string;            // "P1XP2", "MatchTotal2"
  line: number | null;     // 2.5 for Over/Under, null for 1X2
  outcomes: Outcome[];
}

interface Outcome {
  id: string;
  name: string;            // "Arsenal", "Over 2.5"
  price: number;           // Decimal odds: 1.85
  is_suspended: boolean;
}

Error Handling

import { ScorioError, PlanLimitError, RateLimitError, NetworkError } from '@scorio/client-sdk';

try {
  const games = await client.getAllLiveGames();
} catch (err) {
  if (err instanceof PlanLimitError) {
    console.log(`Upgrade your plan. Current: ${err.currentPlan}`);
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof NetworkError) {
    console.log('Network error:', err.message);
  }
}

Polling Recommendations

| Data | Interval | Use Case | |------|----------|----------| | Live games & odds | 1-2s | Live scoreboards, in-play betting | | Prematch games | 10-30s | Upcoming fixtures, prematch odds | | Catalog | 60s | Sport/region/competition navigation | | Schedule | 60s | Daily fixture lists | | Odds movers | 5-10s | Steam move alerts, sharp money tracking | | Price history | On demand | Odds charts, trend analysis |

Plans

Billing, quotas and keys are handled by RapidAPI. Every plan includes full markets and odds in game responses — only the odds-intelligence endpoints (movers, price history, odds summary) are gated to Ultra and above.

| | Basic | Pro | Ultra ⭐ | Mega | |---|:---:|:---:|:---:|:---:| | Price | Free | $49 / mo | $149 / mo | $399 / mo | | Requests / month | 30,000 | 1,000,000 | 5,000,000 | 13,000,000 | | Rate limit | 30 / min | 100 / min | 500 / min | 2,000 / min | | Catalog & search | ✓ | ✓ | ✓ | ✓ | | Live scores & stats | ✓ | ✓ | ✓ | ✓ | | Prematch & schedule | ✓ | ✓ | ✓ | ✓ | | Markets & odds | ✓ | ✓ | ✓ | ✓ | | Odds intelligence (movers, history, summaries) | — | — | ✓ | ✓ |

At 30 requests/minute the free Basic plan is for evaluation and light use; sustained 1-2s live polling needs Pro or higher.

🛒 Subscribe on RapidAPI →

Pick a plan, get your X-RapidAPI-Key, and pass it to the client:

const client = new ScorioSDK({
  apiKey: 'YOUR_RAPIDAPI_KEY',            // from your RapidAPI subscription
  host: 'scorio.p.rapidapi.com',          // the RapidAPI proxy host
});

Use Cases

Sportsbook / Betting Platform — Real-time odds feed with full market depth. Hundreds of markets per game. Sub-second updates.

Live Scoreboard — Live scores, game states, timers, and per-period statistics across 80+ sports. Build a multi-sport live ticker in minutes.

Odds Comparison Site — Track price movements across outcomes. Historical price data with tick-level granularity for charts and analysis.

Analytics Dashboard — Odds intelligence: steam moves, min/max/avg summaries. Identify sharp money and market inefficiencies.

Sports Content Platform — Schedule, fixtures, team search. Build editorial calendars and daily betting previews.

Trading Bot — Price history API gives you every odds tick for the last 60 days. Backtest strategies with real data.

Requirements

• Node.js 18+ / Deno / Bun / Modern browsers (uses native fetch)
• TypeScript 5+ recommended (works with JavaScript too)

License

MIT

Odds intelligence (ULTRA+)

// biggest movers, excluding suspended long shots and simulated sports
const { data } = await client.getOddsMovers({ minutes: 60, maxPrice: 10, includeVirtual: false });
// Movers are tracked on the main markets (match result, totals, handicaps) — where
// the money actually moves. Exotic props swing on thin liquidity and are not reported.

// daily open/close/min/max candles — reaches further back than tick history
const { data: candles } = await client.getEventDailyPriceHistory('demo', { limit: 30 });

Path IDs accept stable tokens: a sport alias (football) or demo for a live example that always carries data.