TopG APItopg.org ↗
Access TopG.org server listings, rankings, votes, and player history via API. Covers Minecraft, Runescape, WoW, and more game categories.
What is the TopG 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.
curl -X GET 'https://api.parse.bot/scraper/26b099a6-82c5-4247-aad0-7dfdb486af68/get_minecraft_server_list?page=1' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace topg-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: TopG gaming server directory — browse, filter, and inspect servers."""
from parse_apis.topg.org_gaming_server_directory_api import TopG, ServerNotFound
topg = TopG()
# Browse top-ranked Minecraft servers with pagination
for server in topg.serversummaries.list(limit=5):
print(server.name, server.rank, server.players.raw)
# Filter servers by type
for server in topg.serversummaries.by_type(type="Survival", limit=3):
print(server.name, server.ip, server.tags)
# Get full details for a specific server
detail = topg.servers.get(id="675337")
print(detail.name, detail.score, detail.version)
# Access vote score sub-resource
vote_info = detail.votes.get()
print(vote_info.rank, vote_info.score)
# Access player history sub-resource
history = detail.history.get()
for entry in history.player_history[:3]:
print(entry)
# Search across all game categories
result = topg.serversummaries.search(query="skyblock", limit=3).first()
if result:
print(result.name, result.category, result.url)
# Explore non-Minecraft game categories
category = topg.gamecategories.list(limit=3).first()
if category:
for srv in category.servers(limit=2):
print(srv.name, srv.rank)
# Typed error handling
try:
topg.servers.get(id="99999999")
except ServerNotFound as exc:
print(f"Server not found: {exc.server_id}")
print("exercised: list / by_type / get / votes.get / history.get / search / gamecategories.list / servers")
Retrieve the ranked list of Minecraft servers, 20 per page. Servers are ordered by their TopG rank (vote-based). Pagination via integer page number.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
{
"type": "object",
"fields": {
"page": "string current page number",
"servers": "array of server summary 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",
"SMP",
"Lifesteal"
],
"status": "Online",
"players": {
"max": "500",
"raw": "58/500",
"current": "58"
}
}
]
},
"status": "success"
}
}About the TopG API
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.
The TopG API is a managed, monitored endpoint for topg.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when topg.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official topg.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- 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 | 100 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.