# FNTerminal API: integration brief for AI agents

Context: you are connecting an application to FNTerminal, a free public API with live data on every Fortnite Creative and UEFN island (players, rankings, retention, estimated earnings, Discover rows). Read this whole brief before writing code.

## Essentials
- Base URL: https://fnterminal.live/api/v1 (HTTPS, GET only, JSON responses, no API key, CORS enabled: callable from a browser).
- Full reference (OpenAPI 3.1): https://fnterminal.live/api/v1/openapi.json. Generate your types from it or follow it exactly.
- Rate limit: 120 requests per minute per IP (fewer for expensive lists: deep offsets, broad filters). On HTTP 429, wait `retryAfterSeconds` (in the JSON body, also the Retry-After header) before retrying.
- Freshness: data refreshes every 10 minutes and responses are cached for 60 s. Cache results on your side for at least 60 s and never poll the same URL more than once a minute. For several islands, call the list endpoint once instead of one island at a time.
- Attribution: wherever the data is shown, display “Data: FNTerminal” linking to https://fnterminal.live. Don’t present the data as coming from Epic Games, and don’t suggest that Epic or FNTerminal endorses the app.

## Endpoints
1. GET /islands: list and filter islands.
   Params: sort (players|rising|falling|earnings|peak|plays|retention|newest, default players), limit (1–200, default 50), offset (up to 10,000), genre, tag, creator, q (title search, 60 characters max), minPlayers, epic (true|false).
   Returns { sort, limit, offset, count, islands: Island[] }.
2. GET /islands/{code}: one island. Creator island codes look like 1234-5678-9012; Epic’s own modes use names such as experience_br or playlist_… (always URL-encode the code).
   Params: series (6h|1d|1w|1m|3m|1y|all), metric (ccu|plays|uniq|minutes|avg_min|favs|recs|ret_d1|ret_d7|grank, default ccu), include (comma-separated: media,versions,discover,totals).
   Returns { island: IslandDetail, series?, media?, versions?, discover? }. 404 when the code is unknown.
3. GET /ecosystem: players in Fortnite right now, today’s curve and daily peaks.
4. GET /heatmap: the genre heatmap, live islands grouped by genre with their players now and 24 hours ago.
   Params: mode (most|rising|falling, default most), genre, limit (1–600, default 200).
   Returns { at, mode, genre, limit, count, genres: [{ genre, label, players, players24hAgo, change24h, count, islands: [{ code, title, url, image, players, players24hAgo, change24h }] }] }.

## Data rules
- `players.now` is null when the island isn’t live; `players.lastSeen` keeps the last value. Epic hides values under 5: expect null anywhere a number is expected.
- Ratios (change1h, change24h, change7d, retention.day1/day7) are decimals: 0.125 = 12.5%.
- Dates are ISO 8601 strings in UTC.
- `estimatedEarnings` comes from a model based on playtime, not from Epic’s figures: always label it as an estimate, ideally with the low–high range. It is null for Epic’s own modes and when the day’s stats are missing.
- Images: `island.image` (1280 px WebP); smaller: https://fnterminal.live/img/island/{code}?w=256 or ?w=640.
- `series.points` is an array of [isoDate, value|null].

## Ready-made embeds (no code)
- Live badge (SVG): https://fnterminal.live/api/badge/{code} (add ?lang=fr for French).
- Widget (360 × 200 card): <iframe src="https://fnterminal.live/embed/island/{code}" width="360" height="200" style="border:0;border-radius:16px" loading="lazy"></iframe> (add ?lang=fr for French, ?theme=light for the light theme).

## Checklist
1. Write a small typed client: fetch with a 10 s timeout, check `res.ok`, handle 400/404/429/5xx, and retry 429 and 5xx with backoff (3 tries max).
2. Cache responses (memory, KV or your framework’s cache) for 60 s or more, keyed by URL.
3. Call FNTerminal from your server when you can (one cache shared by all users); browser calls are allowed too.
4. Handle nulls everywhere, format numbers for the user’s locale and show “—” for missing values.
5. Show the attribution link.

## Example
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, … }, … } ] }

API terms of use: https://fnterminal.live/legal/terms#api
