Examples

Achievements

A simple example that shows how to build achievement data.

# This example requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            player = await client.player('gamerboy80')
            for achievement in player.achievements:
                achievement = hypixel.Achievement.from_type(achievement)
                if achievement:
                    print(achievement.name)
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Ban Info

A simple example that shows how to get watchdog and staff ban info.

# This example requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            print(await client.bans())
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Bedwars Lobby

A simple example showing how to display a full bedwars lobby username.

# This example requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            player = await client.player('gamerboy80')
            # Will display [None] as the rank if the player has no rank
            print(f'[{player.bedwars.level}✫] [{player.rank}] {player.name}')
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Caching

A simple example that shows how to use the cache.

# This example requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

import time

async def main():
    client = hypixel.Client('api-key', cache=True, cache_time=5)
    async with client:
        try:
            player = await client.player('gamerboy80')
            # Doesn't make any requests
            # Returns much faster than the first
            player = await client.player('gamerboy80')
            print(client.hypixel_cache_info)
            print(client.mojang_cache_info)
            time.sleep(5)
            # Makes new API requests
            player = await client.player('gamerboy80')
            client.clear_cache()
            # Makes new API requests
            player = await client.player('gamerboy80')
            client.clear_hypixel_cache()
            # Makes a new Hypixel API request
            # Doesn't make a new Mojang API request
            player = await client.player('gamerboy80')
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Converting Time

A simple example that shows how to convert the default time to other timezones.

# This example requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

try:
    # Python 3.9+
    from zoneinfo import ZoneInfo
except ImportError:
    # Python 3.8 (pip install backports.zoneinfo[tzdata])
    # This module also works for python 3.6, however hypixel.py does not
    from backports.zoneinfo import ZoneInfo

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            player = await client.player('gamerboy80')
            # Can be None if in game privacy settings are changed
            if player.last_login:
                # List possible timezones with
                # zoneinfo.available_timezones()
                new_york = ZoneInfo('America/New_York')
                # Convert UTC time to America/New_York time
                # (accounts for daylight savings)
                print(player.last_login.astimezone(new_york))
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

First Login

A simple example that shows how to get a player’s first login.

# This exmaple requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            player = await client.player('gamerboy80')
            print(player.first_login.strftime('%A, %b %d %Y'))
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Friends

A simple example that shows how to get and use player_friends data.

Note

Only shows friends the player is currently friends with.

Warning

Methods referenced in this example have been removed.

# This exmaple requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            # Sort sorts the friends list from earliest to latest
            friends = await client.player_friends('gamerboy80', sort=True)
            earliest = friends[0]
            name = await client.get_name(earliest.uuid)
            print(f'First friend: {name}')

            latest = friends[-1]
            name = await client.get_name(latest.uuid)
            print(f'Latest friend: {name}')

            amount = len(friends)
            print(f'Has {amount} friends')
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Guild Member

A simple example showing how to get a guild’s member.

# This example requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            guild = await client.guild_by_player('gamerboy80')
            # guild = await client.guild_by_name('jakeygoat')
            uuid = await client.get_uuid('gamerboy80')
            member = next((
                member for member in guild.members if member.uuid == uuid
            ), None)
            print(member)
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Guild

A simple example that shows how to get a guild’s info.

# This example requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            guild = await client.guild_by_player('gamerboy80')
            # guild = await client.guild_by_name('jakeygoat')
            print(guild.name)
            print(guild.tag)
            print(guild.level)
            print(guild.description)
            print(guild.created.strftime('%A, %b %d %Y'))
            for rank in guild.ranks:
                print(rank.name)
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Key

A simple example that shows how to get a key’s queries.

# This example requires an api key (obviously)

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client()
    async with client:
        try:
            print(await client.key('api-key'))
            # If you passed a key into the client, you can get its info
            # as follows:
            print(await client.key(client.keys[0]))
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Leaderboard

A simple example showing how to handle leaderboard models.

# This example requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

from uuid import UUID

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            leaderboards = await client.leaderboards()
            bedwars = leaderboards['BEDWARS']
            # Can also use bedwars[0] instead of next()
            level = next((
                lb for lb in bedwars if lb.title == 'Level'
            ), None)
            print(f'{level.prefix} {level.title}:')
            # Splices for top 10 instead of top 100
            for index, player in enumerate(level.leaders[:10]):
                # Requests from mojang's api
                print(f'#{index + 1} {await client.get_name(player)}')

            player = 'gamerboy80'
            uuid = await client.get_uuid(player)
            uuid = str(UUID(uuid))
            index = level.leaders.index(uuid)
            print(f'#{index + 1} {player}')

        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Multiple Contexts

A simple example that shows how to use the same Client instance with multiple contexts.

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client()
    async with client:
        "Do stuff here"

    # Opening a new context will open a new aiohttp.ClientSession while
    # keeping your previous Client attributes
    async with client:
        "Do more stuff here"

if __name__ == '__main__':
    asyncio.run(main())

No Context

A simple example that shows how to use hypixel.Client without a context manager.

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client()

    try:
        "Do stuff here"
    except HypixelException as error:
        print(error)

    # Make sure this is awaited before your script ends
    await client.close()

if __name__ == '__main__':
    asyncio.run(main())

Parkour

A simple example showing how to display a player’s parkour times.

# This example requires an api key

import hypixel
from hypixel import utils
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            player = await client.player('gamerboy80')
            parkour = player.parkour
            print(
                "Arcade: "
                f"completed on {parkour.arcade.completed.strftime('%A, %b %d %Y')} "
                # datetime.timedelta does not have its own strftime
                # function.
                f"in {utils.strfdelta(parkour.arcade.time)}"
            )

            # Loop through every ParkourLobby object
            for i, lobby in enumerate(parkour):
                if not lobby:
                    continue
                mode = parkour._modes[i]
                print(
                    f"{mode:<15} {utils.strfdelta(lobby.time):<10} {lobby.completed.year}"
                )

            # Compare another player's times
            # Kinda messy, but it shows the functionality
            # len() and subscripting[int] also work on Parkour objects,
            # however, len() always returns the total amount, even if
            # some (or all) attributes are None, so that subscripting 2
            # objects with the same index will always return the same
            # attribute.
            player2 = await client.player('technoblade')
            parkour2 = player2.parkour
            for i, (p1, p2) in enumerate(zip(parkour, parkour2)):
                if not p1 or not p2:
                    continue
                elif p1.time < p2.time:
                    print(f"{parkour._modes[i]}: {player.name} with {p1.time}")
                else:
                    print(f"{parkour._modes[i]}: {player2.name} with {p2.time}")
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Player Count

A simple example that shows how to get the current number of players.

# This exmaple requies an api key

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            print(client.player_count())
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())

Player Status

A simple example that shows how to get a player’s status.

# This example requires an api key

import hypixel
from hypixel import HypixelException
import asyncio

async def main():
    client = hypixel.Client('api-key')
    async with client:
        try:
            # Attributes can be False and None if in game privacy
            # settings are changed.
            print(await client.player_status('gamerboy80'))
        except HypixelException as error:
            print(error)

if __name__ == '__main__':
    asyncio.run(main())