hypixelez.hypixel_api module

class hypixelez.hypixel_api.HypixelClient(api_key, debug=True, base_url='https://api.hypixel.net/v2/skyblock/profile')[source]

Bases: object

HTTP client for the Hypixel SkyBlock API.

This client also supports resolving Minecraft usernames to UUIDs via Mojang API.

Parameters:: api_key (str)

fetch_profile_info(uuid, profile)[source]

Fetch full SkyBlock profile data and wrap it in SkyblockProfileData.

Parameters:

uuid (str) – Minecraft UUID.
profile (str) – SkyBlock profile id.

Returns:

A SkyblockProfileData instance with the raw API response and UUID.

Raises:

requests.RequestException – For network issues or non-2xx HTTP status.
Exception – If Hypixel returns success=false (API-level error).

Notes

On API-level errors the code currently raises a generic Exception. Consider introducing a custom exception type for better UX and docs.

get_profile_names_ids_by_id(uuid)[source]

Get available SkyBlock profiles for a player UUID.

Parameters:: uuid (str) – Minecraft UUID.
Returns:: A mapping {profile_name: profile_id}, where profile_name is the Hypixel “cute_name” (e.g. “Peach”), and profile_id is the profile id.
Raises:: requests.RequestException – If the underlying HTTP request fails.
Return type:: dict

Notes

This method currently assumes the response contains a "profiles" key.

get_uuid_by_name(name)[source]

Resolve a Minecraft username to a UUID using Mojang API.

The result is cached in-memory for the lifetime of the client.

Parameters:: name (str) – Minecraft username.
Returns:: The UUID string if found; otherwise None. Returns None also in case of network errors.
Return type:: str | None

Notes

This method currently swallows requests exceptions and returns None instead of raising.

class hypixelez.hypixel_api.SkyblockProfileData(raw_data, uuid)[source]

Bases: object

Wrapper around Hypixel SkyBlock profile JSON with convenience getters.

Most getter methods are “safe”: if the requested data is missing, they return a default value (usually 0 or an empty list) and log a warning.

get_cata_class_level(class_name)[source]

Get the dungeon class level.

Parameters:: class_name – Dungeon class id (e.g. “mage”, “berserk”, “archer”, “tank”, “healer”).
Returns:: Class level if present, otherwise 0.
Return type:: int

get_cata_class_xp(class_name)[source]

Get dungeon class XP progress within the current class level.

Parameters:: class_name – Dungeon class id (e.g. “mage”, “berserk”, “archer”, “tank”, “healer”).
Returns:: Current class level XP progress if present, otherwise 0.
Return type:: int

get_cata_level()[source]

Get the Catacombs level.

Returns:: Catacombs level if present, otherwise 0.
Return type:: int

get_cata_xp()[source]

Get Catacombs XP progress within the current Catacombs level.

Returns:: Current Catacombs level XP progress if present, otherwise 0.
Return type:: int

get_collection(collection_name)[source]

Get the amount collected for a specific collection.

Parameters:: collection_name (CollectionKey | str) – Collection key (e.g. “LOG”, “WHEAT”). Full list: CollectionKey.
Returns:: Collection amount if present, otherwise 0.
Return type:: int

get_global_level()[source]

Get the global SkyBlock level.

Returns:: Global level if present, otherwise 0.
Return type:: int

Notes

The current implementation derives level as experience // 100.

get_global_xp()[source]

Get XP progress within the current global SkyBlock level.

Returns:: Current global level XP progress if present, otherwise 0.
Return type:: int

Notes

The current implementation derives progress as experience % 100.

get_skill_current_level_xp(skill_name)[source]

Get XP progress within the current level for a given skill.

Parameters:: skill_name – Skill XP key (e.g. “SKILL_CARPENTRY”).
Returns:: Current level XP progress if present, otherwise 0.
Return type:: int

get_skill_level(skill_name)[source]

Get the current level for a given SkyBlock skill.

Parameters:: skill_name – Skill XP key (e.g. “SKILL_CARPENTRY”).
Returns:: Skill level if present, otherwise 0.
Return type:: int

get_slayer_level(slayer_name)[source]

Get the slayer level derived from claimed levels.

Parameters:: slayer_name – Slayer id (e.g. “zombie”, “spider”, “wolf”, …).
Returns:: Highest claimed slayer level if present, otherwise 0.
Return type:: int

get_slayer_stats(slayer_name)[source]

Get slayer boss kill statistics by tiers.

Parameters:: slayer_name – Slayer id (e.g. “zombie”, “spider”, “wolf”, …).
Returns:: A list of tier kill counts if present, otherwise an empty list.
Return type:: list

Notes

The current implementation iterates over keys inside the slayer dict and appends values for keys that contain "boss_kills_tier". If you need stable ordering (tier1..tierN), consider sorting keys.

get_slayer_stats_by_tier(slayer_name, tier)[source]

Get slayer boss kill count for a specific tier.

Parameters:

slayer_name – Slayer id (e.g. “zombie”, “spider”, “wolf”, …).
tier – Tier number (1-indexed). For example, tier=1 means “tier I”.

Returns:

Kill count for the requested tier if present, otherwise 0.

Return type:

int

Notes

If tier is out of range, the implementation will fall back to 0.

get_slayer_xp(slayer_name)[source]

Get total slayer XP for a specific slayer.

Parameters:: slayer_name – Slayer id (e.g. “zombie”, “spider”, “wolf”, …).
Returns:: Total slayer XP if present, otherwise 0.
Return type:: int