# Hydro Vanilla SMP — Public Statistics API

> A free, public, read-only REST API over the player statistics of Hydro Vanilla SMP,
> a whitelisted community Minecraft server running since 2018 with full Java and
> Bedrock cross-play. It exposes the same data as https://stats.hydrosmp.com.

Base URL: https://api.hydrosmp.com/v1
Documentation: https://api.hydrosmp.com/
OpenAPI 3.1 spec: https://api.hydrosmp.com/openapi.json

## Access

- No authentication. No API key, no signup, no headers required.
- GET and HEAD only. The API is strictly read-only and accepts no request body of any kind.
- CORS is open (`Access-Control-Allow-Origin: *`), so browser clients work directly.
- Rate limit: 240 requests per minute per IP address, reported in `RateLimit-*` headers.
- Errors use RFC 9457 Problem Details (`application/problem+json`).

## Response shape

Every successful response is `{ "data": ..., "meta": ... }`. `data` is the resource or
array of resources; `meta` carries pagination and `data_updated_at`, the ISO 8601 UTC
timestamp of the last statistics regeneration. Collections take `limit` (default 50,
max 500) and `offset`, and `meta.pagination.next` is an absolute URL for the next page.

Statistic values are self-describing objects: `value` (raw, native unit), `unit`
(`int`, `cm`, `ticks`, `tenths_of_heart`), `display` (human-readable string) and
`converted` (unit conversions where meaningful).

Player references accept a dashed UUID, a bare UUID, or a case-insensitive in-game name.
Every player object carries `edition`, either `java` or `bedrock` (Bedrock players connect
through Geyser and have synthetic UUIDs beginning `00000000-0000-0000-0009-`).

## Endpoints

- [GET /v1](https://api.hydrosmp.com/v1): Endpoint index for programmatic discovery.
- [GET /v1/health](https://api.hydrosmp.com/v1/health): Service health and data freshness. Never cached.
- [GET /v1/status](https://api.hydrosmp.com/v1/status): Live server-list ping — online/offline, current player count, version, MOTD, online player sample. The only real-time endpoint; everything else is a 15-minute snapshot.
- [GET /v1/server](https://api.hydrosmp.com/v1/server): Server addresses, player counts by edition, ranking rules and crown weights.
- [GET /v1/mods](https://api.hydrosmp.com/v1/mods): Every server-side Fabric mod, resolved against Modrinth. Performance and quality-of-life only.
- [GET /v1/modpack](https://api.hydrosmp.com/v1/modpack): The optional client modpack, its latest version and supported Minecraft versions. Never hardcoded.
- [GET /v1/stats](https://api.hydrosmp.com/v1/stats): Catalogue of all 217 tracked statistics with titles, units and record holders. Supports `search`.
- [GET /v1/stats/{stat_id}](https://api.hydrosmp.com/v1/stats/jump): Full leaderboard for one statistic, best first.
- [GET /v1/totals](https://api.hydrosmp.com/v1/totals): Every statistic summed server-wide, with per-player averages.
- [GET /v1/advancements](https://api.hydrosmp.com/v1/advancements): Advancement catalogue with rarity — how many players hold each one, rarest first. Datapack bookkeeping entries excluded unless `include=datapack`.
- [GET /v1/advancements/{advancement_id}](https://api.hydrosmp.com/v1/advancements/minecraft:nether/all_effects): One advancement with its rarity, icon, wiki link and the first player on the server to earn it (`first_by`, `first_completed_at`).
- [GET /v1/advancements/{advancement_id}/holders](https://api.hydrosmp.com/v1/advancements/minecraft:end/kill_dragon/holders): Everyone holding one advancement, ordered by when they earned it — position 1 is the first on the server. Supports `order=first|latest`.
- [GET /v1/feed](https://api.hydrosmp.com/v1/feed): Server-wide advancement unlocks, newest first. Vanilla advancements only; a rolling window, not the full archive. Supports `player`, `category`, `since`.
- [GET /v1/history](https://api.hydrosmp.com/v1/history): Player population and progression over time, with average/peak concurrent players and an hour-of-day activity profile. Supports `resolution=raw|hourly|daily`. Not backfilled — data starts at `meta.recording_since`.
- [GET /v1/players](https://api.hydrosmp.com/v1/players): List and search players. Supports `search`, `edition`, `ranked`, `sort`.
- [GET /v1/players/{player}](https://api.hydrosmp.com/v1/players/Phobia0): Player profile with medals, crown score, hall-of-fame rank and top ranks.
- [GET /v1/players/{player}/stats](https://api.hydrosmp.com/v1/players/Phobia0/stats): Every statistic for one player, with rank. Supports `ids` to filter.
- [GET /v1/players/{player}/advancements](https://api.hydrosmp.com/v1/players/Phobia0/advancements): Advancement progress. Recipe unlocks excluded unless `include=recipes`.
- [GET /v1/players/{player}/milestones](https://api.hydrosmp.com/v1/players/Phobia0/milestones): A player's timeline — first seen, progression beats with days-after-joining, rarest advancement held, and anything they earned first on the server.
- [GET /v1/players/{player}/activity](https://api.hydrosmp.com/v1/players/Clavalava/activity): One player's hours played, sessions and deaths over 7 days, 30 days and since recording began, plus their rank this week. Totals only.
- [GET /v1/activity](https://api.hydrosmp.com/v1/activity): Server-wide activity — average players online by local hour (`hour_of_day`), and active players, hours and deaths per day. Not backfilled.
- [GET /v1/activity/players](https://api.hydrosmp.com/v1/activity/players): Most active players. Supports `period=7d|30d|all` and `sort=minutes|sessions|deaths`.
- [GET /v1/hall-of-fame](https://api.hydrosmp.com/v1/hall-of-fame): Crown ranking by 1st/2nd/3rd place finishes across all statistics.
- [GET /v1/events](https://api.hydrosmp.com/v1/events): Weekly community events with their leaders. Supports `active`.
- [GET /v1/events/{event_id}](https://api.hydrosmp.com/v1/events): A single event by id.
- [GET /v1/compare](https://api.hydrosmp.com/v1/compare?players=Phobia0,Blxde7): Head-to-head comparison of two players across every statistic, with per-stat winners.
- [GET /v1/random/player](https://api.hydrosmp.com/v1/random/player): A random ranked player and their best rank. Never cached.
- [GET /v1/random/stat](https://api.hydrosmp.com/v1/random/stat): A random statistic with its top three players. Never cached.

## Embeddable images

These return `image/svg+xml` rather than JSON, for use in an `<img>` tag, a README or a
forum signature. Errors are rendered as an error badge (with the real HTTP status) rather
than as JSON, so a failed embed still renders as an image.

- [GET /v1/badge/server.svg](https://api.hydrosmp.com/v1/badge/server.svg): Live player count as a shields-style badge. Supports `label`, `color`.
- [GET /v1/badge/player/{player}.svg](https://api.hydrosmp.com/v1/badge/player/Phobia0.svg): One player stat as a badge. `stat` accepts any statistic id, or `advancements` (default), `medals`, `rank`.
- [GET /v1/card/player/{player}.svg](https://api.hydrosmp.com/v1/card/player/Phobia0.svg): A larger stat card with playtime, advancements, hall-of-fame rank and medals.

## How activity is measured, and what is deliberately not published

Minecraft's `play_time` counter only advances while a player is online, and those counters
are copied off the game server every 15 minutes. Diffing consecutive copies recovers who
was playing and for how long. Resolution is 15 minutes; no logs are parsed.

Only **totals** are published — hours, sessions and deaths per player, and server-wide
averages by hour. Per-session start and end times are never served by any endpoint: that
pattern would reveal when an individual member is reliably asleep or away from home. The
raw per-window log is stored outside every web root, on a path the API service is not
permitted to read.

## Player tenure

Player profiles and milestones carry `first_seen`, derived from the oldest timestamp in a
player's advancement file. When `first_seen_estimated` is true, that player was already on
the server when advancement tracking began, so the date is a floor rather than a join date
— read it as "playing since at least". Roughly 3% of the roster is in this state.

## Caching

Data is regenerated on a schedule, not per request. Responses carry `Cache-Control`,
a strong `ETag` and `Last-Modified`. Send `If-None-Match` to get a `304 Not Modified`.
Poll `/v1/health` cheaply and only re-fetch heavier endpoints when `data_updated_at` changes.

## Terms

Free for non-commercial community use with attribution to Hydro Vanilla SMP
(https://hydrosmp.com). Cache responses, set a descriptive `User-Agent`, do not resell
the data, and do not use it to target or harass players. No uptime guarantee — this is a
volunteer-run community server.

## Optional

- [Hydro Vanilla SMP website](https://hydrosmp.com): Server information, rules and how to join.
- [Live stats site](https://stats.hydrosmp.com): The human-facing view of this same data.
- [Discord](https://discord.gg/WbefzQ3nT9): Support, questions and rate-limit requests.