0xDocs 0x.limo

Docs / REST API

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.

RouteDoes
POST /v1/plays {app, mode, source, ref?}start a play → {play, history, beat_secs}
POST /v1/plays/{play}/beatstill playing; send about once a minute (beat_secs)
POST /v1/plays/{play}/endthe play ended
  • mode is native or web. source is launcher, link, direct or other. ref is 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, ref and 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. history in the answer says whether this play is kept.
bash
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}

What you get back as a developer:

  • GET /v1/catalog/live gives the plays going on now per world (Catalog).
  • GET /v1/catalog/stats gives plays and time played over 7 days and 24 hours (Catalog).
  • GET /v1/apps/{appid}/players returns {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

RouteDoes
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/playsthe caller's own play history (the 500 latest; empty without consent)
PUT /v1/me/wishlist/{appid} / GET /v1/me/wishlistthe wishlist (follow a world), at most 1000
bashtested
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).

RouteDoes
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)
bash
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}}'
  • stats values are numbers. achievements maps 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

RouteReturns
GET /v1/apps/{appid}/global_statstotals of the schema's aggregated stats and their daily changes (newest first, up to 60 days)
GET /v1/apps/{appid}/achievement_percentageseach achievement's share of players, most achieved first
GET /v1/apps/{appid}/achievementspublic, store page: achievements with display names, icons and percentages

Leaderboards are on Achievements and leaderboards.

See the generated apps reference.