API des exports publics

Chaque nuit, Fourmizzz publie pour chaque serveur deux fichiers JSON : la liste des joueurs et la liste des alliances. Ils ne contiennent que des données déjà publiques en jeu (classements, fiche d'alliance, diplomatie visible) et sont destinés aux joueurs et aux outils communautaires : cartes, suivi de progression, outils d'alliance.

L'API est en lecture seule, gratuite et sans authentification.

Le contrat complet au format OpenAPI 3, importable dans Swagger Editor, Postman ou un générateur de client, est disponible ici : api-exports.fr.openapi.yaml.

Adresse de l'API

L'API se sert sur l'adresse du serveur dont on veut les données :

Respecter le protocole indiqué : S1 à S4 et le serveur anglais ne sont servis qu'en HTTP, pas en HTTPS.

Chaque serveur a ses propres exports. Le domaine d'accueil (www.fourmizzz.fr, www.antzzz.org) et tout hôte qui n'est pas un serveur ouvert répondent 404.

Routes

Le / final fait partie de l'adresse : sans lui, le serveur répond d'abord une redirection 301 vers l'adresse avec slash. Mieux vaut l'écrire directement pour économiser un aller-retour.

Versions et historique

Une version est la date et l'heure UTC du passage du job d'export, au format AAAAMMJJHHmm (année, mois, jour, heure, minutes), par exemple 202609292200.

• Le job tourne chaque nuit à minuit, heure de Paris. En UTC, c'est donc la date de la veille : …2200 en heure d'été (ex. 202609292200 pour la nuit du 29 au 30 septembre), …2300 en heure d'hiver. UTC évite les heures en double ou manquantes aux changements d'heure.
• Aucune purge : tout l'historique reste disponible, ce qui permet de suivre une évolution jour après jour.
• Si le job est relancé dans la même minute, il écrase la version (nouvel en-tête Last-Modified) ; s'il est relancé plus tard, il crée une nouvelle version.

Liste des versions

GET /api/exports/ renvoie, pour chaque type d'export, les versions disponibles de la plus récente à la plus ancienne :

{
  "players": ["202609292200", "202609282200"],
  "alliances": ["202609292200", "202609282200"]
}

Les deux types sont générés au même passage du job et ont donc normalement les mêmes versions. Ils sont listés séparément car un passage peut échouer sur un seul type. Les tableaux sont vides ([]) si aucun export n'existe encore.

Paramètre version

• Absent ou version=latest : la version la plus récente de ce type, servie directement, sans redirection.
• version=AAAAMMJJHHmm : le fichier de cette version, tel qu'il a été déposé par le job.

La date, l'heure et les minutes doivent exister : 202602300000 (30 février), 202609292400 ou 202609292260 répondent 400, tout comme un format différent (2026-09-29, 2026092922) ou un tableau (version[]=…).

En-têtes de réponse

• Content-Type: application/json; charset=utf-8 sur toutes les réponses, erreurs comprises. Les caractères non ASCII sont échappés en séquences JSON \uXXXX, que tout parseur JSON décode.
• Last-Modified :
  • sur un fichier, la date exacte de sa dernière modification. Elle indique si une version a été régénérée ;
  • sur la liste des versions, la date du fichier le plus récent, tous types confondus (en-tête absent si aucun export n'existe).

Codes de réponse

Les erreurs sont toujours un objet JSON {"error": "<message>"}, jamais une page HTML. Le message est en français et n'est pas traduit : un outil doit se fier au code HTTP, pas au texte.

Fichier des joueurs

Un tableau d'objets, un par joueur, trié par id :

[
  {
    "id": 123,
    "pseudo": "Fourmi",
    "alliance": "TAG",
    "masterPlayerId": 456,
    "x": 10,
    "y": -4,
    "field": 98765,
    "grade": "Chef",
    "buildingScore": 1500,
    "technologyScore": 700,
    "trophyScore": 1234,
    "onHoliday": false,
    "isBanned": false
  }
]

Fichier des alliances

Un tableau d'objets, un par alliance, trié par tag :

[
  {
    "tag": "TAG",
    "name": "Les Fourmis",
    "playersCount": 12,
    "totalField": 5000000,
    "totalBuildingScore": 300,
    "totalTechnologyScore": 200,
    "totalTrophyScore": 9000,
    "diplomacy": {
      "pacts": [{ "tag": "AMI", "name": "Pacte de non-agression", "description": "…" }],
      "wars": ["ENN"]
    }
  }
]

Chaque pacte est un objet :

Données non exportées

Aucune donnée privée n'est exportée : ni e-mail, ni adresse IP, ni ressources, ni armée, ni date de dernière connexion, ni description ou règles d'alliance.

Exemples

Lister les versions du serveur S1, en-têtes compris :

curl -i http://s1.fourmizzz.fr/api/exports/

Télécharger le fichier des alliances d'une version précise :

curl -o alliances.json "http://s1.fourmizzz.fr/api/exports/alliances/?version=202609292200"

Charger la dernière version des joueurs en Python, bibliothèque standard uniquement :

import json
import urllib.request

with urllib.request.urlopen("http://s1.fourmizzz.fr/api/exports/players/") as reponse:
    joueurs = json.load(reponse)

sans_alliance = [j["pseudo"] for j in joueurs if j["alliance"] is None]
print(len(joueurs), "joueurs, dont", len(sans_alliance), "sans alliance")

Bonnes pratiques

• Une récupération par jour suffit : les fichiers ne changent qu'une fois par nuit. Interroger l'API en boucle n'apporte rien de plus.
• Pour savoir s'il y a du nouveau, interroger d'abord GET /api/exports/ et comparer la première version avec la dernière déjà téléchargée.
• Une version déjà téléchargée ne change plus, sauf relance du job dans la même minute : la conserver en cache plutôt que la télécharger à nouveau. En cas de doute, comparer l'en-tête Last-Modified.
• Un joueur s'identifie par le couple serveur + id, jamais par l'id seul, et le pseudo peut changer.