Skip to content
This repository has been archived by the owner. It is now read-only.
Java wrapper for the BotBlock API
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

This repository was moved

You can find the new repository and its content under BotBlock/JavaBotBlockAPI.
This repository is archived and issues/pull requests towards it will be either moved or ignored.

JavaBotBlockAPI is a continued and updated Java Wrapper for BotBlock, a website that makes it possible to update guild counts on multiple lists with one API.
This wrapper is a fork of BotBlock4J and was updated and improved to make it as userfriendly as possible.



You can install JavaBotBlockAPI through the following methods.
Make sure to replace {version} with the above shown version.


Put this code into your build.gradle:


    compile group: 'com.andre601', name: 'JavaBotBlockAPI', version: '{version}'


For maven use this code snipped:



To use the Wrapper you have to follow these steps.


In the below examples do I use a JDA instance called jda.
This will also work with ShardManager.

POST methods

You can post you guild counts to the different Botlists using the BotBlock API.

Creating an instance of BotBlockAPI

For posting your guild counts towards the BotBlock API you first need to create an instance of the BotBlockAPI class. To do this it's recommended to use BotBlockAPI.Builder().

Here is an example of how it could look like.

BotBlockAPI api = new BotBlockAPI.Builder()
    .addAuthToken("", "MySecretToken123")
    .addAuthToken("", "MySecretToken456")

Remember to use .build(); at the end to create the class.

Auto Posting

JavaBotBlockAPI allows you to post the guild counts automatically every X minutes. To do this, you first need to get an instance of the RequestHandler and then call .startAutoPosting(...).

Here is an example:

RequestHandler handler = new RequestHandler();

// api is the instance of the BotBlockAPI
handler.startAutoPosting(jda, api);

The delay in which you post the guild counts is set through the .setUpdateInterval(int) method in the BotBlockAPI.Builder().

Cancel auto posting

To cancel the auto posting just call .stopAutoPosting(); in the RequestHandler and it should cancel the scheduler.

Manually posting

There are methods that allow you to post the guild counts manually. To Post your guild counts, just call the .postGuilds(..., ...) method in the RequestHandler.

RequestHandler handler = new RequestHandler();

// api is the instance of the BotBlockAPI
handler.postGuilds(jda, api);

GET methods

Since version 2.0.0 of JavaBotBlockAPI can you get certain informations of a bot or the available Botlists on the BotBlock API.

All available Botlists

You can call .getBotlists() to receive a JSONObject with all available Botlists in the BotBlockAPI.

The returned JSONObject could look like this:

    "": {
        "api_docs": "",
        "api_post": "",
        "api_field": "server_count",
        "api_shard_id": null,
        "api_shard_count": null,
        "api_shards": "shards",
        "api_get": ""
    "": {
        "api_docs": "",
        "api_post": "",
        "api_field": "guild_count",
        "api_shard_id": "shard_id",
        "api_shard_count": "shard_count",
        "api_shards": null,
        "api_get": null

Single Botlist

Calling .getBotlist(String) returns a specific Botlist as JSONObject. For example does .getBotlist("") return the following JSONObject:

    "api_docs": "",
    "api_post": "",
    "api_field": "guild_count",
    "api_shard_id": "shard_id",
    "api_shard_count": "shard_count",
    "api_shards": null,
    "api_get": null

Complete Botinfo

Calling .getAll(...) returns a JSONObject from all the botlists and with some general information.

The JSONObject can look like this:

    "id": "123456789012345678",
    "name": "MyBot",
    "discriminator": "1234",
    "owners": [
    "server_count": 100,
    "invite": "",
    "list_data": {
        "": [
        "": [

<data> is the JSON that is returned by the provided Botlist meaning it's different for each site. name, owners, server_count and invite is based on the most common appearances of the data.

Botinfo from all Botlists

You can call .getBotInfos(...) to only receive the bot info from all the Botlists.

The returned JSONObject can look like this:

    "": [
    "": [

<data> is the JSON that is returned by the provided Botlist meaning it's different for each site.

Botinfo of a single site

With .getBotInfo(..., String) can you receive the info of a specific site. The returned data depends on the selected site and can be different for each one.


You can call .getOwners(...) to get the owners of a Bot from all the Botlists. The info is returned as JSONArray and is based on how often the info is provided by the botlists.


When you post the guild counts you could encounter certain Exceptions.
You can receive the following exceptions:

  • IOException
    The Request couldn't be performed properly. This can be f.e. the case when denies access (403).
  • RatelimitedException
    When we exceed the ratelimit of
    This shouldn't be the case with auto-posting since it has a minimum delay of 1 minute.
  • NullPointerException
    Thrown when sends an empty response, meaning something got messed up on their side.


Here are some useful links:

  • Site for which this wrapper was made.
    • API API documentation.
  • Wiki Contains additional information on how you can use JavaBotBlockAPI.
  • Javadocs Java documentation of the Wrapper.
  • BotBlock4J Original Wrapper from which this one originates.
You can’t perform that action at this time.