API Reference

The following section outlines the API for PyPixel.

class AchievementData(data, cached)

New in version 0.1.9.

Represents Hypixel achievement data.

Parameters

data (dict) – The raw data from the API.
cached (bool) – Whether or not the data was retrieved from the cache.

raw: The raw data from the API.

cached: Whether or not the data was retrieved from the cache.

last_updated: The date and time the achievements were last updated.

games: A list of AchievementGame.

class AchievementGame(name, data)

New in version 0.1.9.

Represents a game with achievements.

Parameters

name (str) – The name of the game.
data (dict) – The game’s achievement data.

name: The game’s name.

total_points: The total amount of achievement points you can earn in the game.

one_time: A list of OneTime.

tiered: A list of Tiered.

class Achievement(data)

New in version 0.1.9.

Represents a Hypixel achievement.

Parameters: data (dict) – The achievement’s data.

name: The achievement’s name.

description: The achievement’s description.

class OneTime(data)

New in version 0.1.9.

Represents a one-time achievement.

This inherits from Achievement.

Parameters: data (dict) – The achievement’s data.

points: The amount of achievement points the achievement is worth.

percent_unlocked_game: The percent of players who played the game the achievement belongs to that have it.

percent_unlocked_global: The percent of players across the network that have the achievement.

class Tiered(data)

New in version 0.1.9.

Represents a tiered achievement.

This inherits from Achievement.

Parameters: data (dict) – The achievement’s data.

tiers: A list of AchievementTier.

class AchievementTier(data)

New in version 0.1.9.

Represents an achievement tier in a tiered achievement.

Parameters: data (dict) – The tier’s data.

tier: The Tier’s tier (if that makes sense).

points: The amount of points the tier is worth.

amount: The amount of x you have to get for this tier.

class Auction(data, cached, hypixel)

New in version 0.2.0.

Represents an auction on the Skyblock Auction House.

Parameters

data (dict) – The auction’s data from the API.
cached (bool) – Whether or not the data was retrieved from the cache.
hypixel (Hypixel) – The Hypixel class used to make the request.

raw: The auction’s raw data from the API.

cached: Whether or not the data is from the cache.

id: The auction’s ID.

auctioneer: The auctioneer’s UUID.

auctioneer_profile: The auctioneer’s SkyBlock profile ID.

auctioneer_coop_members: The members of the auctioneer’s coop.

started: The date and time that the auction started.

end: The date and time that the auction ends at.

item: The name of the item being auctioned.

lore: The lore of the item being auctioned.

stripped_lore: The item’s lore, but stripped of formatting.

extra: Some extra data on the item being auctioned.

category: The category the item is in.

tier: The item’s tier.

starting_bid: The starting bid for the auction. If the auction is a BIN auction, this is the price of the item.

nbt_data: The NBT data for the item.

claimed: Whether or not the auction has been claimed.

claimed_bidders: The bidders that have claimed their coins/items from the auction.

highest_bid: The highest bid on the item. If nobody has bid, this will be 0. For BIN auctions, this will always be 0.

bin: Whether or not the auction is a BIN auction.

bids: A list of bids on the item. For BIN auctions, this will always be an empty list.

get_auctioneer()

This function is a coroutine.

Gets the auctioneer’s player object.

Raises: PlayerNotFound – The player couldn’t be found for some reason.
Returns: The player from the API.
Return type: Player

class AuctionPage(data, cached, hypixel)

New in version 0.2.0.

Represents a page of Skyblock auctions from the Hypixel API.

Parameters

data (dict) – The raw data from the API.
cached (bool) – Whether or not the data was retrieved from the cache.
hypixel (Hypixel) – The Hypixel class used to make the request.

raw: The raw data from the API.

page: The page number.

total_pages: The total number of pages.

total_auctions: The total number of auctions.

last_updated: The date and time that the page was last updated.

auctions: A list of Auction.

class Cache(clear_cache_after)

Changed in version 0.2.0.

A class used for caching data returned from the api

Parameters: clear_cache_after (int) – How long data should stay cached for.

cleanCache()

This function is a coroutine.

Cleans the cache.

getFromCache(url)

This function is a coroutine.

Gets the cached url from the cache.

Returns: The cached response. Can also be None if the response is not cached.
Return type: Optional[dict]

cache(url, data)

This function is a coroutine.

Caches a response.

Parameters

url (str) – The URL the request was sent to.
data (dict) – The response as a dict.

class Guild(data, cached, hypixel)

Represents a Hypixel guild.

Parameters

data (dict) – The raw data from the API.
cached (bool) – Whether or not the data was retrieved from the cache.
hypixel (Hypixel) – The Hypixel class used to make the request.

get_member(member)

This function is a coroutine.

Gets a Player object from a GuildMember

Parameters: member (GuildMember) – The member you want a player object from.
Returns: The retrieved player.
Return type: Player

class GuildMember(memberdata)

Represents a Hypixel guild member.

Parameters: memberdata (dict) – A dict containing the member’s data.

uuid: The player’s UUID.

rank: The player’s guild rank.

joined: The date the player joined.

quest_participation: The player’s quest participation.

xp_history: The player’s guild XP history.

class GuildRank(rankdata)

Represents a Hypixel guild rank.

Parameters: rankdata (dict) – A dict containing the rank’s data.

name: The rank’s name.

default: A boolean indicating if the rank is the default rank.

tag: The rank’s tag.

created: The date/time the rank was created.

priority: The rank’s priority in the guild’s rank heirarchy.

class Hypixel(*, api_key, base_url, clear_cache_after, user_agent)

The main class that will be used for requesting information from the Hypixel API.

Changed in version 0.2.0: Removed the validate kwarg and added a user_agent kwarg.

Added the get_auctions method.

Updated _send.

Parameters

api_key (str) – Your Hypixel API key.
base_url (Optional[str]) – The base URL for the Hypixel API. Defaults to https://api.hypixel.net/.
clear_cache_after (Optional[int]) – How often the cache should clear in seconds.
user_agent (Optional[str]) – The user agent to use for requests. This is formatted with your Python version and aiohttp version.

get_player(uuid)

This function is a coroutine.

Gets a player from the Hypixel API using the /player endpoint.

Parameters: uuid (str) – The UUID you are requesting player data for.
Raises: PlayerNotFound – The player couldn’t be found.
Returns: The player from the API.
Return type: Player

get_guild(arg, by)

This function is a coroutine.

Gets a guild from the Hypixel API using the /guild endpoint.

Parameters

arg (str) – The guild ID or name, or a player UUID.
by (Literal['id', 'name', 'player']) – The type of ‘arg’ you provided.

Raises

TypeError – Invalid ‘by’ parameter.
GuildNotFound – The guild was not found.

Returns

The guild from the API.

Return type

Guild

get_profiles(uuid)

This function is a coroutine.

Gets a player’s SkyBlock profiles from the Hypixel API using the /skyblock/profiles endpoint.

Parameters: uuid (str) – The player’s UUID.
Raises: PlayerNotFound – The player’s profiles could not be found.
Returns: A list containing the player’s profiles.
Return type: List[SkyBlockProfile]

get_auctions(page)

This function is a coroutine.

New in version 0.2.0.

Gets a page of auctions from the Hypixel API.

Note

This does not use your API Key.

Parameters: page (int) – The page to request.
Returns: The page of auctions.
Return type: AuctionPage

get_key(key=None)

New in version 0.1.8.

This function is a coroutine.

Gets information on an API Key using the /key endpoint.

Parameters: key (Optional[str]) – The API key you want information for. Defaults to the API key you provided on initialization of the class.
Raises: KeyNotFound – The key provided does not exist.
Returns: The data on the API Key
Return type: APIKey`

get_achievements()

New in version 0.1.9.

This function is a coroutine.

Gets every achievement on the Hypixel Network using the /resources/achievements endpoint.

Note

This does not use your API Key.

Raises: PyPixelError – The request failed for some reason.
Returns: An object containing every achievement.
Return type: AchievementData

get_name(uuid)

This function is a coroutine.

Gets a player’s name from their UUID. This does not use the Hypixel API.

Parameters: uuid (str) – The player’s UUID.
Raises: PlayerNotFound – The UUID is invalid.
Returns: The player’s name.
Return type: str

get_uuid(name)

This function is a coroutine.

Get’s a player’s UUID from their name.

Parameters: name (str) – The player’s name.
Raises: PlayerNotFound – The name is invalid.
Returns: The player’s UUID.
Return type: str

_send(url, *, headers, authenticate)

This function is a coroutine.

Changed in version 0.2.0: Added a header kwarg, as well as the authenticate kwarg.

This will also add the User-Agent header to requests.

Sends a request to the specified url.

Parameters

url (str) – The URL the request will be sent to.
headers (Optional[dict]) – The request headers. Defaults to an empty dict.
authenticate (Optional[bool]) – Whether or not to provide an Api-Key header with your API Key. If not provided, will provide the Api-Key header based on the url the request is being sent to.

Raises

APIError – The API returned a 500 range status code.
NotFound – The API returned a 404 status code.
ClientError – The API returned a 400 range status code.

Returns

The json data from the API, and a boolean value indicating whether or not the data was retrieved from the cache.

Return type

dict, bool

APIKey(key_data, cached, hypixel):

New in version 0.1.8.

Represents an API Key.

Parameters

key_data (dict) – The raw key data from the API.
cached (bool) – The raw key data from the API.
hypixel (Hypixel) – The raw key data from the API.

cached: Indicates whether or not the data was retrieved from the cache.

key: The API Key

owner: The key’s owner.

request_past_minute: The amount of requests made with the key in the past minute.

total_requests: The total amount of requests made with the key.

get_owner()

This function is a coroutine.

Gets the owner pf the key as a Player object.

Returns: The key’s owner.
Return type: Player

class Player(data, cached, hypixel)

Represents a Hypixel player.

Parameters

data (dict) – The raw data from the API.
cached (bool) – Whether or not the data was retrieved from the cache.
hypixel (Hypixel) – The Hypixel class used to make the request.

class PlayerStats(data)

Base class for a player’s statistics.

Parameters: data (dict) – The raw player data from the API.

skywars: The player’s SkyWars statistics.

class Firework(firework)

Represents a firework. Interesting, right?

Parameters: firework (dict) – The raw firework data.

class SkyWarsStats(playerstats)

Base class for a player’s SkyWars stats.

Parameters: playerstats (dict) – The raw player stats data from the API.

class Overall(stats)

The player’s overall SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Solo(stats)

The player’s solo SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Normal(stats)

The player’s solo normal SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Insane(stats)

The player’s solo insane SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Teams(stats)

The player’s teams SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Normal(stats)

The player’s teams normal SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Insane(stats)

The player’s teams insane SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Mega(stats)

The player’s mega SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Ranked(stats)

The player’s ranked SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Lab(stats)

The player’s laboratory SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Solo(stats)

The player’s lab solo SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class Teams(stats)

The player’s lab teams SkyWars stats.

Parameters: stats (dict) – The raw SkyWars stats data from the API.

class SkyBlockProfile(profiledata, cached, hypixel)

Represents a SkyBlock profile.

Parameters

profiledata (dict) – The profile’s data from the API.
cached (bool) – A boolean indicating if the profile’s data was retrieved from the cache.
hypixel (Hypixel) – The Hypixel class used to get the profile.

class Profilemember(uuid, memberdata, hypixel)

Represents a member in a SkyBlock profile.

Parameters

uuid (str) – The member’s UUID.
memberdata (dict) – The member’s data in the profile.
hypixel (Hypixel) – The Hypixel class used to get the profile.

get_player()

This function is a coroutine.

Gets the member’s player object.

Raises: PlayerNotFound – The player couldn’t be found for some reason.
Returns: The player from the API.
Return type: Player

class SkyBlockStats(stats)

Represents a player’s SkyBlock Statistics.

Parameters: stats (dict) – The player’s stats from their memberdata retrieved from the API.

class SkyBlockObjective(objective_name, objective_data)

Represents a SkyBlock Objective.

Parameters

objective_name (str) – The name of the objective.
objective_data (dict) – The objective’s data.

name: The name of the objective.

status: The objective’s status.

progress: The objective’s progress.

completed_at: The objective’s completion date/time. Can also be None if not completed.

class SkyBlockQuest(quest_name, quest_data)

Represents a SkyBlock quest.

Parameters

quest_name (str) – The name of the quest.
quest_data (dict) – The quest’s data.

name: The name of the quest.

status: The quest’s status.

activated_at: The quest’s activation date/time.

completed_at: The quest’s completion date/time. Can also be None if not completed.

class SkyBlockSlayer(slayer, slayer_data)

Represents a SkyBlock slayer.

Parameters

slayer (str) – The name of the slayer.
slayer_data (dict) – The slayer’s data.

slayer: The name of the slayer.

claimed_levels: The player’s claimed levels for a slayer.

xp: The player’s slayer xp.

level: The player’s slayer level.

class SkyBlockPet(pet_data)

Represents a SkyBlock pet.

Parameters: pet_data (dict) – The pet’s data.

uuid: The pet’s UUID, I guess.

type: The pet’s type.

xp: The pet’s XP.

active: A boolean indicating whether or not the pet is active.

tier: The pet’s tier

held_item: The item the pet is holding.

candy_used: The candy used on the pet.

skin: The pet’s skin.

Exceptions

Changed in version 0.1.8: These exceptions are now actually used.

Oh also the parameters changed.

exception PyPixelError(*args): Base exception class for PyPixel.

exception HTTPException

Base exception class for when the API returns an http error code.

Parameters

status_code (int) – The status code returned by the API.
reason (str) – The reason the request failed.
url (str) – The url the request was sent to.
data (Optional[dict]) – The JSON data returned from the request, if any.

exception APIError

Exception that’s thrown when the API returns a 500 range status code.

Parameters

status_code (int) – The status code returned by the API.
reason (str) – The reason the request failed.
url (str) – The url the request was sent to.
data (Optional[dict]) – The JSON data returned from the request, if any.

exception ClientError

Exception that’s thrown when the API returns a 400 range status code.

Parameters

status_code (int) – The status code returned by the API.
reason (str) – The reason the request failed.
url (str) – The url the request was sent to.
data (Optional[dict]) – The JSON data returned from the request, if any.

exception NotFound

Exception thats thrown when the API returns a 404 status code.

Parameters

reason (str) – The reason the request failed.
url (str) – The url the request was sent to.
data (Optional[dict]) – The JSON data returned from the request, if any.

exception PlayerNotFound(reason)

Exception thats thrown when a player couldn’t be found.

Parameters

reason (str) – The reason the player couldn’t be found.
url (str) – The url the request was sent to.
data (Optional[dict]) – The JSON data returned from the request, if any.

exception GuildNotFound(reason)

Exception thats thrown when a guild couldn’t be found.

Parameters

reason (str) – The reason the guild couldn’t be found.
url (str) – The url the request was sent to.
data (Optional[dict]) – The JSON data returned from the request, if any.

exception KeyNotFound(reason, url, data)

New in version 0.1.8.

Exception thats thrown when an API Key couldn’t be found.

Parameters

reason (str) – The reason the key couldn’t be found.
url (str) – The url the request was sent to.
data (Optional[dict]) – The JSON data returned from the request, if any.