MinecraftStatus
Documentation

Check Minecraft status with Python

Copy this example, set an optional MINECRAFTSTATUS_API_KEY in the environment, and pass an edition plus address. The example preserves pending, quota and freshness boundaries.

Source

Python · anonymous by default
import json
import os
import sys
import urllib.parse
import urllib.request
import urllib.error

base = os.environ.get("MINECRAFTSTATUS_API_BASE", "https://minecraftstatus.com")
edition = sys.argv[1] if len(sys.argv) > 1 else "java"
address = sys.argv[2] if len(sys.argv) > 2 else "play.example.net"
headers = {"Accept": "application/json"}
if os.environ.get("MINECRAFTSTATUS_API_KEY"):
    headers["Authorization"] = "Bearer " + os.environ["MINECRAFTSTATUS_API_KEY"]
request = urllib.request.Request(
    f"{base}/api/v1/status/{edition}?address={urllib.parse.quote(address, safe='')}",
    headers=headers,
)
try:
    with urllib.request.urlopen(request, timeout=15) as response:
        status = response.status
        body = json.load(response)
except urllib.error.HTTPError as error:
    body = json.loads(error.read().decode("utf-8"))
    if error.code == 429:
        raise SystemExit(f"Rate limited; retry after {error.headers.get('Retry-After')} seconds")
    if error.code == 202:
        print("Observation pending:", body.get("pollUrl"))
        raise SystemExit(0)
    raise SystemExit(f"MinecraftStatus API HTTP {error.code}: {body.get('error', {}).get('message', 'request failed')}")
if status == 202:
    print("Observation pending:", body.get("pollUrl"))
else:
    print(json.dumps(body, indent=2))
    if body.get("freshness") != "fresh":
        print("Current claim is not fresh; observe again before presenting it as current", file=sys.stderr)

Run with an address argument such as java play.example.net. The source files are versioned alongside this documentation under examples/api/python/status.python.

Choose another language

Contract boundary

Every example branches on HTTP status first, prints a queued job receipt for 202, respects Retry-After for 429, and refuses to present stale or missing freshness as current.