Planet Minecraft APIplanetminecraft.com ↗
Search and retrieve Minecraft server listings from Planet Minecraft. Get player counts, server IPs, tags, stats, and full descriptions via 2 REST endpoints.
What is the Planet Minecraft API?
The Planet Minecraft API exposes 2 endpoints for discovering and inspecting Minecraft server listings from planetminecraft.com. The get_servers endpoint returns paginated lists of Java and Bedrock servers with player counts and engagement stats, while get_server_details delivers full server metadata including IP address, game version, tags, description text, and monthly vote counts for any server identified by its slug.
curl -X GET 'https://api.parse.bot/scraper/3edb2b52-0725-4786-ac00-7c8285db44a6/get_servers?page=1&order=order_hot&category=servers&keywords=survival' \ -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 planetminecraft-com-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.
"""Planet Minecraft server discovery: list, filter, and inspect server details."""
from parse_apis.planet_minecraft_api import PlanetMinecraft, Order, Category, ServerNotFound
client = PlanetMinecraft()
# List trending Java servers, capped at 5 results
for summary in client.serversummaries.list(order=Order.HOT, category=Category.JAVA, limit=5):
print(summary.name, summary.players, summary.is_online)
# Drill into the first server's full details
summary = client.serversummaries.list(keywords="survival", limit=1).first()
if summary:
server = summary.details()
print(server.name, server.ip, server.online_players)
print("Tags:", server.tags)
print("Views:", server.stats.views)
# Direct lookup by slug
detail = client.servers.get(slug="pupland-friendly-smp-no-pvp-pup-play-in-testing")
print(detail.name, detail.description[:80] if detail.description else "")
# Handle a missing server gracefully
try:
client.servers.get(slug="nonexistent-server-slug-xyz")
except ServerNotFound as exc:
print(f"Server not found: {exc.slug}")
print("exercised: serversummaries.list / summary.details / servers.get / ServerNotFound")
List Minecraft servers from Planet Minecraft. Supports Java and Bedrock categories, multiple sort orders, keyword search, and pagination. Each result includes server name, online status, player count, and basic engagement stats (votes, views, diamonds, favorites). Pagination is page-number based.
| Param | Type | Description |
|---|---|---|
| page | integer | The page number to retrieve. |
| order | string | Sort order for the server listing. |
| category | string | The category of servers to list. |
| keywords | string | Search keywords to filter servers by name or description. |
{
"type": "object",
"fields": {
"servers": "array of server objects each containing name, slug, url, players, is_online, and stats",
"pagination": "object containing current_page, category, order, and total_results"
},
"sample": {
"data": {
"servers": [
{
"url": "https://www.planetminecraft.com/server/pupland-friendly-smp-no-pvp-pup-play-in-testing/",
"name": "PupLand | Friendly SMP",
"slug": "pupland-friendly-smp-no-pvp-pup-play-in-testing",
"stats": {
"views": "163",
"votes": "5",
"diamonds": "3",
"favorites": "3"
},
"players": "2/1000",
"is_online": true
}
],
"pagination": {
"order": "order_hot",
"category": "servers",
"current_page": 1,
"total_results": 25
}
},
"status": "success"
}
}About the Planet Minecraft API
Server Listing and Search
The get_servers endpoint returns an array of server objects, each containing name, slug, url, players, is_online, and a stats block covering votes, views, diamonds, and favorites. Requests accept a category parameter to filter between Java and Bedrock servers, an order parameter to sort by trending, top-voted, new, or other available orderings, and a keywords parameter for name or description search. Pagination is controlled via the page parameter; the pagination response object reports current_page, category, order, and total_results.
Detailed Server Records
The get_server_details endpoint accepts a slug (returned in every get_servers result) and returns a detailed record for that server. The response includes ip (the server's connection address when published by the listing author, or null), table_data — a key-value object drawn from the server's info table covering fields like Status, Location, Game Version, MOTD, and Players — along with tags, the full description text, and a stats object with views, votes_this_month, and server_score. The online_players field gives the current and maximum player count as a formatted string such as 2/1000.
Coverage and Freshness
Data reflects public server listings on Planet Minecraft, which hosts thousands of community-submitted Java and Bedrock servers. Engagement metrics like votes_this_month and server_score reflect the state of the listing at retrieval time. Server IP availability depends on whether the listing owner has published it in the description; the API returns null for ip when none is present.
The Planet Minecraft API is a managed, monitored endpoint for planetminecraft.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when planetminecraft.com 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 planetminecraft.com 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 that filters by category (Java vs. Bedrock) and sorts by votes or player count
- Monitor server uptime and online player counts over time using
is_onlineandonline_playersfrom recurring calls - Aggregate server tags and game version data from
table_datato analyze trends in the Minecraft server ecosystem - Index server descriptions and names from
get_serverskeywords search to power a custom discovery tool - Track monthly vote momentum with
votes_this_monthto identify newly trending servers - Extract server IPs in bulk for connectivity testing or latency benchmarking tools
- Compile server metadata including location and MOTD from
table_datafor community ranking dashboards
| 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.
Does Planet Minecraft offer an official developer API?+
What does `get_server_details` return in the `table_data` field, and is it always consistent?+
table_data object contains key-value pairs from the server's info table as submitted by the listing owner. Common keys include Status, Location, Game Version, MOTD, and Players, but the exact keys present vary per listing since authors control what they fill in. Always check for key existence before accessing a specific field.Is the server IP always available in `get_server_details`?+
ip field is extracted from the listing description when the server owner has published it there. When no IP is present, the field returns null. The API covers all publicly listed metadata; the IP field simply reflects what the listing author has chosen to include.Does the API expose server reviews, comments, or user-submitted screenshots?+
Can I retrieve servers by a specific game mode, like Survival or Creative?+
get_servers endpoint supports keywords search and a category parameter for Java vs. Bedrock, but does not expose a dedicated game-mode filter. Game mode information may appear in server descriptions or tags returned by get_server_details. You can fork this API on Parse and revise it to add a tag- or game-mode-based filter endpoint.