Public exports API

Every night, Fourmizzz publishes two JSON files for each server: the list of players and the list of alliances. They only contain data that is already public in the game (rankings, alliance page, visible diplomacy) and are intended for players and community tools: maps, progress tracking, alliance tools.

The API is read-only, free and requires no authentication.

The complete contract in OpenAPI 3 format, which can be imported into Swagger Editor, Postman or a client generator, is available here: api-exports.en.openapi.yaml.

API address

The API is served on the address of the server whose data you want:

Use the protocol shown: the English server and French S1 to S4 are only served over HTTP, not HTTPS.

Each server has its own exports. The home domain (www.antzzz.org, www.fourmizzz.fr) and any host that is not an open server answer 404.

Routes

The trailing / is part of the address: without it, the server first answers a 301 redirection to the address with a slash. Better write it directly and save a round trip.

Versions and history

A version is the UTC date and time of the export job run, formatted YYYYMMDDHHmm (year, month, day, hour, minutes), for example 202609292200.

• The job runs every night at midnight, Paris time. In UTC, this is therefore the date of the previous day: …2200 in summer time (e.g. 202609292200 for the night of September 29 to 30), …2300 in winter time. UTC avoids duplicated or missing hours when the clocks change.
• No purge: the whole history remains available, so an evolution can be tracked day after day.
• If the job is rerun within the same minute, it overwrites the version (new Last-Modified header); if it is rerun later, it creates a new version.

List of versions

GET /api/exports/ returns, for each export type, the available versions from newest to oldest:

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

Both types are generated by the same job run and should therefore have the same versions. They are listed separately because a run can fail on a single type. The arrays are empty ([]) if no export exists yet.

version parameter

• Absent or version=latest: the most recent version of this type, served directly, without redirection.
• version=YYYYMMDDHHmm: the file of this version, as uploaded by the job.

The date, hour and minutes must exist: 202602300000 (February 30), 202609292400 or 202609292260 answer 400, as does a different format (2026-09-29, 2026092922) or an array (version[]=…).

Response headers

• Content-Type: application/json; charset=utf-8 on every response, errors included. Non-ASCII characters are escaped as JSON \uXXXX sequences, which any JSON parser decodes.
• Last-Modified:
  • on a file, the exact date of its last modification. It tells whether a version has been regenerated;
  • on the list of versions, the date of the most recent file, all types combined (header absent if no export exists).

Status codes

Errors are always a JSON object {"error": "<message>"}, never an HTML page. The message is in French and is never translated: a tool should rely on the HTTP status code, not on the text.

Players file

An array of objects, one per player, sorted by 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
  }
]

Alliances file

An array of objects, one per alliance, sorted by 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"]
    }
  }
]

Each pact is an object:

Data not exported

No private data is exported: no email, no IP address, no resources, no army, no last login date, no alliance description or rules.

Examples

List the versions of the English server, headers included:

curl -i http://s1.antzzz.org/api/exports/

Download the alliances file of a specific version:

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

Load the latest version of the players in Python, standard library only:

import json
import urllib.request

with urllib.request.urlopen("http://s1.antzzz.org/api/exports/players/") as response:
    players = json.load(response)

without_alliance = [p["pseudo"] for p in players if p["alliance"] is None]
print(len(players), "players, including", len(without_alliance), "without an alliance")

Good practices

• One download per day is enough: the files only change once a night. Polling the API in a loop brings nothing more.
• To find out whether there is something new, first query GET /api/exports/ and compare the first version with the last one already downloaded.
• A version already downloaded no longer changes, unless the job is rerun within the same minute: keep it in cache rather than downloading it again. When in doubt, compare the Last-Modified header.
• A player is identified by the pair server + id, never by the id alone, and the nickname can change.