API de l'index de maps

L'index de maps derrière la page Parcourir a une petite API publique. Elle est en lecture seule, ne demande aucun compte et répond en JSON (sauf le fichier de chart). Soyez raisonnable : les réponses sont mises en cache et les requêtes limitées par adresse.

Identité d'un chart : le hash des notes

Un chart est identifié par le hash de ses notes : 64 caractères hexadécimaux minuscules, un condensé BLAKE3 du nombre de touches et de chaque note (début, colonne, type, fin d'une note longue) en millisecondes entières, relatives à la première note. Les mêmes notes donnent le même hash, qu'elles viennent d'un fichier .osu, .sm, .ssc ou .qua et quel que soit le nom du fichier ; les mines et les rafales sont ignorées ; la musique et les métadonnées ne comptent pas. La version du hash est renvoyée dans noteHashVersion. L'index ne contient que des charts osu!mania et Etterna de 4 à 7 touches.

GET /api/charts/{hash}

Où peut-on télécharger ce chart ? Un hash mal formé répond 400 ; un hash bien formé que l'index ne connaît pas répond 200 avec status: "unknown" (un client peut donc demander sans traiter d'erreur).

{
  "chartHash": "9f2c…64 hex…",
  "status": "known",
  "sources": [
    { "kind": "osuSet", "ref": "4001", "confidence": "verified", "checkedAtMs": 1791600000000 }
  ],
  "ttlMs": 300000,
  "chart": {
    "hash": "9f2c…", "noteHashVersion": 1, "keys": 7,
    "bpmMin": 120.0, "bpmMax": 180.0, "bpmMain": 180.0,
    "lengthMs": 144000, "notes": 1200, "lns": 40,
    "densityAvg": 8.3, "densityPeak": 14.0, "roxBytes": 5120,
    "title": "Song", "artist": "Artist", "creator": "Mapper", "difficulty": "7K Hard"
  }
}

kind est un ensemble ouvert (osuSet, etternaPack, ...) : ignorez les valeurs inconnues. ref est un identifiant, jamais une URL : un id de set osu!, un id de pack EtternaOnline. La page de la source est https://osu.ppy.sh/beatmapsets/<ref> ou https://etternaonline.com/packs/<ref>. La réponse porte un ETag et Cache-Control: public, max-age=300.

GET /api/charts/{hash}/rox

Le chart au format compact ROX (le format d'échange ouvert du jeu), servi à la demande comme pièce jointe (application/octet-stream, ETag: "<hash>", immutable). 404 si le chart est inconnu ou retiré. Jamais de musique, jamais d'image.

GET /api/chartsets

Les sets (un par dossier de chanson d'un set osu! ou d'un pack Etterna), les plus récents d'abord par défaut.

La réponse est { "items": [...], "total": n, "page": p, "perPage": n } ; chaque élément porte id, title, artist, creator, sourceKind, keys, bpmMin, bpmMax, lengthMinMs, lengthMaxMs, densityMax, chartCount et downloadUrl (/go/chartset/<id>, absent pour un set sans source publique).

GET /api/chartsets/{id}

Un set : les champs ci-dessus plus tags, sources et charts (chacun avec son objet chart, le nom de sa difficulty dans ce set et, pour osu!, son osuBeatmapId).

GET /go/chartset/{id}

Une redirection 302 vers la page de la source d'origine, où l'on télécharge la map. 404 pour un set sans source publique.

Limites et usages

• Les requêtes sont limitées par adresse (240 par minute par défaut pour chacun des trois groupes : consultation de charts, fichiers .rox, liste des sets) ; au-delà, la réponse est 429 avec Retry-After.
• Utilisez ETag / If-None-Match ; n'interrogez pas en boucle.
• Mettez un moyen de vous joindre dans votre User-Agent.
• Les créateurs sont crédités partout où un chart est montré. Pour faire retirer une entrée, utilisez la page Contact.