tiktok-live-api-ranks

TikTok LIVE Rankings API

A typed client for the public TikTok LIVE leaderboard and rankings API. Pull live creator, gifter, gaming and shop rankings across 30+ regions, updated live, with a two-line install and no API key. Powered by the TikTool managed API.

Docs and dashboard: tik.tools

Zero dependencies. Uses the global fetch (Node 18+ or any modern browser). The endpoints wrapped here are public and need no key. For the full authenticated API - real-time WebSocket chat, gifts and battles, gift catalogs, profiles and signing - see tiktok-live-api.

Not affiliated with or endorsed by TikTok. It reads the public rankings published by the TikTool Live managed API service.

Install

npm install tiktok-live-api-ranks

Quick Start

import { TikTokRanks } from 'tiktok-live-api-ranks';

const ranks = new TikTokRanks();
const board = await ranks.getGlobalLeaderboard();

console.log(`${board.totalLive} creators live across ${board.totalRegions} regions`);
for (const region of board.regions) {
  console.log(`${region.region}: ${region.liveCount} live, top creator #${region.top[0]?.rank}`);
}

API

new TikTokRanks(options?)

• options.baseUrl - override the API base URL. Defaults to https://tik.tools.
• options.timeoutMs - request timeout in milliseconds. Defaults to 15000.

getGlobalLeaderboard(): Promise<GlobalLeaderboard>

Worldwide live totals plus a leaderboard per region. Each region board carries liveCount, totalScore and a top array of ranked creators (rank, uniqueId, displayName, score, isLive, roomId).

getRegion(regionCode): Promise<RegionLeaderboard | null>

The board for a single region, for example "US+", "BR" or "MENA". Region code is case-insensitive. Returns null when the region is not in the current global board.

const us = await ranks.getRegion('US+');
if (us) console.log(`US+ has ${us.liveCount} creators live`);

getTopChannels(): Promise<TopChannel[]>

The top live channels feed across all regions, ordered by the current ranking. Each channel carries uniqueId, displayName, viewerCount, region and roomId.

const channels = await ranks.getTopChannels();
console.log(`${channels.length} channels in the live top feed`);

Types

Every method returns a fully typed result. The exported types are GlobalLeaderboard, RegionLeaderboard, RankedCreator, TopChannel, TikTokRanksOptions and the TikTokRanksError class.

Why tik.tools

• Live, managed rankings. Creator, gifter, gaming and shop boards across 30+ regions, refreshed live - no scraping and no sign server to maintain.
• Agency and leaderboard intelligence. Region movers, gaming ranks and eligible-creator discovery on the full tik.tools API.
• AI live captions and translation. Real-time speech-to-text with 60+ language translation on the managed API.
• Unreal Engine plugin. Drive avatars and overlays from live chat, gifts and battles.
• Free Sandbox tier. Start building for free, upgrade only when you need higher limits or unmasked data.

License

MIT - see LICENSE.