API documentation

Build integrations with ordinary HTTPS requests. There is no MineGeo SDK; the Python examples use the requests library.

Base URL: https://minegeo.vercel.app/api/dev/v1

Download the OpenAPI specification

1. Create a key

Open the developer panel →

Open the developer panel, log in, name your integration and select its permissions. Public maps are selected by default. Access to your profile, private maps and game history is separate and optional. You can have up to 5 active keys, with an expiry of 1–365 days (90 by default).

Store the copied key in the MINEGEO_API_KEY environment variable on your computer or server. Keep it out of source code, repositories, browser JavaScript and URLs. If it leaks, revoke it and create a replacement.

2. Make a request with Python

python -m pip install requests

import os
import requests

response = requests.get(
    "https://minegeo.vercel.app/api/dev/v1/maps",
    headers={"Authorization": f"Bearer {os.environ['MINEGEO_API_KEY']}"},
    params={"limit": 20, "offset": 0},
    timeout=20,
)
response.raise_for_status()
print(response.json())

Every v1 request needs Authorization: Bearer <your-key>. MineGeo developer keys start with mg_dev_. Contributor upload tokens, metrics tokens and your browser login cookie do not authenticate this API.

Endpoints and permissions

Account endpoints always refer to the owner of the API key. They cannot read another player's private data. /me returns your account ID, display name, creation date and username appearance; it does not expose your email or account role.

Map details include metadata, map bounds and panorama count. Raw storage paths, panorama coordinates, moderation notes and game answers are excluded. Game history exposes a score only after a game is complete.

Pagination and search

Lists accept limit (default 20, maximum 50) and offset (default 0, maximum 10000). /maps and /me/maps also accept q (up to 80 characters) to search map names. Unknown or repeated query parameters return HTTP 400. Use pagination.nextOffset for the next request; null means the end of the supported result window. Narrow q when you reach the offset limit.

{
  "maps": [],
  "pagination": {"limit": 20, "offset": 0, "total": 0, "nextOffset": null}
}

GET /maps/{id} returns {map: {...}}. GET /me returns {account: {...}}. GET /me/maps uses the maps list envelope; GET /me/games uses {games: [...], pagination: {...}}. Map url values are relative to https://minegeo.vercel.app.

Rate limits

Each key can make 60 requests per minute. All keys belonging to one account share a limit of 180 requests per minute. Creating more keys does not bypass the account limit. These limits apply to authenticated requests, including requests that fail permission or input checks.

• RateLimit-Limit: per-key request limit
• RateLimit-Remaining: requests remaining for this key
• RateLimit-Reset: seconds until the current minute window resets
• X-RateLimit-Owner-Limit / X-RateLimit-Owner-Remaining: shared account quota

If you receive HTTP 429, wait for the number of seconds in Retry-After before retrying. Avoid tight retry loops. Cache catalog responses in your integration when appropriate.

Errors

{"error":{"code":"insufficient_scope","message":"This API key does not have the required permission."}}

• 400 — invalid input or pagination
• 401 — missing, invalid, revoked or expired key
• 403 — key is missing a required permission
• 404 — map or endpoint unavailable
• 429 — request quota exhausted
• 500 / 503 — temporary service failure; retry with a delay