Plays and stats
Play sessions and where players come from, the player's library and play history, per-player stats and achievements, global stats and live player counts.
#Plays
A play is one session of one player in one game. The launcher reports plays for every game it starts, so a game run from the launcher doesn't have to do anything. A hosted page opened outside the launcher can report its own plays with the same routes.
| Route | Does |
|---|---|
POST /v1/plays {app, mode, source, ref?} | start a play → {play, history, beat_secs} |
POST /v1/plays/{play}/beat | still playing; send about once a minute (beat_secs) |
POST /v1/plays/{play}/end | the play ended |
modeisnativeorweb.sourceislauncher,link,directorother.refis an optional link reference, so you can see which of your links brought players in.- Each beat or end adds the time since the previous call, at most 10 minutes, so a client that vanishes doesn't add hours.
- Plays are counted anonymously per hour, world, mode, source,
refand country. The address is used only to find the country; it isn't stored. - A player who consented to a play history also gets a row per play.
historyin the answer says whether this play is kept.
curl -s https://api.0x.limo/v1/plays -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"app": 4000009, "mode": "web", "source": "link", "ref": "devlog-12"}'
# {"play": "5d1f0c9a7e2b44c18a6f3b2d9e0c7a41", "history": false, "beat_secs": 60}const api = "https://api.0x.limo", auth = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
const { play, beat_secs } = await fetch(`${api}/v1/plays`, { method: "POST", headers: auth,
body: JSON.stringify({ app: 4000009, mode: "web", source: "direct" }) }).then(r => r.json());
const beat = setInterval(() => fetch(`${api}/v1/plays/${play}/beat`, { method: "POST", headers: auth }), beat_secs * 1000);
addEventListener("pagehide", () => { clearInterval(beat); fetch(`${api}/v1/plays/${play}/end`, { method: "POST", headers: auth, keepalive: true }); });What you get back as a developer:
GET /v1/catalog/livegives the plays going on now per world (Catalog).GET /v1/catalog/statsgives plays and time played over 7 days and 24 hours (Catalog).GET /v1/apps/{appid}/playersreturns{players}, the players in the app now (reported in the last 3 minutes).
The figures are what clients report. Nothing here is billed or enforced.
#Library and play history
| Route | Does |
|---|---|
GET /v1/me/library | {items: [{appid, added_at, last_played, playtime_secs, plays}]} |
PUT /v1/me/library/{appid} | add a listed or owned world |
DELETE /v1/me/library/{appid} | remove one; it stays hidden even if the play history mentions it |
GET /v1/me/consent / PUT /v1/me/consent {play_history} | the player's consent; withdrawing it deletes the history |
GET /v1/me/plays | the caller's own play history (the 500 latest; empty without consent) |
PUT /v1/me/wishlist/{appid} / GET /v1/me/wishlist | the wishlist (follow a world), at most 1000 |
curl -s https://api.0x.limo/v1/me/library -H "Authorization: Bearer $ZEROX_TOKEN"Play history is kept for 180 days. Anonymous counts are kept for 400 days.
#Player stats
Stats and achievements follow ISteamUserStats. A game defines its stats and achievements in its app
schema (GET /v1/apps/{appid}, which also says whether the caller owns the app).
| Route | Does |
|---|---|
GET /v1/apps/{appid}/userstats/{steamid} | {stats: {name: number}, achievements: {name: unlock_time}} |
PUT /v1/apps/{appid}/userstats/{steamid} | store your own stats (a player), or a player's stats in your app (game-server session) |
curl -s -X PUT https://api.0x.limo/v1/apps/4000009/userstats/76561197960287930 \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"stats": {"wins": 12, "best_lap_ms": 61840}, "achievements": {"FIRST_WIN": 1792250000}}'statsvalues are numbers.achievementsmaps a name to its unlock time (Unix seconds); an object{achieved, unlock_time}is accepted too.- The schema's rules apply on the server side: min/max values and increment-only stats.
- Writing another player's stats as a player gets
403 can only write own stats.
#Global stats
| Route | Returns |
|---|---|
GET /v1/apps/{appid}/global_stats | totals of the schema's aggregated stats and their daily changes (newest first, up to 60 days) |
GET /v1/apps/{appid}/achievement_percentages | each achievement's share of players, most achieved first |
GET /v1/apps/{appid}/achievements | public, store page: achievements with display names, icons and percentages |
Leaderboards are on Achievements and leaderboards.
See the generated apps reference.
