NAV
shell

Introduction

API Endpoint

https://api.statscraft.net/public

Welcome to the Statscraft API documentation.

The Statscraft API is used for retrieving data stored against your server. The extracted data can be used in various ways - for example you could get a list of the top players and display it on your website.

Whenever an element represents time, the unit will always be in seconds unless otherwise stated. Also, you may append /<start>/<end> to every request which will limit what data is returned. The start and end parameters must be UNIX timestamps and are completely optional, if no range is provided then the data returned will be from the time that you created your server.

Are you a developer? If you’ve created an SDK in your favourite language we’d love to officially support it. Drop us an email via [email protected]

With every request there is a generation object, which contains two elements:

Authentication

To access the API, all requests need to be authenticated via your private key.

Supply the private key by setting the X-Private-Key header in all requests to the API.

Error Handling

Example Error

{
    "time": 1516378123,
    "date": "Fri, 19 Jan 2018 11:08:43",
    "error": true,
    "message": "The specified private key is invalid",
    "generation": {
        "global": 0.04175,
        "response": 0.00543
    }
}

If there is an error then the error element will be set to true and an error message will be displayed in the message element.

Information

Endpoint

GET https://api.statscraft.net/public/info

Example Request

curl -X GET -H 'X-Private-Key: lEYvb6MQklaWkDNpm' "https://api.statscraft.net/public/info"

Example Response

{
    "returning_players": "0",
    "returning_players_percentage": "0",
    "new_players": 1,
    "new_players_percentage": 100,
    "avg_time_played": "382.2500",
    "avg_time_played_formatted": "00:06:22",
    "generation": {
        "global": 0.03268,
        "response": 0.00982
    }
}

Returns general information about your server, similar to the data that you would see upon logging into your server’s dashboard.

Server

Retrieve average server usage

Endpoint

GET https://api.statscraft.net/public/server

Example Request

curl -X GET -H 'X-Private-Key: lEYvb6MQklaWkDNpm' "https://api.statscraft.net/public/server"

Example Response

{
    "players_online": "0.9264",
    "tps": "20.00",
    "memory_usage": "38.46114580",
    "memory_average": "386.1789",
    "cpu_usage": "0.999440",
    "generation": {
        "global": 0.0465,
        "response": 0.01131
    }
}

Returns your average server data.

The memory_average is measured in MB, whereas the memory_usage is a percentage.

Retrieve all sessions

Endpoint

GET https://api.statscraft.net/public/sessions

Example Request

curl -X GET -H 'X-Private-Key: lEYvb6MQklaWkDNpm' "https://api.statscraft.net/public/sessions"

Example Response

{
    "sessions": [
        {
            "username": "Test",
            "uuid": "d8d5a923-7b20-43d8-883b-1150148d6955",
            "date_login": "1516117508",
            "date_quit": "1516117513",
            "duration": "1516117513",
            "ip_address": "123.45.67.89",
            "country_code": "GB",
            "mc_version": "1.12"
        },
        {
            "username": "Test",
            "uuid": "d8d5a923-7b20-43d8-883b-1150148d6955",
            "date_login": "1516191499",
            "date_quit": "1516191501",
            "duration": "1516191501",
            "ip_address": "123.45.67.89",
            "country_code": "GB",
            "mc_version": "1.12"
        },
        {
            "username": "Test",
            "uuid": "d8d5a923-7b20-43d8-883b-1150148d6955",
            "date_login": "1516191605",
            "date_quit": "1516191609",
            "duration": "1516191609",
            "ip_address": "123.45.67.89",
            "country_code": "GB",
            "mc_version": "1.12"
        },
        {
            "username": "Test",
            "uuid": "d8d5a923-7b20-43d8-883b-1150148d6955",
            "date_login": "1516191627",
            "date_quit": "1516193145",
            "duration": "1516193145",
            "ip_address": "123.45.67.89",
            "country_code": "GB",
            "mc_version": "1.12"
        }
    ],
    "total": "4",
    "generation": {
        "global": 0.03446,
        "response": 0.00797
    }
}

Returns all of the sessions stored against your server.

This API endpoint is only accessible to Enterprise customers. If you are interested in upgrading to Enterprise please contact us at [email protected]

Players

Retrieve data about a specific player

Endpoint

GET https://api.statscraft.net/public/player/<uuid>

Example Request

curl -X GET -H 'X-Private-Key: lEYvb6MQklaWkDNpm' "https://api.statscraft.net/public/player/7c6d3775-9dd7-4934-9f2c-32303a367226
"

Example Response

{
    "info": {
        "player_id": "1245",
        "player_uuid": "7c6d3775-9dd7-4934-9f2c-32303a367226",
        "username": "Test",
        "date_first_login": "1516117513",
        "date_last_login": "1516117513",
        "image": "https://cravatar.eu/helmavatar/7c6d3775-9dd7-4934-9f2c-32303a367226/64.png"
    },
    "session": {
        "total_playtime": "1529",
        "avg_playtime": "382.2500",
        "frequent_time": "1516173059.7500",
        "frequent_time_end": "1516173442.0000",
        "total_sessions": "4",
        "date_first": "1516117508",
        "date_last": "1516191627",
        "ip_address": "123.45.67.89",
        "country_code": "GB",
        "country_name": "United Kingdom",
        "avg_playtime_formatted": "6 minutes and 22 seconds",
        "total_playtime_formatted": "25 minutes and 29 seconds",
        "frequent_time_formatted": "16:10:59",
        "frequent_time_end_formatted": "16:17:22"
    },
    "generation": {
        "global": 0.18494,
        "response": 0.05666
    }
}

Returns data about a specific player.

Retrieve a players’ sessions

Endpoint

GET https://api.statscraft.net/public/playersessions/<uuid>

Example Request

curl -X GET -H 'X-Private-Key: lEYvb6MQklaWkDNpm' "https://api.statscraft.net/public/playersessions/7c6d3775-9dd7-4934-9f2c-32303a367226
"

Example Response

{
    "sessions": [
        {
            "date_login": "1516117508",
            "date_quit": "1516117513",
            "duration": 5,
            "ip_address": "123.45.67.89",
            "country_code": "GB",
            "mc_version": "1.12"
        },
        {
            "date_login": "1516191499",
            "date_quit": "1516191501",
            "duration": 2,
            "ip_address": "123.45.67.89",
            "country_code": "GB",
            "mc_version": "1.12"
        },
        {
            "date_login": "1516191605",
            "date_quit": "1516191609",
            "duration": 4,
            "ip_address": "123.45.67.89",
            "country_code": "GB",
            "mc_version": "1.12"
        },
        {
            "date_login": "1516191627",
            "date_quit": "1516193145",
            "duration": 1518,
            "ip_address": "123.45.67.89",
            "country_code": "GB",
            "mc_version": "1.12"
        }
    ],
    "total": "4",
    "generation": {
        "global": 0.03475,
        "response": 0.00709
    }
}

Returns sessions stored against a player on your server.

If you do not have ProtocolLib or ViaVersion installed on your server then the mc_version will likely be null.

Retrieve a list of your top ten players

Endpoint

GET https://api.statscraft.net/public/topplayers

Example Request

curl -X GET -H 'X-Private-Key: lEYvb6MQklaWkDNpm' "https://api.statscraft.net/public/topplayers
"

Example Response

{
    "1": {
        "username": "Test",
        "uuid": "7c6d3775-9dd7-4934-9f2c-32303a367226",
        "total_time": "1529",
        "average_time": "382.2500"
    },
    "generation": {
        "global": 0.04208,
        "response": 0.00727
    }
}

Returns a list of the top ten players on your server, based on their total playtime.