JavaScript
Community maintained Node.js client for the topstats.gg API.
Welcome to the community maintained Node.js client for the Topstats.gg API.
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",
}
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
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.
top-stats/javascript-sdk
0