hypixel

README

hypixel

hypixel is a Hypixel API library for Go. It provides near full coverage of Hypixel's public API (see TODO below) in a lightweight package.

Some changes are made internally to try and keep the API consistent on the library's end, but the Hypixel api is very inconsistent so check the documentation if something looks like it should work, but doesn't.

Getting Started

• master

  • The latest stable release of Hypixel with the most stable API. You should probably use it for production tooling.

• working

  • The development branch. There may be rapid, breaking API changes. Bugs are fixed faster, but they may be more of them.

Installing

To get the latest stable release

go get github.com/t1ra/hypixel

But if you want to use working

cd $GOPATH/src/github.com/t1ra/hypixel
git checkout develop

Usage

1. Import the library into your project

import "github.com/t1ra/hypixel"

1. Create a new instance of the Hypixel struct. Creating a new instance requires an API key, which can be retrieved from in-game by running /uuid (or /uuid new).

hypixel, err := Hypixel.New(KEY)

1. Follow documentation and its examples to construct your application.

Documentation

As is the style of Go code, all structs and functions in Hypixel are documented in the source. This allows Godoc to automatically generate very useful documentation.

For documentation on methods

• 

And for documentation on structs

• 

There isn't any hand-written documentation just yet.

Contributing

Contributions, whether in the form of Pull Requests or Issues are encouraged. If you want to create a pull request, make sure you follow these guidelines:

• Open an issue describing the bug or feature.

• Fork the develop branch and make your changes.

• Follow predefined naming conventions and run go lint.

• Create and run a test and/or example (if applicable) for your changes.

• Create a pull request stating your changes with a link to the issue.

Testing

Completing Hypixel tests requires you supply an API. To do so, join Hypixel and type /uuid new, and add the key to a file called api_key in the root of the repository.

You'll also have to modify the Example ExampleKey()'s output from my UUID (d4acada6bc844dd384060bb77e207a7a) to whatever your UUID is.

TODO

• https://github.com/HypixelDev/PublicAPI/tree/master/Documentation/methods/skyblock
• There are probably naming inconsistencies, especially in automatically generated structs.

Thanks

Ashley McNamara for the Gopher above. Taken from https://github.com/ashleymcnamara/gophers.

Documentation

Overview

Package hypixel provides Golang bindings to the Hypixel API.

Index

• Constants
• type Hypixel
  • func New(apiKey string) (*Hypixel, error)
  • func (session *Hypixel) Achievements() (Achievements, error)
  • func (session *Hypixel) BanStats() (BanStats, error)
  • func (session *Hypixel) Boosters() (Boosters, error)
  • func (session *Hypixel) Challenges() (Challenges, error)
  • func (session *Hypixel) FindGuild(guild string) (string, error)
  • func (session *Hypixel) Friends(uuid string) (Friends, error)
  • func (session *Hypixel) GameStats() (Stats, error)
  • func (session *Hypixel) Guild(userGuild string) (Guild, error)
  • func (session *Hypixel) GuildAchievements() (GuildAchievements, error)
  • func (session *Hypixel) GuildPermissions() ([]GuildPermission, error)
  • func (session *Hypixel) Key(customKey ...string) (Key, error)
  • func (session *Hypixel) Leaderboards() (Leaderboards, error)
  • func (session *Hypixel) Player(uuid string) (Player, error)
  • func (session *Hypixel) PlayerCount() (int, error)
  • func (session *Hypixel) Quests() (Quests, error)
  • func (session *Hypixel) SkyblockCollections() (map[string]SkyblockCollection, error)
  • func (session *Hypixel) SkyblockSkills() (SkyblockSkills, error)

Examples

• Hypixel.Achievements
• Hypixel.BanStats
• Hypixel.Boosters
• Hypixel.FindGuild
• Hypixel.Friends
• Hypixel.GameStats
• Hypixel.Guild
• Hypixel.GuildAchievements
• Hypixel.GuildPermissions
• Hypixel.Key
• Hypixel.Leaderboards
• Hypixel.Player
• Hypixel.PlayerCount
• Hypixel.Quests
• Hypixel.SkyblockCollections
• Hypixel.SkyblockSkills
• New

Constants

const (
	// APIKeyLength is the length of Hypixel API keys.
	APIKeyLength = 36
	// APIBaseURL is the base URL of the Hypixel API.
	APIBaseURL = "https://api.hypixel.net/"
)

Types

type Hypixel

type Hypixel struct {
	sync.RWMutex
	// Hypixel API keys are in the format of a UUID.
	// Example: 00000000-0000-0000-0000-000000000000
	APIKey string
}

Hypixel is the main struct of the API. It holds the API key for your session, which is set with the New() function.

func New

func New(apiKey string) (*Hypixel, error)

New creates a new instance of the Hypixel struct.

Example

Examples

instance, err := New("00000000-0000-0000-0000-000000000000")
if err != nil {
	log.Fatalln(err)
}
fmt.Println(instance.APIKey)

func (*Hypixel) Achievements

func (session *Hypixel) Achievements() (Achievements, error)

Achievements returns all available achievements for all gamemodes.

Example

Achievements, err := instance.Achievements()
if err != nil {
	log.Fatalln("Couldn't get achievements:", err)
}
fmt.Println(Achievements.LastUpdated)

Output:

1577816800575

func (*Hypixel) BanStats

func (session *Hypixel) BanStats() (BanStats, error)

BanStats returns statistics about Watchdog and staff bans.

Example

BanStats, err := instance.BanStats()
if err != nil {
	log.Fatalln("Couldn't get Ban stats:", err)
}
fmt.Println(BanStats.WatchdogLastMinute)

func (*Hypixel) Boosters

func (session *Hypixel) Boosters() (Boosters, error)

Boosters returns a list of active boosters.

Example

_, err := instance.Boosters()
if err != nil {
	log.Fatalln("Couldn't get boosters:", err)
}

func (*Hypixel) Challenges

func (session *Hypixel) Challenges() (Challenges, error)

Challenges returns all the available challenges for all gamemodes.

func (*Hypixel) FindGuild

func (session *Hypixel) FindGuild(guild string) (string, error)

FindGuild returns the ID of a requested guild.

Example

// Get a guild ID by its name
GuildID, err := instance.FindGuild("Sex Havers")
if err != nil {
	log.Fatalln("Couldn't get guild ID from name:", err)
}
fmt.Println(GuildID)

// Get a guild ID by the UUID of a member
GuildID, err = instance.FindGuild("69a7da3c-5e94-4bbe-883e-61568c928d05")
if err != nil {
	log.Fatalln("Couldn't get guild ID from UUID:", err)
}
fmt.Println(GuildID)

Output:

5de1d9c68ea8c96c82070699
5de1d9c68ea8c96c82070699

func (*Hypixel) Friends

func (session *Hypixel) Friends(uuid string) (Friends, error)

Friends returns frend information about a player.

Example

Friends, err := instance.Friends("d4acada6-bc84-4dd3-8406-0bb77e207a7a")
// Me! :)
if err != nil {
	log.Fatalln("Couldn't get friends:", err)
}

fmt.Println(len(Friends.Records)) // :(

Output:

1

func (*Hypixel) GameStats

func (session *Hypixel) GameStats() (Stats, error)

GameStats returns the total players online, total players for every minigame, and total players for every mode of that minigame e.g. (Solo/Doubles/Mega Skywars).

Example

Stats, err := instance.GameStats()
if err != nil {
	log.Fatalln(err)
}

fmt.Println(Stats.GameStats.SKYWARS.Players > 0)
// This too can theoretically return false and still be correct, but
// practically, there should be at least one person playing it at any time.

Output:

true

func (*Hypixel) Guild

func (session *Hypixel) Guild(userGuild string) (Guild, error)

Guild returns information about a guild.

Example

Guild, err := instance.Guild("69a7da3c-5e94-4bbe-883e-61568c928d05")
if err != nil {
	log.Fatalln("Couldn't get guild information from player UUID:", err)
}

fmt.Println(Guild.Name)

Guild, err = instance.Guild("Sex Havers")
if err != nil {
	log.Fatalln("Couldn't get guild information from name:", err)
}

fmt.Println(Guild.ID)

Output:

Sex Havers
5de1d9c68ea8c96c82070699

func (*Hypixel) GuildAchievements

func (session *Hypixel) GuildAchievements() (GuildAchievements, error)

GuildAchievements returns all the available guild achievements.

Example

GuildAchievements, err := instance.GuildAchievements()
if err != nil {
	log.Fatalln("Couldn't get guild achievements", err)
}

fmt.Println(GuildAchievements.Tiered["PRESTIGE"].Description)

Output:

Reach Guild level %s

func (*Hypixel) GuildPermissions

func (session *Hypixel) GuildPermissions() ([]GuildPermission, error)

GuildPermissions returns all the available guild permissions.

Example

GuildPermissions, err := instance.GuildPermissions()
if err != nil {
	log.Fatalln("Couldn't get guild permissions", err)
}

fmt.Println(GuildPermissions[0].Name)
// The "en_us" access is because, apparently, theres the ability
// to have localised permissions. Even though all of this data is static.
// Who knows.

Output:

Modify Guild Name

func (*Hypixel) Key

func (session *Hypixel) Key(customKey ...string) (Key, error)

Key returns information about the current active key. If no arguments are provided, it looks up the key that's set in the Hypixel struct. If an argument is provided, it looks up that key instead.

Example

Key, err := instance.Key()
if err != nil {
	log.Fatalln("Couldn't get default key information", err)
}

fmt.Println(Key.Owner)

Output:

d4acada6bc844dd384060bb77e207a7a

func (*Hypixel) Leaderboards

func (session *Hypixel) Leaderboards() (Leaderboards, error)

Leaderboards returns information about the current Hypixel leaderboards.

Example

Leaderboards, err := instance.Leaderboards()
if err != nil {
	log.Fatalln("Couldn't get leaderboards", err)
}

fmt.Printf("%v %v",
	Leaderboards.Skywars[1].Prefix, Leaderboards.Skywars[1].Title)

Output:

Overall Wins

func (*Hypixel) Player

func (session *Hypixel) Player(uuid string) (Player, error)

Player returns information about a player.

Example

Player, err := instance.Player("d4acada6-bc84-4dd3-8406-0bb77e207a7a")
if err != nil {
	log.Fatalln("Couldn't get player information", err)
}

fmt.Println(Player.PlayerName)

Output:

tiraa

func (*Hypixel) PlayerCount

func (session *Hypixel) PlayerCount() (int, error)

PlayerCount returns the current amount of players online.

Example

PlayerCount, err := instance.PlayerCount()
if err != nil {
	log.Fatalln("Couldn't get player count", err)
}

fmt.Println(PlayerCount > 0)
// This per-se can fail and still be truthful, but we'll just have to assume
// that Hypixel still exists for the mean time.

Output:

true

func (*Hypixel) Quests

func (session *Hypixel) Quests() (Quests, error)

Quests returns all the available quests for all gamemodes.

Example

Quests, err := instance.Quests()
if err != nil {
	log.Fatalln("Couldn't get quests", err)
}

fmt.Println(Quests.Modes["hungergames"][0].Name)

Output:

Daily Quest: Game of the Day

func (*Hypixel) SkyblockCollections

func (session *Hypixel) SkyblockCollections() (map[string]SkyblockCollection, error)

SkyblockCollections returns all the available skyblock collections.

Example

SkyblockCollections, err := instance.SkyblockCollections()
if err != nil {
	log.Fatalln(err)
}

fmt.Println(SkyblockCollections["FARMING"].Items["WHEAT"].Name)
fmt.Println(SkyblockCollections["FARMING"].Items["WHEAT"].MaxTier)

Output:

Wheat
9

func (*Hypixel) SkyblockSkills

func (session *Hypixel) SkyblockSkills() (SkyblockSkills, error)

SkyblockSkills returns all the available skyblock skills.

Example

SkyblockSkills, err := instance.SkyblockSkills()
if err != nil {
	log.Fatalln(err)
}

fmt.Println(SkyblockSkills.Collections["FARMING"].Name)
fmt.Println(SkyblockSkills.Collections["FARMING"].Description)

Output:

Farming
Harvest crops and shear sheep to earn Farming XP!