Data conventions
The rules every endpoint follows, so you can write one parser for all of them.
The API speaks JSON over HTTPS. Responses are UTF-8, field names are camelCase and every endpoint is a GET (or HEAD). Anything else gets 405. URLs are capped at 2,048 characters.
New fields may be added to any object at any time. Ignore fields you do not know. Removing or renaming a field only happens in a new API version.
Every time is a Unix timestamp in milliseconds, UTC, as a plain number. Fields that hold one end in At, such as firstSeenAt and updatedAt. History points use t. Daily series also give a day string in YYYY-MM-DD form, and days always run from midnight to midnight UTC.
const listedAt = new Date(listing.firstSeenAt);
console.log(listedAt.toISOString());
const hoursAgo = (Date.now() - listing.firstSeenAt) / 3_600_000;Big numbers are safe
The largest balances are in the trillions, well inside the range JavaScript numbers hold exactly. No string encoding is needed.
null means we do not know or it does not apply, for example bid: null when nobody has an open buy order. A field that is documented is always present, with two exceptions: inside stats a stat is left out until it has been read once, and every field of ProductDetails only appears when it applies.
Usernames are 1 to 16 letters, digits or underscores. Bedrock players have a leading dot, such as .Bamsden816, and that dot is part of the name. Lookups are case insensitive and responses always use the player's current capitalization.
The market is organised by product: an item plus everything that changes its value. A product key is the item id, followed by the variant in square brackets when there is one.
Keys contain brackets, commas and colons, so URL encode them in paths and query strings:
const key = "netherite_sword[sharpness:5,unbreaking:3]";
const response = await fetch(
`https://api.donutstats.io/v1/items/${encodeURIComponent(key)}`,
{ headers: { "x-api-key": process.env.DONUTSTATS_API_KEY } },
);The variant is built from these parts. When an item has more than one, they are joined with a semicolon.
- Enchantments, sorted by id and joined with commas. Level 1 is written without a level:
sharpness:5,unbreaking:3,mending. Enchanted books use the enchantments stored in them. - Type names for potions, splash and lingering potions, tipped arrows, spawners, trial spawners, goat horns and suspicious stew:
poison,skeletonand so on. - Flight duration for firework rockets other than 1:
flight:2,flight:3. filledfor shulker boxes with contents. Each box is different, so these never get a market price. The contents are indetails.contents.uniquefor filled maps, written and writable books and player heads. These never get a market price either.
Boards marked in game are DonutSMP's own leaderboards. Kills and shards have no board on DonutSMP, so DonutStats ranks every player whose stats it has on record.