HomeLogo

@zikeji/hypixel

NodeJS API wrapper for Hypixel's Public API

Get Started →

Hypixel API V2 Support

With the V1 API being phased out, it's ever crucial to begin updating your projects to their V2 endpoints.

Rate Limiting Queue

Built in async rate limiting queue prevents prevents requests from failing by queueing and waiting for the queue to clear.

# @zikeji/hypixel

npm (opens new window) npm bundle size (opens new window) visit docs (opens new window) GitHub license (opens new window) GitHub last commit (opens new window) GitHub code size in bytes (opens new window) GitHub issues (opens new window) Coveralls (opens new window) GitHub Workflow Status (opens new window)

With IntelliSense (opens new window) support, this is an unopinionated async/await API wrapper for Hypixel's Public API (opens new window). It is developed in TypeScript complete with documentation (opens new window), typed interfaces (opens new window) for all API responses, built-in rate-limit handling, flexible cache support (opens new window), and some helper functions (opens new window).

# 4.0.0 Information

4.0 is a major breaking version, where I've rebased types on the v2 endpoints published by Hypixel and removed my previous OpenAPI.yaml.

I've added AugmentedTypes.ts to "augment" their typings, but they are very barebones in the current state. Pull requests augmenting types are welcome, I will more than likely not be exploring the typings like I did in the past, and merely add what I want/need.

# Installation

# NodeJS

Use npm (opens new window) to install this library.

npm i --save @zikeji/hypixel
1

# Usage

const { Client } = require("@zikeji/hypixel");
const client = new Client("API_KEY");
(async () => {
  const status = await client.status.uuid("20934ef9488c465180a78f861586b4cf"); // Minikloon
  console.log(status);
  // {"online": false}
  const stats = await client.punishmentstats();
  console.log(stats);
  // {watchdog_lastMinute: 1, staff_rollingDaily: 2609, watchdog_total: 5591714, watchdog_rollingDaily: 4213, …}
})();
1
2
3
4
5
6
7
8
9
10

# Helpers

This library adds multiple helpers to facilitate using the Hypixel API. You can find documentation on each helper here (opens new window). If you would like to request a helper that doesn't exist, please open an issue. Otherwise if you would like to contribute one refer to the below section.

# Contributing

If some API result isn't documented / typed out fully, please open an issue and I can see about adding it. However some data is too exhaustive to provide typings to in a reasonable manner, as exhibited here (opens new window), where it isn't reasonable to add 19.5 thousand lines of code to document the entire dataset.

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. All changes must ensure they pass eslint, tests, and that testing is updated to meet or exceed the previous coverage.

# New Typings

If Hypixel updates their API documentation, you can navigate to https://api.hypixel.net and click "Download", place it in the root folder of this project, and do npm run types:openapi to regenerate the ./src/types/api.ts.

# Licenses

This projected is licensed under the MIT license. For additional details see LICENSE.

This library contains derivative work based on classes from the hypixel-php (opens new window) library. Code that is derivative work of hypixel-php (opens new window) will be marked as such with a header comment. See LICENSE-HYPIXEL-PHP.md for additional details on the original license.