API publique du PurpleSMP

Obtenir une clé

Chaque appel doit porter une clé. Elles sont distribuées à la main, une par projet, uniquement par ticket sur le Discord — c'est le seul canal : aucun formulaire, aucune inscription automatique.

Ouvrir un ticket sur le Discord

Portées

Une clé porte une ou plusieurs portées. Demande celles dont ton projet a besoin :

• stats Statistiques : classements, joueurs, villages, royaumes, commandes
• quetes Quêtes communautaires : objectif, paliers, progression, classement
• videos Vidéos et lives des créateurs : lecture de ce qui est publié sur /videos
• videos-envoi Vidéos et lives : dépôt des publications (réservé au bot Discord)

Faire un appel

Toutes les routes sont en GET, répondent en JSON UTF-8, et vivent sous https://purplesmp.fr/api/v1. La clé se transmet dans l'en-tête Authorization :

curl -H "Authorization: Bearer TA_CLE" \
     "https://purplesmp.fr/api/v1/stats/classements?metrique=playtime&limite=10"

Deux variantes existent, dans cet ordre de préférence : l'en-tête X-API-Key: TA_CLE, et le paramètre d'URL ?cle=TA_CLE. Le paramètre rend l'API testable depuis un navigateur, mais il finit dans les journaux d'accès et les historiques : réserve-le à tes essais, jamais à la production.

// JavaScript
const r = await fetch("https://purplesmp.fr/api/v1/quetes/actuelle", {
  headers: { Authorization: "Bearer TA_CLE" }
});
const { data } = await r.json();
console.log(data.nom, data.progression.total);

# Python
import requests

r = requests.get(
    "https://purplesmp.fr/api/v1/stats/joueurs/Notch",
    headers={"Authorization": "Bearer TA_CLE"},
    timeout=10,
)
print(r.json()["data"]["temps_de_jeu"]["libelle"])

Format des réponses

Succès comme erreur, l'enveloppe est la même : un booléen ok à tester en premier, puis data ou error. Un client n'a donc qu'un seul cas à écrire.

{
  "ok": true,
  "meta": {
    "saison": { "slug": "actuelle", "nom": "Saison 2", "en_cours": true },
    "classement": "playtime",
    "libelle": "Temps de jeu",
    "unite": "de jeu",
    "version": "v1",
    "generated_at": "2026-09-05T06:22:24+02:00"
  },
  "data": [
    { "rang": 1, "pseudo": "…", "uuid": "…", "valeur": 1284300, "affichage": "14 j 20 h" }
  ]
}

{
  "ok": false,
  "error": { "code": "rate_limited", "message": "Quota dépassé : 60 requêtes par minute…" }
}

Le bloc meta rappelle toujours la saison servie, et porte la pagination quand la route en a une (total, page, par_page, pages). Les valeurs numériques brutes sont accompagnées de leur version formatée (affichage) : à toi de choisir laquelle afficher.

Choisir une saison

Le serveur repart de zéro à chaque saison. Le site en garde un instantané complet, et l'API le sert : toutes les routes de statistiques acceptent ?saison=.

• ?saison=actuelle — ou rien du tout : la saison en cours, lue en direct.
• ?saison=saison-1 — une saison terminée, telle qu'elle était à sa clôture.

La liste des slugs disponibles est renvoyée par GET /saisons. Un slug inconnu répond 404 season_not_found plutôt que de retomber silencieusement sur la saison en cours — mieux vaut une erreur qu'un graphique faux.

Pour les quêtes, la saison est portée par la clé de quête elle-même : s:saison-1:12. Voir la section quêtes plus bas.

Quotas et erreurs

Chaque clé a deux limites : 60 requêtes par minute et 5 000 par jour par défaut. Elles sont ajustables à la demande, dans le même ticket.

Chaque réponse porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Daily-Remaining : surveille-les plutôt que de compter toi-même. Un dépassement répond 429 avec un en-tête Retry-After en secondes.

Tous les appels sont journalisés, refus compris : route, adresse IP, agent, durée. Une clé qui sature ses quotas en boucle, qui est partagée publiquement ou qui sert à autre chose que ce qui a été annoncé peut être bloquée sans préavis.

Ce que l'API ne donne pas

L'API sert exactement ce que les pages publiques montrent aux joueurs — ni plus, ni moins. Ce n'est pas une politique déclarative : chaque route rejoue le code de la page correspondante et passe par une liste blanche de champs.

Ne sont donc accessibles par aucun moyen :

• la présence en ligne d'un joueur, et son historique de connexions détaillé ;
• sa position en jeu — monde, coordonnées, point de retour ;
• les adresses IP, adresses e-mail et identifiants de compte ;
• les achats, paiements et transactions de la boutique ;
• les sanctions, signalements et notes du staff ;
• l'inventaire, les enderchests et les coffres.

Si un module est désactivé sur le site (villages, commandes…), sa route répond 404 : ce qui est caché aux visiteurs l'est aussi aux clés.

Saisons

Toutes les routes de statistiques et de quêtes acceptent une saison. Commence par celle-ci pour connaître les slugs disponibles.

Classements stats

Les mêmes classements que la page /stats/classements, classement global compris.

Joueurs stats

L'explorateur de joueurs et les fiches, à l'identique de /stats/joueurs.

Villages & royaumes stats

La carte politique du serveur, avec les membres, les classements hebdomadaires et le détail des points.

Commandes stats

Les ordres d'achat déposés par les joueurs, comme sur /stats/commandes.

Quêtes communautaires quetes

La quête se désigne par une clé : « actuelle », « prochaine », « q<id> » pour une quête précise, ou « s:<saison>:<id> » pour une quête de saison archivée. Ce sont les mêmes clés que le sélecteur du site.

Vidéos des créateurs videos

Les vidéos et les lives affichés sur /videos. Ils sont déposés par le bot Discord, qui surveille les chaînes YouTube, Twitch et TikTok des créateurs et ne retient que les publications parlant du serveur.

Une question, un besoin particulier ?

Un champ manquant, un quota trop serré, une route qui te rendrait service : passe par le même ticket. L'API est faite pour les projets de la communauté, elle évolue avec eux.

Rejoindre le Discord