SeedFinder API

SeedFinder is a REST API that finds nearby Minecraft Bedrock structures for a given world seed and player position. All endpoints return JSON and are reachable at
https://mineseedfinder.vercel.app.

Base URL

https://mineseedfinder.vercel.app

Endpoints

`GET /status`

Health check. Returns whether the native library was loaded and its version.

Response 200:

{
  "ok": true,
  "version": "..."
}

Response 500:

{
  "status": "error",
  "message": "..."
}

`GET /scan`

Scan for structures near the given position.

Query param	Type	Default	Description
`seed`	int (uint64)	`0`	World seed.
`x`	float	`0`	Player X block position.
`z`	float	`0`	Player Z block position.
`radius`	int	`100`	Search radius in chunks. Clamped to `1000`.
`max`	int	`20`	Maximum results to return. Clamped to `1000`.
`types`	string	`5`	Comma-separated structure type IDs.

Any parameter that is missing or unparseable is replaced with its default. The response also includes a missing_or_invalid array listing any params the server had to substitute.

Example response 200:

{
  "missing_or_invalid": ["seed"],
  "results": [
    { "name": "mansion", "x": 520,    "z": 216,    "distance": 34.5 },
    { "name": "village", "x": 712,    "z": -520,   "distance": 54.4 },
    { "name": "village", "x": -360,   "z": -840,   "distance": 56.5 },
    { "name": "village", "x": 168,    "z": 1176,   "distance": 73.7 },
    { "name": "village", "x": 136,    "z": -1352,  "distance": 84.4 },
    { "name": "village", "x": -1448,  "z": -264,   "distance": 91.4 },
    { "name": "village", "x": -296,   "z": -1464,  "distance": 92.8 }
  ]
}

Response 400 (invalid param):

{
  "error": "Invalid parameter: ...",
  "missing_or_invalid": ["seed"]
}

Response 503 (native lib not loaded):

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

Structure type IDs

The types parameter accepts comma-separated IDs from the table below. Outpost → 10, Village → 5.

ID	Name	ID	Name
1	Desert Pyramid	11	Ruined Portal
2	Jungle Temple	12	Ruined Portal (Nether)
3	Swamp Hut	13	Ancient City
4	Igloo	14	Buried Treasure
5	Village	15	Mineshaft
6	Ocean Ruin	16	Desert Well
7	Shipwreck	17	Amethyst Geode
8	Ocean Monument	23	Trail Ruins
9	Woodland Mansion	24	Trial Chambers
10	Pillager Outpost

Live example

Click to open the call below — searches Villages, Monuments and Mansions within 100 chunks of spawn on seed 31415:

https://mineseedfinder.vercel.app/scan?seed=31415&x=0&z=0&radius=100&max=50&types=5,8,9

Sample response:

{"results":[{"distance":34.5,"name":"mansion","x":520,"z":216},{"distance":54.4,"name":"village","x":712,"z":-520},{"distance":56.5,"name":"village","x":-360,"z":-840},{"distance":73.7,"name":"village","x":168,"z":1176},{"distance":84.4,"name":"village","x":136,"z":-1352},{"distance":91.4,"name":"village","x":-1448,"z":-264},{"distance":92.8,"name":"village","x":-296,"z":-1464}]}

Client examples

Pick a language below to see how to fetch from /scan with requests (Python), network.get (Lua, e.g. inside Flarial Client) or the built-in https module (Node.js).

import requests

BASE = "https://mineseedfinder.vercel.app"

def scan(seed, x=0, z=0, radius=100, max_=20, types="5"):
    params = {
        "seed": seed,
        "x": x,
        "z": z,
        "radius": radius,
        "max": max_,
        "types": types,  # comma-separated structure IDs, e.g. "5,8,9"
    }
    r = requests.get(f"{BASE}/scan", params=params, timeout=15)
    r.raise_for_status()
    return r.json()

if __name__ == "__main__":
    data = scan(seed=31415, x=0, z=0, radius=100, max_=50, types="5,8,9")
    for s in data.get("results", []):
        print(f"{s['name']:<14} (x={s['x']}, z={s['z']}) dist={s['distance']}")

-- Drop-in for Flarial Client modules. `network` is a Flarial global.
local BASE = "https://mineseedfinder.vercel.app"

local function scan(seed, x, z, radius, maxResults, types)
    local url = string.format(
        "%s/scan?seed=%d&x=%d&z=%d&radius=%d&max=%d&types=%s",
        BASE, seed, x, z, radius, maxResults, types
    )
    -- seedfinder uses types= for structure IDs, e.g. "5,8,9"
    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 with your Lua JSON lib if needed
end

-- Example: villages, monuments, mansions around spawn on seed 31415
local body = scan(31415, 0, 0, 100, 50, "5,8,9")
print(body or "no response")

// No dependencies — uses Node 18+ built-in fetch.
const BASE = "https://mineseedfinder.vercel.app";

async function scan(seed, x = 0, z = 0, radius = 100, max = 20, types = "5") {
    const url = new URL("/scan", BASE);
    url.searchParams.set("seed", String(seed));
    url.searchParams.set("x", String(x));
    url.searchParams.set("z", String(z));
    url.searchParams.set("radius", String(radius));
    url.searchParams.set("max", String(max));
    url.searchParams.set("types", types);  // comma-separated structure IDs, e.g. "5,8,9"

    const res = await fetch(url, { signal: AbortSignal.timeout(15000) });
    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
    return res.json();
}

(async () => {
    const data = await scan(31415, 0, 0, 100, 50, "5,8,9");
    for (const s of data.results ?? []) {
        console.log(`${s.name.padEnd(14)} (x=${s.x}, z=${s.z}) dist=${s.distance}`);
    }
})().catch((err) => {
    console.error("scan failed:", err);
    process.exit(1);
});