API Reference

The following section outlines the API of topggpy.

Client

class topgg.DBLClient(bot: discord.client.Client, token: str, autopost: bool = False, post_shard_count: bool = False, autopost_interval: Optional[float] = None, **kwargs: Any)[source]

Represents a client connection that connects to Top.gg. This class is used to interact with the Top.gg API.

Parameters

  • bot (discord.Client) – An instance of a discord.py Client object.

  • token (str) – Your bot’s Top.gg API Token.

  • autopost (bool) – Whether to automatically post bot’s guild count every 30 minutes. This will dispatch on_autopost_success() (or on_autopost_error() in case of an error).

  • post_shard_count (bool) – Whether to post the shard count on autopost. Defaults to False.

  • autopost_interval (Optional[int]) – Interval used by autopost to post server count automatically, measured in seconds. Defaults to 1800 (30 minutes) if autopost is True, otherwise None.

  • **session (aiohttp.ClientSession) – An aiohttp session to use for requests to the API.

property guild_count: int

Gets the guild count from the provided Client object.

async get_weekend_status() → bool[source]

This function is a coroutine.

Gets weekend status from Top.gg.

Returns

weekend status – The boolean value of weekend status.

Return type

bool

async post_guild_count(guild_count: Optional[Union[int, List[int]]] = None, shard_count: Optional[int] = None, shard_id: Optional[int] = None) → None[source]

This function is a coroutine.

Posts your bot’s guild count and shards info to Top.gg.

Parameters

  • guild_count (Optional[Union[int, List[int]]]) – Number of guilds the bot is in. Applies the number to a shard instead if shards are specified. If not specified, length of provided client’s property .guilds will be posted.

  • shard_count (Optional[int]) – The total number of shards.

  • shard_id (Optional[int]) – The index of the current shard. Top.gg uses 0 based indexing for shards.

async get_guild_count(bot_id: Optional[int] = None) → topgg.types.BotStatsData[source]

This function is a coroutine.

Gets a bot’s guild count and shard info from Top.gg.

Parameters

bot_id (int) – ID of the bot you want to look up. Defaults to the provided Client object.

Returns

stats – The guild count and shards of a bot on Top.gg.

Return type

BotStatsData

async get_bot_votes() → List[topgg.types.BriefUserData][source]

This function is a coroutine.

Gets information about last 1000 votes for your bot on Top.gg.

Note

This API endpoint is only available to the bot’s owner.

Returns

users – Users who voted for your bot.

Return type

List[BriefUserData]

async get_bot_info(bot_id: Optional[int] = None) → topgg.types.BotData[source]

This function is a coroutine.

Gets information about a bot from Top.gg.

Parameters

bot_id (int) – ID of the bot to look up. Defaults to the provided Client object.

Returns

bot info – Information on the bot you looked up. Returned data can be found here.

Return type

BotData

async get_bots(limit: int = 50, offset: int = 0, sort: Optional[str] = None, search: Optional[Dict[str, Any]] = None, fields: Optional[List[str]] = None) → topgg.types.DataDict[str, Any][source]

This function is a coroutine.

Gets information about listed bots on Top.gg.

Parameters

  • limit (int) – The number of results to look up. Defaults to 50. Max 500 allowed.

  • offset (int) – The amount of bots to skip. Defaults to 0.

  • sort (str) – The field to sort by. Prefix with - to reverse the order.

  • search (Dict[str, Any]) – The search data.

  • fields (List[str]) – Fields to output.

Returns

bots – Info on bots that match the search query on Top.gg.

Return type

DataDict

async get_user_info(user_id: int) → topgg.types.UserData[source]

This function is a coroutine.

Gets information about a user on Top.gg.

Parameters

user_id (int) – ID of the user to look up.

Returns

user data – Information about a Top.gg user.

Return type

UserData

async get_user_vote(user_id: int) → bool[source]

This function is a coroutine.

Gets information about a user’s vote for your bot on Top.gg.

Parameters

user_id (int) – ID of the user.

Returns

vote status – Info about the user’s vote.

Return type

bool

async generate_widget(options: topgg.types.WidgetOptions) → str[source]

This function is a coroutine.

Generates a Top.gg widget from the provided WidgetOptions object.

Parameters

options (WidgetOptions) – A WidgetOptions object containing widget parameters.

Returns

widget – Generated widget URL.

Return type

str

async close() → None[source]

This function is a coroutine.

Closes all connections.

Event reference

topgg.on_autopost_success()

Called when autopost posts server count successfully on Top.gg.

topgg.on_autopost_error(exception)

Called when autopost raises an exception during server count posting.

Parameters

exception (Exception) – The raised exception object.

topgg.on_dbl_vote(data)

Called when someone votes for your bot on Top.gg.

Parameters

data (BotVoteData) – The data model containing bot vote information.

Example:

@bot.event
async def on_dbl_vote(data):
    print(data)
topgg.on_dsl_vote(data)

Called when someone votes for your server on Top.gg.

Parameters

data (ServerVoteData) – The data model containing server vote information.

Example:

@bot.event
async def on_dsl_vote(data):
    print(data)