TopggEx.Api (topgg_ex v0.1.6)

View Source

Top.gg API Client for posting stats and fetching data.

This module provides a comprehensive client for interacting with the Top.gg API, allowing you to post bot statistics, retrieve bot information, check votes, and more.

Examples

iex> {:ok, api} = TopggEx.Api.new("your_topgg_token_here")
iex> {:ok, _stats} = TopggEx.Api.post_stats(api, %{server_count: 100})
{:ok, %{server_count: 100}}

Configuration

Before using this module, ensure you have a Finch instance running in your application supervision tree:

children = [
  {Finch, name: :topgg_finch}
]

See also

Summary

Types

api_options()
bot_info()
bot_stats_response()
bots_query()
bots_response()
post_stats_body()
short_user()
snowflake()
t()
user_info()

Functions

get_bot(api, id)

Gets bot information from Top.gg.

get_bots(api, query \\ nil)

Gets a list of bots from Top.gg.

get_stats(api)

Gets your bot's statistics from Top.gg.

get_user(api, id)

Gets user information from Top.gg.

get_votes(api, page \\ nil)

Gets recent unique users who have voted for your bot.

has_voted(api, id)

Checks whether or not a user has voted in the last 12 hours.

is_weekend(api)

Checks whether or not the weekend multiplier is active.

new(token, options \\ %{})

Creates a new Top.gg API client instance.

post_stats(api, stats)

Posts bot statistics to Top.gg.

Types

api_options()

@type api_options() :: %{
  optional(:finch_name) => atom(),
  optional(:base_url) => String.t()
}

bot_info()

@type bot_info() :: map()

bot_stats_response()

@type bot_stats_response() :: %{
  optional(:server_count) => non_neg_integer(),
  :shards => [non_neg_integer()],
  optional(:shard_count) => non_neg_integer()
}

bots_query()

@type bots_query() :: %{
  optional(:limit) => non_neg_integer(),
  optional(:offset) => non_neg_integer(),
  optional(:search) => String.t() | map(),
  optional(:sort) => String.t(),
  optional(:fields) => [String.t()] | String.t()
}

bots_response()

@type bots_response() :: %{
  results: [bot_info()],
  limit: non_neg_integer(),
  offset: non_neg_integer(),
  count: non_neg_integer(),
  total: non_neg_integer()
}

post_stats_body()

@type post_stats_body() :: %{
  :server_count => non_neg_integer() | [non_neg_integer()],
  optional(:shard_count) => non_neg_integer(),
  optional(:shards) => [non_neg_integer()],
  optional(:shard_id) => non_neg_integer()
}

short_user()

@type short_user() :: %{username: String.t(), id: snowflake(), avatar: String.t()}

snowflake()

@type snowflake() :: String.t()

t()

@type t() :: %TopggEx.Api{base_url: String.t(), finch_name: atom(), token: String.t()}

user_info()

@type user_info() :: map()

Functions

get_bot(api, id)

@spec get_bot(t(), snowflake()) :: {:ok, bot_info()} | {:error, any()}

Gets bot information from Top.gg.

Returns {:ok, bot_info} on success, or {:error, reason} on failure.

Parameters

  • api - API client instance
  • id - Bot ID (snowflake)

Examples

iex> {:ok, bot} = TopggEx.Api.get_bot(api, "461521980492087297")
{:ok, %{"id" => "461521980492087297", "username" => "Shiro", ...}}

get_bots(api, query \\ nil)

@spec get_bots(t(), bots_query() | nil) :: {:ok, bots_response()} | {:error, any()}

Gets a list of bots from Top.gg.

Returns {:ok, bots_response} on success, or {:error, reason} on failure.

Parameters

  • api - API client instance
  • query - Optional query parameters

Examples

# Finding by properties
iex> {:ok, response} = TopggEx.Api.get_bots(api, %{
...>   search: %{username: "shiro"}
...> })
{:ok, %{results: [%{"id" => "461521980492087297", "username" => "Shiro", ...}], ...}}

# Restricting fields
iex> {:ok, response} = TopggEx.Api.get_bots(api, %{
...>   fields: ["id", "username"]
...> })
{:ok, %{results: [%{"id" => "461521980492087297", "username" => "Shiro"}], ...}}

get_stats(api)

@spec get_stats(t()) :: {:ok, bot_stats_response()} | {:error, any()}

Gets your bot's statistics from Top.gg.

Returns {:ok, stats} on success, or {:error, reason} on failure.

Parameters

  • api - API client instance

Examples

iex> {:ok, stats} = TopggEx.Api.get_stats(api)
{:ok, %{server_count: 28199, shard_count: 5, shards: [5000, 5000, 5000, 5000, 8199]}}

get_user(api, id)

@spec get_user(t(), snowflake()) :: {:ok, user_info()} | {:error, any()}

Gets user information from Top.gg.

Returns {:ok, user_info} on success, or {:error, reason} on failure.

Deprecated

This function is deprecated and no longer supported by Top.gg API v0.

Parameters

  • api - API client instance
  • id - User ID (snowflake)

Examples

iex> {:ok, user} = TopggEx.Api.get_user(api, "205680187394752512")
{:ok, %{"id" => "205680187394752512", "username" => "Xignotic", ...}}

get_votes(api, page \\ nil)

@spec get_votes(t(), non_neg_integer() | nil) ::
  {:ok, [short_user()]} | {:error, any()}

Gets recent unique users who have voted for your bot.

Returns {:ok, [users]} on success, or {:error, reason} on failure.

Parameters

  • api - API client instance
  • page - Optional page number (each page has at most 100 voters)

Examples

iex> {:ok, voters} = TopggEx.Api.get_votes(api)
{:ok, [%{username: "Xignotic", id: "205680187394752512", avatar: "https://..."}, ...]}

iex> {:ok, voters} = TopggEx.Api.get_votes(api, 2)
{:ok, [%{username: "iara", id: "395526710101278721", avatar: "https://..."}, ...]}

has_voted(api, id)

@spec has_voted(t(), snowflake()) :: {:ok, boolean()} | {:error, any()}

Checks whether or not a user has voted in the last 12 hours.

Returns {:ok, boolean} on success, or {:error, reason} on failure.

Parameters

  • api - API client instance
  • id - User ID (snowflake)

Examples

iex> {:ok, voted?} = TopggEx.Api.has_voted(api, "205680187394752512")
{:ok, true}

is_weekend(api)

@spec is_weekend(t()) :: {:ok, boolean()} | {:error, any()}

Checks whether or not the weekend multiplier is active.

Returns {:ok, boolean} on success, or {:error, reason} on failure.

Parameters

  • api - API client instance

Examples

iex> {:ok, is_weekend?} = TopggEx.Api.is_weekend(api)
{:ok, false}

new(token, options \\ %{})

@spec new(String.t(), api_options()) :: {:ok, t()} | {:error, String.t()}

Creates a new Top.gg API client instance.

Returns :ok with the API client struct, or {:error, reason} if the token is malformed.

Parameters

  • token - Your Top.gg API token
  • options - Optional configuration map

Options

  • :finch_name - Name of the Finch instance to use (default: :topgg_finch)
  • :base_url - Base URL for the API (default: "https://top.gg/api")

Examples

iex> {:ok, api} = TopggEx.Api.new("your_token_here")
iex> {:ok, api} = TopggEx.Api.new("your_token_here", %{finch_name: :my_finch})

post_stats(api, stats)

@spec post_stats(t(), post_stats_body()) :: {:ok, post_stats_body()} | {:error, any()}

Posts bot statistics to Top.gg.

Returns {:ok, stats} on success, or {:error, reason} if the server count is missing, invalid, or the API request fails.

Parameters

  • api - API client instance
  • stats - Stats map containing at least :server_count

Examples

# Posting server count as an integer
iex> {:ok, stats} = TopggEx.Api.post_stats(api, %{server_count: 28199})
{:ok, %{server_count: 28199}}

# Posting with shards (server_count as array)
iex> {:ok, stats} = TopggEx.Api.post_stats(api, %{server_count: [1000, 2000, 3000]})
{:ok, %{server_count: [1000, 2000, 3000]}}

# Posting with additional shard information
iex> {:ok, stats} = TopggEx.Api.post_stats(api, %{
...>   server_count: 500,
...>   shard_id: 0,
...>   shard_count: 5
...> })
{:ok, %{server_count: 500, shard_id: 0, shard_count: 5}}