Les données en direct de toutes les îles Fortnite dans vos propres outils : une API JSON gratuite avec un brief pour les agents de code IA, des badges pour un README ou Discord, un widget pour votre site et des exports CSV. Les données viennent de l’API officielle Fortnite Data.
Vous créez votre application avec Claude, ChatGPT, Cursor ou Copilot ? Donnez ce brief à votre assistant avec votre demande. Il explique comment appeler l’API, ce que veut dire chaque champ et les règles à respecter, pour que le code fonctionne du premier coup.
Brief pour l’agent
ENFR
# API FNTerminal : brief d’intégration pour agent IA
Contexte : tu connectes une application à FNTerminal, une API publique et gratuite qui donne les données en direct de toutes les îles Fortnite Créatif et UEFN (joueurs, classements, rétention, revenus estimés, rangées Découvrir). Lis tout ce brief avant d’écrire du code.
## L’essentiel
- URL de base : https://fnterminal.live/api/v1 (HTTPS, uniquement des GET, réponses JSON, aucune clé d’API, CORS ouvert : appelable depuis un navigateur).
- Référence complète (OpenAPI 3.1) : https://fnterminal.live/api/v1/openapi.json. Génère tes types à partir d’elle ou suis-la à la lettre.
- Limite : 120 requêtes par minute et par adresse IP (moins pour les listes coûteuses : gros offsets, filtres larges). En cas de HTTP 429, attends `retryAfterSeconds` (dans le JSON, aussi dans l’en-tête Retry-After) avant de réessayer.
- Fraîcheur : les données se mettent à jour toutes les 10 minutes et les réponses sont en cache 60 s. Garde les résultats en cache au moins 60 s de ton côté et n’interroge jamais une même URL plus d’une fois par minute. Pour plusieurs îles, appelle la liste une fois plutôt qu’une île à la fois.
- Mention obligatoire : partout où les données s’affichent, mets « Données : FNTerminal » avec un lien vers https://fnterminal.live. Ne présente pas les données comme venant d’Epic Games et ne laisse pas entendre qu’Epic ou FNTerminal approuve l’application.
## Points d’accès
1. GET /islands : liste et filtre les îles.
Paramètres : sort (players|rising|falling|earnings|peak|plays|retention|newest, par défaut players), limit (1 à 200, par défaut 50), offset (jusqu’à 10 000), genre, tag, creator, q (recherche dans les titres, 60 caractères max), minPlayers, epic (true|false).
Réponse : { sort, limit, offset, count, islands: Island[] }.
2. GET /islands/{code} : une île. Les codes des îles de créateurs ressemblent à 1234-5678-9012 ; ceux des modes d’Epic sont des noms comme experience_br ou playlist_… (encode toujours le code dans l’URL).
Paramètres : series (6h|1d|1w|1m|3m|1y|all), metric (ccu|plays|uniq|minutes|avg_min|favs|recs|ret_d1|ret_d7|grank, par défaut ccu), include (liste séparée par des virgules : media,versions,discover,totals).
Réponse : { island: IslandDetail, series?, media?, versions?, discover? }. 404 si le code est inconnu.
3. GET /ecosystem : joueurs dans Fortnite en ce moment, courbe du jour et pics quotidiens.
4. GET /heatmap : la heatmap des genres, les îles en ligne regroupées par genre avec leurs joueurs maintenant et il y a 24 h.
Paramètres : mode (most|rising|falling, par défaut most), genre, limit (1 à 600, par défaut 200).
Réponse : { at, mode, genre, limit, count, genres: [{ genre, label, players, players24hAgo, change24h, count, islands: [{ code, title, url, image, players, players24hAgo, change24h }] }] }.
## Règles sur les données
- `players.now` vaut null quand l’île n’est pas en ligne ; `players.lastSeen` garde la dernière valeur. Epic masque les valeurs inférieures à 5 : attends-toi à null partout où un nombre est prévu.
- Les ratios (change1h, change24h, change7d, retention.day1/day7) sont des décimaux : 0.125 = 12,5 %.
- Les dates sont des chaînes ISO 8601 en UTC.
- `estimatedEarnings` est un modèle fondé sur le temps de jeu, pas un chiffre d’Epic : affiche-le toujours comme une estimation, de préférence avec la fourchette low–high. Il vaut null pour les modes d’Epic et quand les statistiques du jour manquent.
- Images : `island.image` (WebP 1280 px) ; plus petites : https://fnterminal.live/img/island/{code}?w=256 ou ?w=640.
- `series.points` est un tableau de [dateISO, valeur|null].
## Intégrations prêtes à l’emploi (sans code)
- Badge en direct (SVG) : https://fnterminal.live/api/badge/{code} (ajoute ?lang=fr pour le français).
- Widget (carte 360 × 200) : <iframe src="https://fnterminal.live/embed/island/{code}?lang=fr" width="360" height="200" style="border:0;border-radius:16px" loading="lazy"></iframe> (ajoute &theme=light pour le thème clair).
## Liste de contrôle
1. Écris un petit client typé : fetch avec un délai de 10 s, vérifie `res.ok`, gère 400/404/429/5xx et réessaie les 429 et 5xx avec un délai croissant (3 essais max).
2. Mets les réponses en cache (mémoire, KV ou cache du framework) 60 s ou plus, par URL.
3. Appelle FNTerminal depuis ton serveur quand c’est possible (un cache partagé par tous les utilisateurs) ; les appels depuis le navigateur sont aussi autorisés.
4. Gère les null partout, formate les nombres dans la langue de l’utilisateur et affiche « — » pour une valeur absente.
5. Affiche la mention avec le lien.
## Exemple
GET https://fnterminal.live/api/v1/islands?sort=players&limit=3
→ { "sort": "players", "limit": 3, "offset": 0, "count": 3, "islands": [ { "code": "…", "title": "…", "players": { "now": 123456, … }, … } ] }
Conditions d’utilisation de l’API : https://fnterminal.live/legal/terms#api
Comment faire
01Copiez le briefOu téléchargez-le et ajoutez-le à votre projet comme fichier de règles (AGENTS.md, CLAUDE.md, .cursor/rules…).
02Collez-le dans votre assistantPuis décrivez ce que vous voulez construire. Les exemples de demandes ci-dessous sont un bon point de départ.
03Vérifiez le résultatLe code doit garder les réponses en cache, gérer les valeurs null et afficher le lien vers FNTerminal.
Docs lisibles par les machines
Les agents qui naviguent sur le web lisent ces fichiers seuls. Générez un client typé à partir du fichier OpenAPI.
Collez-en une après le brief, puis adaptez-la à votre projet.
Page des meilleures îles
Avec l’API FNTerminal décrite ci-dessus, crée une page qui liste les 10 îles avec le plus de joueurs en ce moment : miniature, titre, créateur, joueurs actuels et évolution sur 24 heures. Récupère les données côté serveur, garde-les en cache 60 secondes et affiche le lien « Données : FNTerminal ».
Commande de bot Discord
Avec l’API FNTerminal décrite ci-dessus, ajoute une commande /island <code> à mon bot Discord. Elle répond avec un embed : titre, miniature, joueurs actuels, évolution sur 24 heures, pic sur 24 heures et record absolu. Gère les codes inconnus (404) et les limites de requêtes (429).
Suivi des joueurs
Avec l’API FNTerminal décrite ci-dessus, écris un script qui enregistre les joueurs de mon île toutes les 10 minutes dans un fichier CSV (heure, joueurs actuels, parties des dernières 24 heures) et qui continue de tourner après une erreur réseau.