@scorio/client-sdk

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

Zero dependencies. Full type safety. Works in Node.js, Deno, Bun, and browsers.

npm i @scorio/client-sdk

Quick Start

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

const client = new ScorioSDK({
  apiKey: 'YOUR_RAPIDAPI_KEY',
  host: 'YOUR_RAPIDAPI_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
const detail = await client.getGameDetail('01TESTGAME00000LIVESOC01');
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 | Sub-second pipeline, poll every 1-2s for in-play data | | Prematch coverage | 150+ days 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
• 150+ days of prematch data ahead
• 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 |

Odds Intelligence

| 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 |

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: 'YOUR_RAPIDAPI_HOST',    // 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 ULID
  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

| Feature | Free | Starter ($49/mo) | Pro ($149/mo) | Business ($399/mo) | |---------|:----:|:-----------------:|:-------------:|:-------------------:| | Catalog & search | Yes | Yes | Yes | Yes | | Live scores & stats | -- | Yes | Yes | Yes | | Prematch & schedule | -- | Yes | Yes | Yes | | Markets & odds | -- | -- | Yes | Yes | | Price history & movers | -- | -- | Yes | Yes |

Subscribe on RapidAPI to get your API key.

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