API Documentation

Overview #

The MineSeedFinder API answers two questions about a Minecraft world from its seed: which structures generate near a position, and which biome sits at a point. It covers Bedrock and Java Edition, there is no key and no account, and every route is a plain HTTP request that returns JSON or plain text.

The same engine runs in the browser on the SeedFinder console and the SeedCracker console, so you can check a result by hand before wiring it into a script.

Base URL #

All routes sit at the root of the site: no path prefix, no version segment, no trailing slash.

https://www.mineseedfinder.com

Rate limits #

Endpoint GET /GetStructures #

Lists the structures near a position, sorted by distance. It also answers POST. /scan is the same endpoint under its original codename, with the same parameters and the same JSON, so a script written against either name keeps working.

Parameters #

Structure IDs #

types takes these IDs, comma-separated. For example 5,8,9 asks for villages, monuments and mansions.

Desert Well (16) and Amethyst Geode (17) are not supported.

Response #

200

{
  "results": [
    { "distance": 34.5, "name": "mansion", "x": 520, "z": 216 },
    { "distance": 56.5, "name": "village", "x": -360, "z": -840 },
    { "distance": 73.7, "name": "village", "x": 168, "z": 1176 }
  ]
}

400, a parameter the API cannot use

{
  "error": "Invalid parameter: invalid value for 'mc': 'x' (must start with 'j' or 'b')",
  "missing_or_invalid": ["mc"]
}

503, native library missing on that server

{
  "error": "SeedFinder native library (.so) not loaded on this server.",
  "hint": "Check Vercel build logs for messages starting with [seedfinder].",
  "missing_or_invalid": [],
  "results": []
}

Live example #

Villages, monuments and mansions within 100 chunks of spawn on seed 31415.

https://www.mineseedfinder.com/GetStructures?seed=31415&x=0&z=0&radius=100&max=50&types=5,8,9

Examples #

import requests

BASE = "https://www.mineseedfinder.com"

def structures(seed, x=0, z=0, radius=100, max_=20, types="5", mc="bedrock"):
    r = requests.get(
        f"{BASE}/GetStructures",
        params={"seed": seed, "x": x, "z": z, "radius": radius,
                "max": max_, "types": types, "mc": mc},
        timeout=15,
    )
    r.raise_for_status()
    return r.json()

for s in structures(seed=31415, types="5,8,9").get("results", []):
    print(f"{s['name']:<14} (x={s['x']}, z={s['z']}) dist={s['distance']}")

-- Flarial Client module: `network` is a Flarial global.
local BASE = "https://www.mineseedfinder.com"

local function structures(seed, x, z, radius, maxResults, types)
    local url = string.format(
        "%s/GetStructures?seed=%d&x=%d&z=%d&radius=%d&max=%d&types=%s",
        BASE, seed, x, z, radius, maxResults, types
    )
    local resp = network.get(url)
    if not resp or resp.code ~= 200 then
        print("[seedfinder] HTTP error: " .. tostring(resp and resp.code))
        return nil
    end
    return resp.body -- JSON string; parse it with your JSON library
end

print(structures(31415, 0, 0, 100, 50, "5,8,9"))

curl "https://www.mineseedfinder.com/GetStructures?seed=31415&x=0&z=0&radius=100&max=50&types=5,8,9"

# the same request with a JSON body
curl -X POST https://www.mineseedfinder.com/GetStructures \
  -H "Content-Type: application/json" \
  -d '{"seed": 31415, "x": 0, "z": 0, "radius": 100, "max": 50, "types": "5,8,9"}'

Endpoint GET /GetBiomeAt #

Answers with the biome at one block position, as plain text. Biomes are identical in Java and Bedrock, so there is no edition parameter.

Parameters #

200

minecraft:river

Examples #

import requests

r = requests.get(
    "https://www.mineseedfinder.com/GetBiomeAt",
    params={"seed": 31415, "x": 0, "z": 0},
    timeout=15,
)
r.raise_for_status()
print(r.text)  # minecraft:river

local resp = network.get(
    "https://www.mineseedfinder.com/GetBiomeAt?seed=31415&x=0&z=0"
)
print(resp and resp.body) -- minecraft:river

curl "https://www.mineseedfinder.com/GetBiomeAt?seed=31415&x=0&z=0"

Endpoint GET /GetBiomes #

Answers with a square grid of biomes centred on X/Z, as text, JSON or a PNG map.

Parameters #

Output formats #

• text: one line per Z row, north first, one character per sample.
• json: the same rows as an array of strings.
• image: a PNG with one pixel per sample, in the same colours as the biome map on the console.

Character legend #

Both biome routes allow 6 requests per minute per IP address, shared between them, and answer 429 with a Retry-After header beyond that.

Examples #

import requests

r = requests.get(
    "https://www.mineseedfinder.com/GetBiomes",
    params={"seed": 31415, "x": 0, "z": 0, "size": 8, "scale": 16,
            "outputformat": "json"},
    timeout=15,
)
r.raise_for_status()
for row in r.json():   # one string per Z row, north first
    print(row)

local url = "https://www.mineseedfinder.com/GetBiomes"
    .. "?seed=31415&x=0&z=0&size=8&scale=16&outputformat=text"

local resp = network.get(url)
print(resp and resp.body) -- one line per row, one char per biome

# PNG map, one pixel per sample
curl -o biomes.png "https://www.mineseedfinder.com/GetBiomes?seed=31415&x=0&z=0&size=32&scale=16"

# text grid you can read in the terminal
curl "https://www.mineseedfinder.com/GetBiomes?seed=31415&x=0&z=0&size=8&scale=16&outputformat=text"

Discord bot (closed test) #

The same structure lookup that runs on this page also exists as a Discord slash command, so a server can answer "what is around this seed" without leaving the chat. It is in a closed test: it runs privately, there is no invite link on this page, and it is not supported as a public service yet.

/scan takes seven required fields: the API's seed, x, z, radius, max and types, plus an explicit edition (Java or Bedrock). It answers with an embed: the structures near the position, sorted by distance and paginated when there are many. A button on the reply opens the SeedFinder console with the same search already filled in.

Commands #

/scan seed:31415 edition:Bedrock x:0 z:0 radius:100 types:village,monument max:20

Attribution #

Using this API, or showing its results, in your own project, bot or website? No sign-up and no permission needed. Credit the service with a powered by SeedFinder line linking to the home page, wherever you show the results.

<a href="https://www.mineseedfinder.com/">powered by SeedFinder</a>