API Documentation

Three free endpoints for Bedrock and Java worlds: a seed and a position turn into the structures nearby, or into the biome at a point. No key, no account, no sign-up.

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.

Not affiliated with Mojang or Microsoft. Every result is a prediction of structure placement computed from the seed, not a guarantee that one specific chest sits on one specific block.

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 #

RouteLimitWhat happens past it
/GetStructures 60 requests per minute per IP 429 from the edge. Results are cached at the edge for an hour, so a repeated request is answered without running the scan again.
/GetBiomeAt and /GetBiomes 60 requests per minute per IP 429 from the edge. Responses are cached for an hour in the browser and for a day at the edge.
Local server. Running the app yourself has no limit at all, on either route.

The switch applies to every example on this page.

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.

Editions. /GetStructures reads the edition from mc, default Bedrock. /GetStructures/java and /GetStructures/bedrock fix it and ignore mc. /scan, /scan/java and /scan/bedrock behave the same way.

Parameters #

ParameterTypeDefaultDescription
seedint (uint64)0 The world seed. Negative seeds are read as their 64-bit unsigned value, the same way the game reads them.
xfloat0 Player X position, in blocks.
zfloat0 Player Z position, in blocks.
radiusint100 Search radius in chunks. Below 1 is rejected with 400; above 1000 is clamped.
maxint20 Maximum results. Below 1 is rejected with 400; above 200 is clamped.
typesstring5 Comma-separated structure IDs from the table below.
mcstringbedrock Edition on the plain path only: the first letter decides, j... for Java and b... for Bedrock. Anything else is a 400. Ignored on the fixed paths.
Any missing parameter falls back to its default. Successful responses carry only results; error responses add missing_or_invalid. On POST, send the same names as a JSON body or as form data.

Structure IDs #

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

IDStructureIDStructure
1Desert Temple11Ruined Portal
2Jungle Temple12Ruined Portal (Nether)
3Witch Hut13Ancient City
4Igloo14Buried Treasure
5Village15Mineshaft
6Ocean Ruins23Trail Ruins
7Shipwreck24Trial Chamber
8Monument
9Mansion
10Outpost

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 }
  ]
}
Coordinates are block coordinates inside the structure's chunk. A structure can span several chunks, so walk to the point and look around rather than expecting the middle of the building. distance is measured in chunks from the position you passed in. A search that finds nothing returns {"results": []}.

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.

Open request See it in the console
https://www.mineseedfinder.com/GetStructures?seed=31415&x=0&z=0&radius=100&max=50&types=5,8,9

Examples #

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 #

ParameterTypeDescription
seedint (uint64)The world seed. Required.
xfloatBlock X position. Required.
zfloatBlock Z position. Required.

200

minecraft:river
The biome is resolved on Minecraft's native 4 by 4 block grid, so positions inside the same cell answer the same biome. A missing parameter is a 400.

Examples #

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

See it in the console

Endpoint GET /GetBiomes #

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

Parameters #

ParameterTypeDefaultDescription
seedint (uint64)requiredThe world seed.
xfloatrequiredCentre X position, in blocks.
zfloatrequiredCentre Z position, in blocks.
sizeint1Samples per side, 1 to 100. One sample is one output row and one PNG pixel. The widest image at scale 16 is 1600 x 1600 blocks, about ±50 chunks around X/Z.
scaleint4Distance between samples, in blocks: 4, 8 or 16.
outputformatstringimagetext, json or image.

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.
Neither text nor json carries a legend, so the table below is the decoder. It mirrors BIOME_CHARS in app/biomes.py: when that table changes, this one changes with it.

Character legend #

CharBiomeCharBiome
Aminecraft:oceanbminecraft:warm_ocean
Bminecraft:plainscminecraft:lukewarm_ocean
Cminecraft:desertdminecraft:cold_ocean
Dminecraft:windswept_hillseminecraft:deep_warm_ocean
Eminecraft:forestfminecraft:deep_lukewarm_ocean
Fminecraft:taigagminecraft:deep_cold_ocean
Gminecraft:swamphminecraft:deep_frozen_ocean
Hminecraft:riveriminecraft:sunflower_plains
Iminecraft:frozen_oceanjminecraft:windswept_gravelly_hills
Jminecraft:frozen_riverkminecraft:flower_forest
Kminecraft:snowy_plainslminecraft:ice_spikes
Lminecraft:mushroom_fieldsmminecraft:old_growth_birch_forest
Mminecraft:beachnminecraft:old_growth_spruce_taiga
Nminecraft:jungleominecraft:windswept_savanna
Ominecraft:sparse_junglepminecraft:eroded_badlands
Pminecraft:deep_oceanqminecraft:bamboo_jungle
Qminecraft:stony_shorerminecraft:dripstone_caves
Rminecraft:snowy_beachsminecraft:lush_caves
Sminecraft:birch_foresttminecraft:meadow
Tminecraft:dark_forestuminecraft:grove
Uminecraft:snowy_taigavminecraft:snowy_slopes
Vminecraft:old_growth_pine_taigawminecraft:jagged_peaks
Wminecraft:windswept_forestxminecraft:frozen_peaks
Xminecraft:savannayminecraft:stony_peaks
Yminecraft:savanna_plateauzminecraft:deep_dark
Zminecraft:badlands0minecraft:mangrove_swamp
aminecraft:wooded_badlands1minecraft:cherry_grove
2minecraft:pale_garden

Both biome routes allow 60 requests per minute per IP address and answer 429 beyond that.

Examples #

# 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"

See it in the console

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 needs only the seed. edition defaults to Java, x and z to 0, and radius, types and max fall back to the server defaults when omitted. It answers with two tabs: List, the structures near the position sorted by distance and paginated when there are many, and Image, a biome map from /GetBiomes with the result structures marked. A button on the reply opens the SeedFinder console with the same search already filled in.

The image is generated on demand and covers at most 1600x1600 blocks (±50 chunks). For a larger search radius it shows the centre and tells how many results are outside the map.

Commands #

CommandWhat it does
/scan Finds structures near a position. Only seed is required; edition defaults to Java, x and z to 0, and radius in chunks (1-1000), types (names, IDs, or all, with autocomplete) and max (1-200) fall back to the server defaults when omitted. The reply has List and Image tabs.
/types (/tipos) Lists the structure names and IDs the API accepts.
/ping Bot and API status.
/help (/ajuda) How to use the bot.
/config Admins only: which channels may use the bot, the per-channel cooldown, the reply language (English or Portuguese) and the /scan defaults.
/scan seed:31415 edition:Bedrock x:0 z:0 radius:100 types:village,monument max:20
Would you use it? Answer below if the poll loads; it is anonymous and only counted toward the decision to open the bot.

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>