cactive-hypixel-nick-tracker 3.0.6
Wrapper for the exclusive CactiveNetwork unofficial Hypixel API.
Requires Python: >=3.9

# Unofficial Hypixel API by CactiveNetwork

This is an implementation of the API in Python, however you're welcome to request data directly.

The method of collecting data is **private**, hence why a key system is required.

This API is written in Python, and as such contains full type declarations for all endpoints, and includes optional object fields for sensitive data not provided on standard API keys.

### Disclaimer:

- We are not associated nor should we be considered affiliated with Hypixel.
- A valid API key is required to successfully request player, nickname, ban and other data from this API. You can request an API key running `-ticket open` [in this discord](https://discord.gg/NeqVuSy) providing you meet criteria.
- You are not under any circumstances guaranteed an API key, and we may revoke your application and its API key for any reason, including but not limited to the following; you are directly linked to administration of Hypixel or not information is provided in your background check, you use data for malicious purposes that harm other players, your application does not need this API for its intended purpose, your application has security flaws that take away the integrity of your key, your application is unsafely public, etc.

---

## Error Types

In the case that your request is invalid, maintenance is done on the API, or the tunnel collecting data is blocked or locked out, you will receive an error, which you should look out for.

This wrapper adds an `internal` field to the object in your array of errors, which will be `True` if the error is internal to your device (unable to send request or parse JSON), otherwise false.

- `no-authentication` - You didn't provide the relevant authentication information (key field).
- `no-identifier` - You didn't provide the relevant username, id, or such required identification field.
- `no-filter` - You didn't provide the relevant filter field to your request.
- `invalid-authentication` - The authentication information provided in the request was invalid.
- `invalid-filter` - The filter provided in the request was invalid.
- `invalid-endpoint` - The endpoint provided in the request was invalid.
- `tunnel-blocked` - Unable to interface with the required relevant request data.
- `hypixel-maintenance` - Unable to complete because one of the data sources are offline. 
- `rate-limit-blocked` - You are being rate limited for sending too many valid requests.
- `failed-api-request` **NODE CLIENT** - The client failed to send a valid request to the server.
- `unexpected-error` - An unexpected error occurred on the API server.

---

## Rate Limits

- Standard requests are limited to `10 requests per minute`.
- Smart-cached requests (semi-accurate data) are limited to `30 request per minute`.

You are expected to respect these limits, and if you do not, you will be blocked from the API.

---

## Endpoints

To use any implementation code block, you must create a declaration to a new API client.

```python
from cactive_hypixel_nick_tracker import Client
client = Client(
    key="MY_API_KEY", # replace this field.
    cache=False
)
```

---

### Nickname History:
**URL**: https://hypixel.cactive.network/api/v3/nickname-history

**Method:** `GET`

**URL Parameters:**
- `key`: String - CactiveNetwork API key (**Required**)
- `nickname`: String - Lookup nickname (**Required**)
- `cache`: Boolean - Not fetch new data

**Python Implementation:**

```python
try:
    data = client.nickname_history("nickname").data
    print(data)
    ''' [
        {
            "uuid": "eea2d4fda8b8413b9439f06faaf7e109",
            "nickname": "angry_and_free",
            "active": false,
            "created_at": "2022-04-11T09:00:27.933Z",
            "voided_at": "1970-01-01T00:00:00.000Z"
        }
    ] '''
except Exception as e:
    print(e)
    ''' [
        {
            "type": "no-identifier",
            "code": 400,
            "message": "You didn't provide a 'nickname' parameter in your request"
        }
    ] '''
```
---
### Player Data

**URL**: https://hypixel.cactive.network/api/v3/player-data

**Method:** `GET`

**URL Parameters:**
- `key`: String - CactiveNetwork API key (**Required**)
- `uuid`: String - Player uuid (**Required**)
- `cache`: Boolean - Not fetch new data

**Python Implementation:**

```python
try:
    data = client.player_data("uuid").data
    print(data)
    ''' {
        "uuid": "eea2d4fda8b8413b9439f06faaf7e109",
        "nickname_history": [
            {
                "nickname": "angry_and_free",
                "active": false,
                "created_at": "2022-04-11T09:00:27.933Z",
                "voided_at": "1970-01-01T00:00:00.000Z"
            }
            ...
        ],
        "infractions": [],
        "tracker": {
            "server": null,
            "map": null,
            "proxy": null,
            "last_login": "2022-04-11T09:13:06.113Z"
        },
    } '''
except Exception as e:
    print(e)
    ''' [
        {
            "type": "no-identifier",
            "code": 400,
            "message": "You didn't provide a 'uuid' parameter in your request"
        }
    ]'''
```
---
### Staff Tracker

**URL**: https://hypixel.cactive.network/api/v3/staff-tracker

**Method:** `GET`

**URL Parameters:**
- `key`: String - CactiveNetwork API key (**Required**)
- `filter`: String - `all`, `online`, or `offline` (**Required**)
- `cache`: Boolean - Not fetch new data

**Python Implementation:**

```python
try:
    data = client.staff_tracker("online").data
    print(data)
    ''' [
        {
            "uuid": "20934ef9488c465180a78f861586b4cf",
            "rank": "ADMINISTRATOR"
            "online": false
        },
        ...
    ] '''
except Exception as e:
    print(e)
    ''' [
        {
            "type": "invalid-filter",
            "code": 400,
            "message": "You need to provide a filter out of the options, 'all', 'online', 'offline'"
        }
    ] '''
```
---
### Punishment Data

**URL**: https://hypixel.cactive.network/api/v3/punishment-data

**Method:** `GET`

**URL Parameters:**
- `key`: String - CactiveNetwork API key (**Required**)
- `id`: String - Punishment ID (Ban ID) (**Required**)
- `cache`: Boolean - Not fetch new data

**Python Implementation:**

```python
try:
    const { data } = await client.punishment_data("ID");
    print(data)
    ''' {
        "id": "C256D602",
        "punishment_type": "ban",
        "uuid": "eea2d4fda8b8413b9439f06faaf7e109",
        "executor": null,
        "reason": "Cheating through the use of unfair game advantages.",
        "length": 2592000000
    } '''
except Exception as e {
    print(e)
    ''' [
        {
            "type": "no-identifier",
            "code": 400,
            "message": "You didn't provide a 'id' parameter in your request"
        }
    ] '''
}
```
---
### Key

**URL**: https://hypixel.cactive.network/api/v3/key

**Method:** `GET`

**URL Parameters:**
- `key`: String - CactiveNetwork API key (**Required**)

**Python Implementation:**
```python
try {
    data = client.key_data("key").data
    print(data)
    ''' {
        "key": "demo",
        "valid": false,
        "active": false,
        "created_at": "1970-01-01T00:00:00.000Z",
        "expires_at": "1970-01-01T00:00:00.000Z",
        "owner_cactiveconnections_id": null,
        "endpoints": [
            {
                "id": "nickname-history",
                "version": 3,
                "status": false
            },
            ...
        ]
    } '''
} except Exception as e {
    print(e)
    ''' [] '''
}
```