topg.org APItopg.org ↗
Access TopG.org server listings, rankings, votes, and player history via API. Covers Minecraft, Runescape, WoW, and more game categories.
curl -X GET 'https://api.parse.bot/scraper/26b099a6-82c5-4247-aad0-7dfdb486af68/get_minecraft_server_list?page=2' \ -H 'X-API-Key: $PARSE_API_KEY'
Retrieve the ranked list of Minecraft servers. Returns 20 servers per page. Supports pagination.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
{
"type": "object",
"fields": {
"page": "string indicating the current page number",
"servers": "array of server objects with id, rank, name, ip, players, status, tags, url"
},
"sample": {
"data": {
"page": "1",
"servers": [
{
"id": "675337",
"ip": "hub.enderblade.com",
"url": "https://topg.org/minecraft-servers/server-675337",
"name": "Enderblade",
"rank": "1",
"tags": [
"Latest",
"1.19.x",
"PVP",
"Survival"
],
"status": "Online",
"players": {
"max": "500",
"raw": "77/500",
"current": "77"
}
}
]
},
"status": "success"
}
}About the topg.org API
The TopG.org API exposes 15 endpoints covering ranked server listings, detailed server profiles, filtering by version, type, and country, plus vote submission and 24-hour player history. Endpoints like get_minecraft_server_details return fields including ip, version array, discord invite URL, player count, vote score, and online status. get_servers_by_game extends coverage to non-Minecraft categories such as Runescape and WoW private servers.
Server Listings and Filtering
get_minecraft_server_list returns 20 servers per page with fields for id, rank, name, ip, players, status, tags, and URL. Pages are navigated via the page integer parameter. Three filter endpoints — get_minecraft_servers_by_version, get_minecraft_servers_by_type, and get_minecraft_servers_by_country — each return the same server object shape but scoped to a specific version string (e.g. 1.21.4, 1.8.x), type tag (e.g. Survival, Factions), or country name (e.g. Germany). Filter endpoints return up to 20 results and do not support pagination. Use get_minecraft_server_versions, get_minecraft_server_types, and get_minecraft_server_countries to retrieve the exact strings the site accepts before calling filter endpoints.
Server Details and History
get_minecraft_server_details returns the full profile for a single server identified by its numeric server_id: ip, name, rank, an array of type tags, vote score, online status, discord invite URL (or null), player count in current/max format, and a version array. get_server_player_history returns the last 24 hours of player counts as an array of [timestamp_ms_string, player_count_integer] pairs — useful for charting activity patterns over time. get_server_vote_score returns rank, score, and a last_update date string for a given server without fetching the full detail payload.
Cross-Game and Search
get_game_categories returns all game categories on the site as objects with name and slug fields. Pass a slug to get_servers_by_game to retrieve the ranked list for categories like runescape-private-servers or wow-private-servers. search_servers accepts a keyword query and returns matching results across all game categories, with each result including a category field so you can tell which game a result belongs to. get_new_minecraft_servers surfaces the most recently added servers without requiring any parameters.
Voting
submit_server_vote accepts a username and server_id and returns a status of voted, already_voted, or submitted, plus a human-readable message. The already_voted status is returned when the calling IP has already cast a vote for that server today, reflecting the site's one-vote-per-day-per-IP rule.
- Build a Minecraft server browser filtered by version (e.g. 1.8.x) using get_minecraft_servers_by_version
- Track daily player count trends for a specific server using get_server_player_history timestamp data
- Monitor vote score changes over time by polling get_server_vote_score for a set of server IDs
- Aggregate top-ranked servers across Minecraft, Runescape, and WoW using get_game_categories and get_servers_by_game
- Surface newly listed servers for a 'just added' feed using get_new_minecraft_servers
- Implement server search across all game categories with keyword queries via search_servers
- Automate player voting workflows by submitting votes with submit_server_vote and handling already_voted responses
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.