Documentazione API v1

Benvenuti nella documentazione ufficiale per sviluppatori di HytaleServers.it. La nostra API pubblica permette di accedere programmaticamente ai dati dei server, inclusi statistiche di voto in tempo reale, stato online e classifiche giocatori.

Endpoint: Dettagli Server

Restituisce tutte le informazioni pubbliche disponibili per un server specifico.

Parametri Richiesta

Parametro	Tipo	Obbligatorio	Descrizione
slug	String / Int	Sì	Il nome univoco del server (es. HytaleWorld) oppure il suo ID numerico (es. 42).

Esempio di Risposta (200 OK)

{
  "id": 1,
  "name": "HytaleWorld",
  "address": "play.hytaleworld.it",
  "votes_count": 154,
  "votes_today": 2,
  "votes_yesterday": 5,
  "today_votes": [
      { "username": "PlayerOne", "timestamp": 1706198400 },
      { "username": "Steve", "timestamp": 1706194800 }
  ],
  "yesterday_votes": [
      { "username": "Alex", "timestamp": 1706112000 },
      { "username": "JohnDoe", "timestamp": 1706108400 }
  ],
  "online": true,
  "country": "IT",
  "categories": ["Survival", "RPG"],
  "sponsored": true,
  "last_update": 1706200000,
  "vote_leaderboard": [
    { "username": "TopVoter", "count": 15 },
    { "username": "FanNumber1", "count": 12 }
  ]
}

Riferimento Campi Risposta

Campo	Tipo	Descrizione
id	Integer	Identificativo univoco del server.
name	String	Il nome visualizzato del server.
address	String	Indirizzo IP o dominio per la connessione.
votes_count	Integer	Numero totale di voti validi nel periodo corrente (ultimi 30 giorni).
votes_today	Integer	Numero di voti ricevuti oggi (dalla mezzanotte, fuso orario Europe/Rome).
votes_yesterday	Integer	Numero di voti ricevuti nell'intera giornata di ieri.
today_votes	Array[Object]	Lista dettagliata dei voti di oggi. Ogni oggetto contiene username e timestamp (Unix).
online	Boolean	Stato attuale del server (true = Online, false = Offline).
last_update	Integer (Unix)	Timestamp dell'ultimo controllo di stato effettuato dal nostro sistema.

Codici di Errore

Codice	Significato	Esempio Risposta
404	Server Non Trovato	{ "error": "Server not found" }
400	Richiesta Invalida	{ "error": "Missing server slug or ID" }
500	Errore Interno	{ "error": "Internal Server Error" }

Esempi di Integrazione

cURL

curl -X GET "https://api.hytaleservers.it/v1/server/HytaleWorld" \
     -H "Accept: application/json"

PHP

$slug = 'HytaleWorld';
$json = file_get_contents("https://api.hytaleservers.it/v1/server/" . $slug);
$data = json_decode($json, true);

if ($data) {
    echo "Il server " . $data['name'] . " ha " . $data['votes_count'] . " voti.";
}

JavaScript (Node.js / Fetch)

fetch('https://api.hytaleservers.it/v1/server/HytaleWorld')
  .then(response => response.json())
  .then(data => {
    console.log(`Server: ${data.name}`);
    console.log(`Status: ${data.online ? 'Online' : 'Offline'}`);
  })
  .catch(error => console.error('Error:', error));

Python

import requests

response = requests.get("https://api.hytaleservers.it/v1/server/HytaleWorld")

if response.status_code == 200:
    data = response.json()
    print(f"Voti oggi: {data['votes_today']}")
else:
    print("Server non trovato")