Documentation

API SoCo.

API REST publique pour accéder aux données NationsGlory. Toutes les réponses sont en JSON. Aucune authentification requise pour les endpoints publics.

URL de base

http://127.0.0.1:5000

Format

application/json

Version

v2.0

Serveurs disponibles

La plupart des endpoints qui ciblent un serveur acceptent l'un des identifiants suivants. La valeur par défaut est blue lorsqu'un serveur est optionnel.

blueorangeyellow whiteblackcyan limecoralalpha sigmaomegared deltamochaepsilon jade

Codes d'erreur

Toutes les erreurs retournent un objet JSON avec un champ error décrivant le problème.

400Paramètre manquant ou invalide — vérifiez les paramètres requis.

404Ressource introuvable — joueur, pays ou serveur inexistant.

500Erreur interne — l'API upstream NationsGlory est injoignable ou a renvoyé une réponse invalide.

Joueurs

GET /api/user/:username

Retourne le profil complet d'un joueur : informations générales, liste des serveurs, dernier serveur de connexion, statut staff, statut OP, comptes supposés associés et URL de bannière d'affiliation.

Paramètre	Type	Description
username	string	Nom du joueur (dans l'URL) REQUIS

Exemple de réponse

JSON
{
  "username": "Bfire",
  "created_at": "2021-03-12",
  "last_connection": "2026-02-10T18:32:00",
  "description": "Fondateur SoCo",
  "is_prime": true,
  "signature": "...",
  "skin": "https://skins.nationsglory.fr/Bfire",
  "last_server_connection": "blue",
  "is_op": false,
  "is_staff": "No",
  "supposed_other_accounts": [],
  "affiliate_banner": "https://apiv2.nationsglory.fr/...",
  "servers": { ... }
}

GET /api/user/:username/servers

Retourne uniquement la liste des serveurs sur lesquels le joueur a joué, avec les données associées (niveau, dernière connexion, etc.).

Paramètre	Type	Description
username	string	Nom du joueur (dans l'URL) REQUIS

Exemple de réponse

JSON
{
  "username": "Bfire",
  "servers": {
    "blue": { "level": 42, "last_connection": "2026-02-10" }
  }
}

GET /api/user-search

Recherche des joueurs par terme de recherche via les forums NationsGlory. Retourne une liste de correspondances.

Paramètre	Type	Description
search	query string	Terme de recherche REQUIS

Requête exemple

URL
GET /api/user-search?search=Bfire

GET /api/skins/:username

Retourne l'URL du skin Minecraft du joueur hébergé sur les serveurs NationsGlory.

Paramètre	Type	Description
username	string	Nom du joueur (dans l'URL) REQUIS

Exemple de réponse

JSON
{
  "username": "Bfire",
  "skin_url": "https://skins.nationsglory.fr/Bfire",
  "content_type": "image/png"
}

GET /api/sanctions

Retourne les sanctions d'un joueur sur un serveur donné. En passant server=all, l'API agrège les sanctions de tous les serveurs et retourne un total par serveur.

Paramètre	Type	Description
pseudo	query string	Pseudo du joueur REQUIS
server	query string	Identifiant du serveur ou `all` pour tous les serveurs Défaut : blue

Réponse — serveur unique

JSON
{
  "pseudo": "Bfire",
  "server": "blue",
  "total_sanctions": 2,
  "sanctions": [ ... ]
}

Réponse — tous les serveurs

JSON
{
  "pseudo": "Bfire",
  "server": "all",
  "total_sanctions": 5,
  "sanctions_by_server": { "blue": 2, "red": 3 }
}

Serveurs

GET/api/playercount

Retourne le nombre de joueurs connectés et le statut en ligne pour chaque serveur NationsGlory.

Exemple de réponse

JSON
{
  "blue": { "players": 142, "online": true },
  "red":  { "players": 87,  "online": true },
  // ...
}

GET/api/players-per-server

Version simplifiée de /api/playercount. Retourne uniquement le nombre de joueurs par serveur, sans les métadonnées.

Exemple de réponse

JSON
{ "blue": 142, "red": 87, "orange": 55, // ... }

GET/api/total-players

Retourne le nombre total de joueurs connectés sur l'ensemble des serveurs NationsGlory en un seul chiffre.

Exemple de réponse

JSON
{ "total_players": 998 }

GET/api/servers

Retourne les métadonnées complètes de tous les serveurs (permanents et temporaires), enrichies avec le nombre de joueurs connectés et l'adresse IP de connexion.

GET/api/servers/:server/status

Retourne le statut en temps réel d'un serveur spécifique : nombre de joueurs, état en ligne, et heure de dernière mise à jour.

Paramètre	Type	Description
server	string	Identifiant du serveur REQUIS

Exemple de réponse

JSON
{
  "server": "blue",
  "players": 142,
  "online": true,
  "last_update": "2026-02-17T12:00:00"
}

Pays

GET/api/country/:server/:country

Retourne le profil complet d'un pays : nom, membres, alliés, ennemis, banque, puissance, territoire et toutes les métadonnées disponibles.

Paramètre	Type	Description
server	string	Identifiant du serveur REQUIS
country	string	Nom du pays REQUIS

Requête exemple

URL
GET /api/country/blue/France

GET/api/country/list/:server

Retourne la liste complète des pays d'un serveur : pays revendiqués et pays disponibles. Également accessible via GET /api/countries?server=blue.

Paramètre	Type	Description
server	string	Identifiant du serveur (dans l'URL ou query string) REQUIS

GET/api/countries/claimed

Retourne uniquement les pays actuellement revendiqués sur le serveur spécifié.

Paramètre	Type	Description
server	query string	Identifiant du serveur Défaut : blue

Exemple de réponse

JSON
{
  "server": "blue",
  "claimed": ["France", "Espagne", // ...]
}

GET/api/countries/available

Retourne la liste des pays disponibles (non revendiqués) sur le serveur spécifié.

Paramètre	Type	Description
server	query string	Identifiant du serveur Défaut : blue

GET/api/country/power

Retourne la puissance actuelle et la puissance maximale d'un pays.

Paramètre	Type	Description
name	query string	Nom du pays REQUIS
server	query string	Identifiant du serveur Défaut : blue

Exemple de réponse

JSON
{
  "country": "France", "server": "blue",
  "power": 15000, "max_power": 20000
}

GET/api/country/pib

Retourne le PIB (Produit Intérieur Brut) d'un pays, extrait des notations NationsGlory.

Paramètre	Type	Description
name	query string	Nom du pays REQUIS
server	query string	Identifiant du serveur Défaut : blue

Exemple de réponse

JSON
{ "country": "France", "server": "blue", "pib": 4850000 }

GET/api/country/skills

Retourne les scores de compétences d'un pays : score général, économique, militaire et total.

Paramètre	Type	Description
name	query string	Nom du pays REQUIS
server	query string	Identifiant du serveur Défaut : blue

Exemple de réponse

JSON
{
  "country": "France", "server": "blue",
  "skills": 88, "econ": 92, "military": 75, "total": 255
}

GET/api/country/allies

Retourne la liste des pays alliés d'un pays donné.

Paramètre	Type	Description
name	query string	Nom du pays REQUIS
server	query string	Identifiant du serveur Défaut : blue

GET/api/country/enemies

Retourne la liste des pays ennemis d'un pays donné.

Paramètre	Type	Description
name	query string	Nom du pays REQUIS
server	query string	Identifiant du serveur Défaut : blue

GET/api/country/members

Retourne la liste des membres d'un pays ainsi que le nombre total de membres.

Paramètre	Type	Description
name	query string	Nom du pays REQUIS
server	query string	Identifiant du serveur Défaut : blue

Exemple de réponse

JSON
{
  "country": "France", "server": "blue",
  "count_members": 12,
  "members": ["Bfire", // ...]
}

GET/api/country/bank

Retourne les données bancaires d'un pays (solde et ressources en banque).

Paramètre	Type	Description
name	query string	Nom du pays REQUIS
server	query string	Identifiant du serveur Défaut : blue

GET/api/country-search

Recherche des pays par terme de recherche sur un serveur donné.

Paramètre	Type	Description
search	query string	Terme de recherche REQUIS
server	query string	Identifiant du serveur Défaut : blue

GET/api/leader

Retourne le leader (chef d'état) d'un pays sur un serveur donné.

Paramètre	Type	Description
search	query string	Nom du pays REQUIS
server	query string	Identifiant du serveur Défaut : blue

Notations & MMR

GET/api/notations

Retourne les notations hebdomadaires d'un pays. Les trois paramètres sont obligatoires. Le serveur et le pays sont automatiquement mis avec une majuscule initiale avant l'envoi à l'API NationsGlory.

Paramètre	Type	Description
week	query string	Numéro de semaine REQUIS
country	query string	Nom du pays REQUIS
server	query string	Identifiant du serveur REQUIS

Requête exemple

URL
GET /api/notations?week=10&country=France&server=blue

GET/api/notations-html

Récupère les notations en scrapant la page HTML NationsGlory. Retourne les 10 dernières notations avec le joueur et son score. Alternative à /api/notations lorsque l'API upstream n'est pas disponible.

Paramètre	Type	Description
server	query string	Identifiant du serveur Défaut : blue
country	query string	Nom du pays Défaut : france

Exemple de réponse

JSON
{
  "server": "blue", "country": "france",
  "total_notations": 24,
  "latest_notations": [
    { "player": "Bfire", "score": "98" },
    // jusqu'à 10 entrées
  ]
}

GET/api/mmr/:server

Retourne le classement MMR complet d'un serveur, avec les joueurs triés par rang.

Paramètre	Type	Description
server	string	Identifiant du serveur (dans l'URL) REQUIS

Requête exemple

URL
GET /api/mmr/blue

HDV & Statistiques

GET/api/hdv

Retourne toutes les offres actives de l'Hôtel de Vente, regroupées par serveur. Chaque entrée contient l'item, le prix et le vendeur.

GET/api/stats/hdv

Retourne des statistiques de prix pour un item sur un serveur donné : prix moyen, minimum, maximum et nombre d'offres. La recherche est insensible à la casse et effectue une correspondance partielle sur le nom de l'item.

Paramètre	Type	Description
server	query string	Identifiant du serveur REQUIS
item	query string	Nom de l'item (recherche partielle) REQUIS

Exemple de réponse

JSON
{
  "server": "blue", "item_filter": "wood",
  "total_entries": 14,
  "statistics": {
    "average_price": 12.5,
    "min_price": 8,
    "max_price": 20,
    "price_count": 14
  },
  "sample": [ ... ] // max 50 entrées
}

GET/api/stats/servers

Retourne un snapshot en temps réel des joueurs connectés par serveur. Un filtre optionnel par serveur peut être appliqué.

Paramètre	Type	Description
server	query string	Filtrer sur un serveur spécifique Optionnel

Exemple de réponse

JSON
{
  "servers": [
    { "server": "blue", "online": true, "connected_players": 142 },
    // ...
  ]
}

GET/api/stats/serversAvg

Retourne la moyenne de joueurs connectés. Actuellement basé sur un snapshot temps réel uniquement (aucune donnée historique disponible).

Paramètre	Type	Description
server	query string	Filtrer sur un serveur spécifique Optionnel

Divers

GET/api/planning

Retourne le planning des événements NationsGlory pour un mois et une année donnés.

Paramètre	Type	Description
server	query string	Identifiant du serveur Défaut : all
month	query string	Mois (1–12) Défaut : 8
year	query string	Année Défaut : 2025

GET/api/staff

Retourne la liste complète des membres du staff NationsGlory.

GET/api/prime-players

Retourne la liste des joueurs ayant un abonnement Prime actif sur NationsGlory.

GET/api/items

Retourne la liste complète des items disponibles dans le jeu NationsGlory.

GET/api/furnitures

Retourne la liste complète des meubles disponibles dans le jeu NationsGlory.

GET/api/radio

Retourne les informations de la radio NationsGlory : titre en cours, artiste et flux.

GET/api/health

Health check de l'API. Retourne le statut de l'API SoCo ainsi que celui de l'API NationsGlory upstream. Utile pour vérifier la disponibilité du service avant d'effectuer des requêtes.

Requête exemple

URL
GET /api/health