{"openapi":"3.1.0","info":{"title":"The Game Census read-only API","version":"1.0.0","summary":"Steam review, player-count and health-tier data recorded by The Game Census.","description":"Read-only JSON API over The Game Census's own recurring observations of Steam games plus facts Steam publishes publicly. No key required; open to every origin (CORS).\n\nOnly games with a public page on thegamecensus.com are returned; an id with no page is HTTP 404.\n\nRate limit: 20 requests per 10 seconds per IP address on /v1/ and /data/. Clients over the limit receive HTTP 429 with a Retry-After header. Responses are cached at the edge, so repeat requests are cheap; fetch bulk data from /v1/health-tiers or the CSV files under /data rather than looping over single-game endpoints.\n\nEvery response carries an X-Census-Licence header with the licence and citation. Please cite as: The Game Census (thegamecensus.com).","termsOfService":"https://thegamecensus.com/data","contact":{"name":"The Game Census","url":"https://thegamecensus.com/contact"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://thegamecensus.com"}],"security":[],"tags":[{"name":"games","description":"Per-game and bulk game data."},{"name":"discovery","description":"Search and review-velocity leaderboards."},{"name":"embeds","description":"Embeddable images."}],"paths":{"/v1/game/{appId}":{"get":{"tags":["games"],"operationId":"getGame","summary":"One game's current vital signs","description":"Review totals, health tier, latest and 30-day-peak concurrent players, and a sales-estimate range for one game.","parameters":[{"name":"appId","in":"path","required":true,"description":"Steam application id, canonical decimal (e.g. 730).","schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"The game.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Game"}}}},"404":{"description":"Unknown id, malformed id, or a game with no public page on thegamecensus.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not found"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/ccu/{appId}":{"get":{"tags":["games"],"operationId":"getCcuSeries","summary":"Daily concurrent-player series","description":"Daily maximum and average concurrent players from the census's own samples, oldest day first, at most the latest 400 days.","parameters":[{"name":"appId","in":"path","required":true,"description":"Steam application id, canonical decimal (e.g. 730).","schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"The series.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CcuSeries"}}}},"404":{"description":"Unknown id, malformed id, or a game with no public page on thegamecensus.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not found"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/reviews/{appId}":{"get":{"tags":["games"],"operationId":"getReviewSeries","summary":"Daily Steam review-total series","description":"Steam's cumulative positive and negative review totals as snapshotted daily by the census, oldest day first, at most the latest 400 snapshots.","parameters":[{"name":"appId","in":"path","required":true,"description":"Steam application id, canonical decimal (e.g. 730).","schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"The series.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewSeries"}}}},"404":{"description":"Unknown id, malformed id, or a game with no public page on thegamecensus.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not found"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/health-tiers":{"get":{"tags":["games"],"operationId":"listHealthTiers","summary":"Health tier of every game that has one","description":"One JSON array with an entry per game that has a public page and a computed health tier. Streamed; use this instead of looping over /v1/game.","responses":{"200":{"description":"The array.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HealthTier"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Too many exports running at once; retry after the number of seconds in Retry-After. Never cached.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search":{"get":{"tags":["discovery"],"operationId":"searchGames","summary":"Search games by name","description":"Case-insensitive exact match first (a single exact match returns only that game), otherwise fuzzy trigram match, at most 10 results. Only games with a public page are returned.","parameters":[{"name":"q","in":"query","required":true,"description":"Game name or part of it. 2 to 80 characters after whitespace normalisation.","schema":{"type":"string","minLength":2,"maxLength":80}}],"responses":{"200":{"description":"Matches, best first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}}},"400":{"description":"q missing or shorter than 2 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"q must be 2-80 characters"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/movers":{"get":{"tags":["discovery"],"operationId":"getMovers","summary":"Review-velocity movers","description":"Games whose Steam review inflow is running furthest above (rising) or below (falling) their own recent history. Method: Steam review count in the latest complete histogram bucket vs the same game's average over the 8 buckets before it. Without a direction both lists are returned.","parameters":[{"name":"direction","in":"query","required":false,"description":"Return only this list.","schema":{"type":"string","enum":["rising","falling"]}},{"name":"limit","in":"query","required":false,"description":"Maximum rows per list.","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}}],"responses":{"200":{"description":"The leaderboard(s).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Movers"}}}},"400":{"description":"direction is not rising or falling, or limit is not an integer in range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"direction must be rising or falling"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/badge/{appId}.svg":{"get":{"tags":["embeds"],"operationId":"getPlayerBadge","summary":"Embeddable live player-count badge","description":"An SVG badge showing the game's current player count, for README files and web pages. Edge-cached for 15 minutes.","parameters":[{"name":"appId","in":"path","required":true,"description":"Steam application id, canonical decimal (e.g. 730).","schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"The badge.","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"Unknown id, malformed id, or a game with no public page on thegamecensus.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not found"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/openapi.json":{"get":{"tags":["discovery"],"operationId":"getOpenApiDocument","summary":"This document","responses":{"200":{"description":"The OpenAPI 3.1 description of this API.","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"responses":{"RateLimited":{"description":"Rate limit exceeded (20 requests per 10 seconds per IP on /v1/ and /data/). Wait Retry-After seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}}},"ServerError":{"description":"Internal error. Never cached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Game":{"type":"object","required":["app_id","name","slug","release_date","is_free","reviews","health","ccu","sales_estimate","url"],"properties":{"app_id":{"type":"integer","description":"Steam application id."},"name":{"type":"string","description":"Game name as listed on Steam."},"slug":{"type":"string","description":"Page slug: https://thegamecensus.com/game/{slug}."},"release_date":{"type":["string","null"],"format":"date","description":"Steam release date; null when Steam gives none."},"is_free":{"type":["boolean","null"],"description":"True when Steam lists the game as free to play."},"reviews":{"type":"object","required":["positive","negative","snap_date"],"properties":{"positive":{"type":["integer","null"],"description":"Positive Steam reviews at the last census snapshot."},"negative":{"type":["integer","null"],"description":"Negative Steam reviews at the last census snapshot."},"snap_date":{"type":["string","null"],"format":"date","description":"Date of the most recent daily review snapshot held for the game."}}},"health":{"description":"Census health tier; null when none has been computed.","oneOf":[{"type":"null"},{"type":"object","required":["tier","label","computed_at"],"properties":{"tier":{"type":"string","description":"thriving, healthy, cooling, quiet, dormant or unknown."},"label":{"type":["string","null"],"description":"Display label for the tier."},"computed_at":{"type":["string","null"],"format":"date-time","description":"When the tier was last computed (UTC)."}}}]},"ccu":{"type":"object","required":["latest","latest_at","peak_30d"],"properties":{"latest":{"type":["integer","null"],"description":"Most recent concurrent-player sample; may be older than a day."},"latest_at":{"type":["string","null"],"format":"date-time","description":"When that sample was taken (UTC)."},"peak_30d":{"type":["integer","null"],"description":"Highest sample in the last 30 days; null when there was none."}}},"sales_estimate":{"description":"Estimated copies-sold range (review-multiple method, see /methodology); null for free-to-play games and games with fewer than 50 reviews.","oneOf":[{"type":"null"},{"type":"object","required":["low","high"],"properties":{"low":{"type":"integer"},"high":{"type":"integer"}}}]},"url":{"type":"string","format":"uri","description":"The game's page on thegamecensus.com."}}},"CcuSeries":{"type":"object","required":["app_id","name","slug","url","series"],"properties":{"app_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"series":{"type":"array","description":"Oldest day first.","items":{"type":"object","required":["date","max","avg","samples"],"properties":{"date":{"type":"string","format":"date","description":"UTC calendar day."},"max":{"type":"number","description":"Highest concurrent-player sample that day."},"avg":{"type":"number","description":"Mean of that day's samples, to one decimal."},"samples":{"type":"integer","description":"Samples behind max and avg; days with few are less reliable."}}}}}},"ReviewSeries":{"type":"object","required":["app_id","name","slug","url","series"],"properties":{"app_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"series":{"type":"array","description":"Oldest day first.","items":{"type":"object","required":["date","positive","negative","steam_review_score"],"properties":{"date":{"type":"string","format":"date","description":"Snapshot day."},"positive":{"type":"integer","description":"Cumulative positive Steam reviews."},"negative":{"type":"integer","description":"Cumulative negative Steam reviews."},"steam_review_score":{"type":["integer","null"],"description":"Steam's own 0-9 review-score bucket (its review_score field); null when not recorded."}}}}}},"HealthTier":{"type":"object","required":["app_id","slug","tier","current_players"],"properties":{"app_id":{"type":"integer"},"slug":{"type":"string"},"tier":{"type":"string","description":"thriving, healthy, cooling, quiet, dormant or unknown."},"current_players":{"type":["integer","null"],"description":"In-game players at the last tier computation; null when no sample from the preceding 2 hours existed."}}},"SearchResults":{"type":"object","required":["q","results"],"properties":{"q":{"type":"string","description":"The normalised query."},"results":{"type":"array","maxItems":10,"items":{"type":"object","required":["app_id","name","slug","reviews","steam_review_label","url"],"properties":{"app_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"reviews":{"type":"integer","description":"Total Steam reviews (positive + negative)."},"steam_review_label":{"type":["string","null"],"description":"Steam's own review label, e.g. Very Positive; null when Steam gives none."},"url":{"type":"string","format":"uri"}}}}}},"Mover":{"type":"object","required":["rank","app_id","name","slug","url","recent_reviews","baseline_reviews","delta_pct","recent_period_start"],"properties":{"rank":{"type":"integer","minimum":1},"app_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"recent_reviews":{"type":"integer","description":"Steam reviews in the latest complete histogram bucket."},"baseline_reviews":{"type":"integer","description":"The game's average reviews per bucket over the 8 buckets before the latest (rounded)."},"delta_pct":{"type":["integer","null"],"description":"Percent change of recent_reviews over the baseline; negative when falling."},"recent_period_start":{"type":["string","null"],"format":"date","description":"Start date of the latest complete bucket (the period recent_reviews covers)."}}},"Movers":{"type":"object","required":["method","computed_at"],"properties":{"method":{"type":"string"},"computed_at":{"type":["string","null"],"format":"date-time","description":"When the leaderboard was last materialised (UTC); null when it was ranked live."},"rising":{"type":"array","items":{"$ref":"#/components/schemas/Mover"}},"falling":{"type":"array","items":{"$ref":"#/components/schemas/Mover"}}}}}}}