SeedFinder - Documentation

Overview

All endpoints below are reachable at https://mineseedfinder.vercel.app and return JSON. The search walks the generation regions around the player, checks biomes through cubiomes and sorts the results by distance.

Base URL

https://mineseedfinder.vercel.app

Endpoint `GET /status`

Health check. Reports whether the native library loaded and its version.

200 response:

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

500 response:

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

Endpoint `GET /scan`

Scans for structures near the given position.

Query parameters

Parameter	Type	Default	Description
`seed`	int (uint64)	`0`	The world seed.
`x`	float	`0`	Player X coordinate, in blocks.
`z`	float	`0`	Player Z coordinate, in blocks.
`radius`	int	`100`	Search radius in chunks. Values below `1` are rejected with 400; values above `1000` are clamped to the maximum.
`max`	int	`20`	Maximum results. Values below `1` are rejected with 400; values above `200` are clamped to the maximum.
`types`	string	`5`	Comma-separated structure IDs.

Any missing or invalid parameter is replaced by its default. The response includes a missing_or_invalid array listing the parameters the server swapped out.

Example 200 response:

{
  "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 }
  ]
}

400 error (invalid parameter):

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

503 error (native library 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 IDs

The types parameter accepts comma-separated IDs from the table below. For example, Outpost is 10 and Village is 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	`10`	Pillager Outpost
`7`	Shipwreck	`23`	Trail Ruins
`8`	Ocean Monument	`24`	Trial Chambers
`9`	Woodland Mansion

Live example

Click to open the request below - it looks for villages, monuments and mansions within 100 chunks of spawn on seed 31415:

Open request ▸

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

Example 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 call /scan with requests (Python), network.get (Lua, e.g. inside Flarial Client) or the native 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 takes the structure IDs in types, 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 it with your JSON lib if needed
end

-- Example: villages, monuments and 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 the native fetch available in Node 18+.
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 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);
});

API Documentation