rcemaps API

Map images for any Rust Console Edition seed, over plain HTTP. No signup, no OAuth — point an <img> or a Discord embed at a URL and you get a PNG.

Quick start

https://rcemaps.com/api/v1/map.png?seed=1234567&size=4500&clean=1

That is the entire integration for most bots. In discord.js:

const seed = 1234567, size = 4500;
const url = `https://rcemaps.com/api/v1/map.png?seed=${seed}&size=${size}&clean=1`;

await interaction.reply({ embeds: [{
  title: `Rust Console — seed ${seed}`,
  url:   `https://rcemaps.com/?seed=${seed}&size=${size}`,
  image: { url },
}] });

Discord fetches the image itself and caches it, so a popular map costs you one request no matter how many people see the message.

Authentication

Optional. Without a key you are metered by IP at the anonymous rate, which is enough for a small bot. If you need more, ask for a free key and send it as an X-API-Key header. A ?key= query parameter also works where headers are awkward, but prefer the header — query strings end up in server logs and browser history.

curl -H "X-API-Key: rce_…" \
     "https://rcemaps.com/api/v1/limits"

Rate limits

Two separate budgets, because the two kinds of request cost very different things. Asking for a map that has been rendered before is nearly free; asking for one that has not means generating it. Only the second draws from the “new maps” budget — re-posting maps you have already requested is effectively unmetered.

Tier	Requests	New maps
anon	60/min (burst 30)	5/min (burst 3)
key	600/min (burst 120)	60/min (burst 20)

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; a 429 also carries Retry-After. Check X-Cache on an image response to see whether you paid for a generation: HIT means you did not.

If you are backfilling a lot of seeds, request them slowly rather than in a burst, and cache the PNGs at your end. Ask for a key and say what you are building — that is easier for both of us than being rate-limited.

Endpoints

GET /api/v1/map.png

The map image, 512×512 PNG. Takes the parameters below.

GET /api/v1/map.json

Metadata for the same map: the image URL, a link to the interactive version, land_pct when known, and whether it is already rendered. Validates your parameters without generating anything.

GET /api/v1/servers

Which seeds the official Console servers are currently running, and how many servers are on each. Use it to show “your server’s map” without asking anyone to type a seed.

GET /api/v1/limits

Your tier and how much of each budget is left.

Parameters

Name	Default	Accepts	Notes
`seed`	required	0 – 2147483647	The world seed.
`size`	4500	1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500	World size in metres.
`style`	ingame	ingame, height, biome, topo	Map view: the in-game look, a heightmap, biome colours, or topography.
`quality`	fast	fast, quality	`quality` resolves finer terrain detail and is slower to produce.
`clean`	0	0 or 1	1 drops the grid and the info bar, leaving just the map — best for a Discord embed.

Terrain commands

Every terrain.* and env.oceanlevel command the game takes works here too, so you can render the map a server is actually running rather than the stock one for that seed. Drop the terrain. prefix and pass the command as a query parameter — terrain.elevation_hill 0.8 becomes elevation_hill=0.8, and env.oceanlevel 5 becomes oceanlevel=5.

So a server booted with:

server.seed 1234567
server.worldsize 4500
--terrain.elevation_hill 0.8
--terrain.center_falloff 1200
env.oceanlevel 5

is this request:

https://rcemaps.com/api/v1/map.png?seed=1234567&size=4500&clean=1
  &elevation_hill=0.8&center_falloff=1200&oceanlevel=5

The ten noise_* commands take Rust's own syntax, url-encoded because of the = and ,:

&noise_base_land=oct%3D6%2Cfreq%3D1%2Camp%3D4%2Coffset%3D-0.4

Most HTTP clients encode that for you — in JavaScript, build it with new URLSearchParams({ seed, size, noise_base_land: 'oct=6,freq=1,amp=4,offset=-0.4' }).

Every distinct set of commands is a different map, so the first request for one has to render and comes out of your new-maps budget. Repeats are cached like any other map. If your bot lets people tweak sliders live, debounce it.

Command names are validated: an unknown parameter or an unparseable value is a 400 naming the offender, rather than a stock map handed back as though nothing were wrong. The full list of commands and what each one does is in the command guide.

Errors

Errors are JSON: {"error": "bad_size", "message": "…"}. Switch on error, show message.

Status	error	What to do
`400`	`missing_seed`, `bad_seed`, `bad_size`, `bad_style`, `bad_quality`, `bad_terrain`, `unknown_parameter`	Fix the request; it will never succeed as sent. `unknown_parameter` also lists the offending names in an `unknown` array.
`401`	`invalid_key`	The key was not recognised. Omit it to fall back to the anonymous tier.
`429`	`rate_limited`, `generate_rate_limited`	Wait `retry_after` seconds. Honour the `Retry-After` header.
`503`	`busy`, `unavailable`, `maintenance`	Temporary. Retry with backoff.

Using the images

Free to use, including in bots on servers you monetise. One ask: leave the rcemaps.com mark on the image.

Maps are deterministic: the same seed and size always produce the same image, so they are safe to cache forever at your end.

This API is versioned. /api/v1 will not change under you in a breaking way; anything incompatible arrives as /api/v2.