A read-only HTTP API providing aggregated player-population data for a StalCraft game server instance. All responses are returned as JSON, encoded in UTF-8.
https://api.szstate.ru/{endpoint}?key=
All requests are made over HTTPS using the GET method.
Requests must include a key query parameter. In the current API version this parameter is accepted with an empty value. Key issuance and validation will be enforced in a subsequent version without altering the request format described in this document.
Each client IP address is limited to 10 requests per 60-second window. The window is fixed and resets on expiry. Every response, except /rateLimit, includes the following headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests permitted per window (10) |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp marking the end of the current window |
Requests exceeding the limit receive HTTP 429 with a Retry-After header specifying seconds until reset.
Returns the current player count at the time of the request.
| Field | Type | Description |
|---|---|---|
current | integer | Number of players currently online |
server_time | string | Timestamp of response generation, YYYY-MM-DD HH:MM:SS |
{"current": 11815, "server_time": "2026-08-22 12:00:00"}
Returns average player-count values over several rolling time periods.
| Field | Type | Description |
|---|---|---|
today_avg | integer | Average over the current day |
week_avg | integer | Average over the current week |
month_avg | integer | Average over the current month |
year_avg | integer | Average over the current year |
server_time | string | Timestamp of response generation |
{"today_avg": 12873, "week_avg": 13504, "month_avg": 13564, "year_avg": 14278, "server_time": "2026-08-22 12:00:00"}
Returns a time series of aggregated player-count data points for a specified reporting period.
| Parameter | Type | Required | Description |
|---|---|---|---|
time | enum | No — defaults to day | Reporting period. One of: day, week, month, year |
count | integer | No | Number of most recent data points to return, counted backward from the newest available point. Maximum permitted value is 10; higher values are clamped. When omitted, all available points for the selected period are returned. |
offset | integer | No — defaults to 0 | Number of points to skip, counted backward from the newest available point. |
points differs by reporting period, as detailed below. Consumers should branch on the time value used in the request when parsing point objects.| Field | Type | Description |
|---|---|---|
t | integer | Unix timestamp in milliseconds marking the data point |
v | integer | Player count at that point |
label | string | Human-readable timestamp, YYYY-MM-DD HH:MM:SS |
maintenance | boolean | Whether this point overlapped with a scheduled maintenance window |
{"t": 1787348581713, "v": 11139, "label": "2026-08-22 00:43:01", "maintenance": false}
| Field | Type | Description |
|---|---|---|
week_start | string | Timestamp marking the start of the aggregation interval |
avg, min, max | integer | Player count statistics within the interval |
maintenance | boolean | Whether the interval overlapped with a scheduled maintenance window |
{"week_start": "2026-08-21 23:30:00", "avg": 14119, "min": 13194, "max": 14962, "maintenance": false}
| Field | Type | Description |
|---|---|---|
date | string | Calendar date, YYYY-MM-DD |
avg, min, max | integer | Player count statistics within the day |
maintenance | boolean | Whether the day included a scheduled maintenance window |
{"date": "2026-07-23", "avg": 17013, "min": 4648, "max": 37021, "maintenance": false}
| Field | Type | Description |
|---|---|---|
week_start | string | Timestamp marking the start of the aggregation interval |
avg, min, max | integer | Player count statistics within the interval |
maintenance | boolean | Whether the interval overlapped with a scheduled maintenance window |
{"week_start": "2025-08-22 01:00:00", "avg": 5970, "min": 5970, "max": 5970, "maintenance": false}
{
"time": "week", "count": 2, "offset": 0, "total": 336,
"points": [ /* objects as documented above for the selected period */ ],
"server_time": "2026-08-22 12:00:00"
}
Returns the current rate-limit window status for the requesting IP address. This endpoint does not itself count against the rate limit.
| Field | Type | Description |
|---|---|---|
limit | integer | Maximum requests permitted per window |
used | integer | Requests already counted within the current window |
remaining | integer | Requests remaining in the current window |
reset_in | integer | Seconds remaining until the window resets |
{"limit": 10, "used": 3, "remaining": 7, "reset_in": 42, "server_time": "2026-08-22 12:00:00"}
Errors are returned with an appropriate HTTP status code and a JSON body containing an error field.
| HTTP Status | error | Description |
|---|---|---|
| 400 | invalid_time_use_day_week_month_year | The time parameter was not one of the accepted values |
| 404 | not_found | The requested data resource could not be located |
| 429 | rate_limit_exceeded | The rate limit has been exceeded; see the Retry-After header |
| 500 | invalid_data | The underlying data resource is missing or malformed |