Common Questions

This page aims to answer some common questions users have about the Hypixel PublicAPI.

Table of Contents

1. How do I get a player's rank prefix?
2. How do I convert those long numbers to dates?
3. How do I check if a player is online?
4. How do I find a player's network level?

How do I get a player's rank prefix?

e.g. [GM], [OWNER], [YOUTUBER], [VIP+], etc

In the player endpoint, a player's rank is actually split up across 5 different fields. When displaying a player's rank, these fields take precedence in the following order:

1. player.prefix - If this field is set, its value overrides the player's normal rank prefix

   1. e.g. A prefix of §c[OWNER] overrides the default ADMIN prefix

2. player.rank - The player's special rank

   1. ADMIN, GAME_MASTER, or YOUTUBER

3. player.monthlyPackageRank - The player's subscription-based rank

   1. Currently only SUPERSTAR for MVP++ players

4. player.newPackageRank - The player's post-EULA lifetime rank

   1. VIP, VIP_PLUS, MVP or MVP_PLUS

5. player.packageRank - The player's pre-EULA lifetime rank

   1. Same values as player.newPackageRank
   2. Pre-eula ranks give players who bought ranks before August 1st 2014 certain ingame advantages that are no longer sold with ranks (like coin boosters, kits, etc)

NOTE:
If any of the above fields have the value NONE or NORMAL, they should be treated as if they didn't exist. The only exception is prefix, which should always be displayed literally.

Other Rank-Related Fields

• player.monthlyRankColor - For players with MVP++, this determines whether they have an AQUA tag or the normal GOLD tag

  • If this field is not present, defaults to GOLD

• player.rankPlusColor - For players with MVP+ or MVP++, this determines what color their +s are

  • This field should contain the capitalized version of a Minecraft color's name. For all possible values, see this table
  • If this field is not present, defaults to RED

• player.mostRecentMonthlyPackageRank - The player's most recent subscription-based rank

  • If this field is present, it means that the user has had the MVP++ rank before
  • If this field is present, it should only ever contain SUPERSTAR as of now

• player.buildTeam - Whether or not a player is on the Hypixel Build Team
  player.buildTeamAdmin - Whether or not the player is an administrator on the Hypixel Build Team

  • Both are likely only used for avatar frames on the forums
  • If either of these fields are not present, they default to false

How do I convert those long numbers to dates?

ie 1590849084000 ==> Saturday, May 30, 2020 2:31:24 PM

In the API, fields related to dates or times will typically be stored as some pretty-big looking numbers (for example, player.lastLogin, guild.created, guild.members[i].joined). These numbers are timestamps that represent how many milliseconds have passed since the Unix epoch, or January 1, 1970 at 00:00:00 UTC (see here for more info).
How exactly you convert these timestamps to readable dates depends on the language, but most modern languages have APIs capable of doing this. For example:

• Java: new Date(long milliseconds)
• JavaScript: new Date(milliseconds)
• Python: datetime.datetime.fromtimestamp(milliseconds // 1000.0)
• etc

How do I check if a player is online?

The old way of checking if a player was online was to use the player endpoint's player.lastLogin and player.lastLogout values; more specifically, if lastLogin > lastLogout then the player is online. The problem with this is that those fields may not be present for staff, youtubers, and players who have not logged in recently.
As of 9e18c01 though, we now have a status endpoint which allows you to check the online status of any player simply by looking at the session.online value. If you would prefer not to send an extra request just to check online status, the old method still works most of the time. However, the new method is more reliable and also provided information like the player's current game and mode.

NOTES:

• Players have the ability to hide this information in the API, so be aware that if session.online is false, they could actually be online.
• You can check if a player has hidden their session status by checking player.settings.apiSession (in the player endpoint). If that field is false, then they have hidden their session status in the API. If it does not exist, assume it is set to true.

How do I find a player's network level?

Currently, the player endpoint does not provide the player's level. However, it can be calculated from a player's network experience, which can be found under player.networkExp. The formula for calculating network level from network experience is as follows:

The integer part of the result represents their current network level and the decimal represents their progress on their current level (ie 389.42 means the player's current level is 389 and they are 42% of the way to level 390). We can also switch that equation around to find the total experience needed to reach a certain level:

TODO

• How do I calculate guild level?