JavaScript

TopStats SDK

Welcome to the community maintained Node.js client for the topstats.gg API.

Install TopStats SDK
Terminal window
```
npm install @topstats/sdk
```

Initialize the Client

import { Client } from "@topstats/sdk";

const client = new Client("YOUR_TOKEN");

Make Your First Request

// Get information about a bot
const bot = await client.getBot("583807014896140293");
console.log(bot.name, bot.server_count);

Usage Examples

// Get detailed bot information
const bot = await client.getBot("583807014896140293");
console.log(bot.name, bot.server_count);

// Get historical statistics
const history = await client.getBotHistorical(
  "583807014896140293",
  "30d",
  "monthly_votes"
);
console.log(history.data);

// Get top bots
const rankings = await client.getRankings({
  sortBy: "monthly_votes_rank",
  sortMethod: "desc",
  limit: 10
});
console.log(rankings.data);

API Reference

Methods

getBot(botId: string): Promise<BotData>

// Example
const bot = await client.getBot("583807014896140293");

getBotHistorical(
  botId: string,
  timeFrame: HistoricalTimeFrame,
  type: HistoricalDataType
): Promise<HistoricalDataResponse>

// Available timeframes
enum HistoricalTimeFrame {
  ALL_TIME = "alltime",
  FIVE_YEARS = "5y",
  THREE_YEARS = "3y",
  ONE_YEAR = "1y",
  NINE_MONTHS = "270d",
  SIX_MONTHS = "180d",
  NINETY_DAYS = "90d",
  THIRTY_DAYS = "30d",
  SEVEN_DAYS = "7d",
  ONE_DAY = "1d",
  TWELVE_HOURS = "12hr",
  SIX_HOURS = "6hr",
}

// Available data types
enum HistoricalDataType {
  MONTHLY_VOTES = "monthly_votes",
  TOTAL_VOTES = "total_votes",
  SERVER_COUNT = "server_count",
  SHARD_COUNT = "shard_count",
}

getBotRecent(botId: string): Promise<RecentDataResponse>

// Example
const recent = await client.getBotRecent("583807014896140293");

getRankings(options: RankingsRequest): Promise<RankingsResponse>

// Example
const rankings = await client.getRankings({
  sortBy: "monthly_votes_rank",
  sortMethod: "desc",
  limit: 250, // Optional, defaults to 100
});

Response Types

interface BotData {
  id: string;
  name: string;
  server_count: number;
  monthly_votes: number;
  total_votes: number;
  // ... and more
}

interface RecentDataResponse {
  hourlyData: RecentData[];
  dailyData: RecentData[];
}

interface RankingsResponse {
  totalBotCount: number;
  data: RankingsData[];
}

Error Handling

Basic
Advanced

try {
  await client.getBot("invalid-id");
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log("Rate limited, try again later");
  } else if (error instanceof TopStatsError) {
    console.error("API Error:", error.message);
  }
}

try {
  const bot = await client.getBot("invalid-id");
} catch (error) {
  switch(true) {
    case error instanceof RateLimitError:
      // Handle rate limiting
      console.log("Rate limited, retry after:", error.retryAfter);
      break;
    case error instanceof TopStatsError:
      // Handle API errors
      console.error("API Error:", error.message, error.code);
      break;
    default:
      // Handle unexpected errors
      console.error("Unknown error:", error);
  }
}

Rate Limits

The API implements rate limiting to ensure fair usage. For detailed information about rate limits and best practices, please refer to our rate limit documentation.