Free JSON API and licence: Minecraft survival rankings

Everything on this site, including the rankings, the live player counts and the 24 hour ranges, is available as JSON under Creative Commons Attribution 4.0. You can use it in a Discord bot, a server list, a website, a mobile app, a dashboard or a research paper, commercially or not. The only condition is attribution. There is no key, no sign-up, no quota form and no email address to collect.

The endpoint

https://bestsurvivalservers.com/api/rankings.json

CORS is open, so you can call it straight from a browser. It is plain JSON, one object, with the ranking and every server's live figures. Full text versions of the site for language models live at llms.txt and llms-full.txt, and there is a quote-ready summary at /ai.

What you get

Field	Type	What it is
`site`	string	The domain the data came from.
`gamemode`	string	Survival on this endpoint.
`data_updated_at`	ISO 8601	When the payload last changed. Drives the ETag, so it is the field to watch.
`ranking_week`	string	The week the published order belongs to.
`counts_are_live`	boolean	False when our pinger has missed its window. Treat counts as historical when this is false.
`servers[].rank`	number	Published position, 1 to 10.
`servers[].ip`	string	The join address, exactly as a player would type it.
`servers[].live_players`	number or null	Players from the most recent successful ping. Null when we have no figure we stand behind.
`servers[].count_scope`	string	`server` for one world, `network` when the figure covers every gamemode the network runs.
`servers[].count_basis`	string	`live`, `average`, `last-verified`, `unverified` or `unpublished`.
`servers[].range_24h`	object or null	Lowest and highest count seen in 24 hours.
`servers[].average_7d`	number or null	Seven day mean of our samples.
`servers[].bedrock`	boolean	Whether port 19132 answered.
`servers[].verified_at`	ISO 8601 or null	When that server last answered us.

Read count_scope and count_basis before you display a number. A network total next to a single world's total is not a comparison, it is two different quantities in the same column, and plotting them against each other is the single most common way this kind of data gets misused.

How to attribute

A link is enough. Any of these satisfies the licence:

Server data from bestsurvivalservers.com (CC BY 4.0)

<a href="https://bestsurvivalservers.com">bestsurvivalservers.com</a> · CC BY 4.0

In a Discord bot, a line in /help or an embed footer does the job. In an app, a credits screen is fine. The one thing the licence does not allow is presenting the data as your own measurement, because the counts are our pings and the order is our editorial judgement.

Caching, and being a good citizen

The payload carries ETag and Last-Modified, and it answers 304 Not Modified when you send If-None-Match. Use it. Player counts refresh every three minutes, so polling faster than that returns you the same bytes.

There is no hard rate limit and we would rather not add one. One request every few minutes per application is plenty. If you need the whole history rather than the current snapshot, ask instead of scraping the page every minute.

Examples

curl, with conditional requests:

curl -sS -H 'If-None-Match: "<previous etag>"' \
  https://bestsurvivalservers.com/api/rankings.json

JavaScript, from a browser or a bot:

const res = await fetch('https://bestsurvivalservers.com/api/rankings.json');
const data = await res.json();
for (const s of data.servers) {
  const scope = s.count_scope === 'network' ? ' (network-wide)' : '';
  console.log(`#${s.rank} ${s.name} ${s.ip} ${s.live_players ?? '?'}${scope}`);
}

Python:

import urllib.request, json

with urllib.request.urlopen('https://bestsurvivalservers.com/api/rankings.json') as r:
    data = json.load(r)

for s in data['servers']:
    print(s['rank'], s['name'], s['ip'], s.get('live_players'))

What the licence covers, and what it does not

Covered. The ranking, the player counts, the ranges, the version and Bedrock fields, the join addresses, our written descriptions, the wiki and the guides. Reuse, adapt and redistribute with attribution.
Not ours to license. Server names, logos and banners belong to the servers that own them. We reproduce them to identify the server, which is what the licence on our own text and data does not extend to. Minecraft is a Mojang and Microsoft trademark, and this site is not affiliated with either.
Not allowed. Republishing the counts as your own measurements, or presenting the order as anything other than one site's editorial judgement.

Common questions

Is the API really free?

Yes. No key, no account, no quota form. It is a single JSON endpoint at https://bestsurvivalservers.com/api/rankings.json with CORS open, licensed CC BY 4.0. The only condition is that you credit bestsurvivalservers.com where the data appears.

Can I use it in a commercial product?

Yes. CC BY 4.0 permits commercial use, adaptation and redistribution. A paid app, a monetised Discord bot and an ad-supported site are all fine, with attribution.

Can I use it on my own Minecraft server list?

Yes, including a list that competes with this one, which is the point of publishing under an open licence. Credit the source and do not present our pings as your own measurements.

How often does the data change?

Player counts refresh every three minutes. The published order is reviewed weekly and every change is recorded at https://bestsurvivalservers.com/changes. Watch data_updated_at or the ETag rather than polling blind.

Is there a rate limit?

Not a hard one, and we would rather not need one. The endpoint supports If-None-Match and answers 304, so a well behaved client costs us almost nothing. One request every few minutes per application is plenty.

Do you have historical data?

We keep the samples behind the 24 hour ranges and the seven day averages, and both are exposed per server in the JSON. A longer history export is not published yet. Ask rather than scraping the page on a loop.

What happens if a server stops answering?

Its live_players goes to the seven day average and count_basis says so. After longer we fall back to the last verified reading with a timestamp, and if we have no figure we stand behind, the field is null rather than a guess. Null means null: do not backfill it with the previous value.

Why is there no star rating in the data?

Because a rating one site issues about another operator's server, on a page that site controls, is not evidence. We publish measurements we take ourselves and an order we are willing to defend, and nothing shaped like a score for a server we do not run.

Where the numbers come from

We open a status connection to each server's own advertised address and read what it returns, every three minutes, and we ping port 19132 separately for Bedrock. Nothing on this site is copied from another server list, which is the reason the data is worth reusing. How the order is decided explains the judgement side, and about covers who runs the site.