API Reference

Static Maps API Reference

Base URL

https://staticmap.maptoolkit.net

Endpoints

`GET /`

Render a static map image

Renders a static map image from query parameters. At minimum size and either center+zoom or bounds/bbox (or at least one overlay feature) must be provided.

Parameter	In	Type	Required	Description
`api_key`	query	string	Yes	API key for authentication.
`size`	query	string	Yes	Output image dimensions as `{width}x{height}`. Maximum 4096x4096 pixels.
`center`	query	string	No	Map center as `{lat},{lng}`.
`zoom`	query	number	No	Zoom level (0–20).
`bounds`	query	string	No	Bounding box as `{minlat},{minlng},{maxlat},{maxlng}`.
`bbox`	query	string	No	Bounding box as `{minlng},{minlat},{maxlng},{maxlat}` (GeoJSON order).
`style`	query	string	No	Style ID or inline Mapbox GL style JSON. Defaults to `maptoolkit-maptoolkit.summer`.
`maptype`	query	string	No	Deprecated. Use `style` instead.
`format`	query	string	No	Output image format. Default: `png`. One of: `png`, `jpeg`, `webp`.
`ratio`	query	integer	No	Pixel density multiplier (1 = standard, 2 = retina, 4 = ultra-high-DPI). Default: `1`. One of: `1`, `2`, `4`.
`factor`	query	integer	No	Deprecated. Use `ratio` instead. One of: `1`, `2`, `4`.
`credits`	query	string	No	Attribution overlay name. Default: `osm`.
`attribution`	query	string	No	Set to `false` to suppress the attribution overlay. One of: `false`.
`exptime`	query	integer	No	Cache TTL in seconds. `-1` bypasses the cache. Default: `7200`.
`delta_zoom`	query	integer	No	Integer offset added to the resolved zoom level.
`states`	query	string	No	State filter forwarded to the style URL template.
`marker`	query		No	Marker overlay. Pipe-delimited: `center:{lat},{lng}\|icon:{url}\|anchor:{center\|bottom}`. Repeat for multiple markers.
`path`	query		No	Polyline overlay. Pipe-delimited: `points:{lng1},{lat1}\|{lng2},{lat2}\|...\|width:{px}\|color:{RRGGBBAA}`. Repeat for multiple paths.
`geojson`	query		No	GeoJSON geometry overlay. Pipe-delimited: `geometry:{GeoJSON}\|width:{px}\|color:{RRGGBBAA}`. Repeat for multiple overlays.
`kml`	query		No	URL of a KML file to overlay. Repeat for multiple files.
`path_icons`	query	string	No	Directional icons along paths. `true` for defaults, or `icon:{name}\|size:{scale}\|spacing:{px}`.
`marker_z_order`	query	string	No	Z-order strategy for marker rendering. Default: `auto`. One of: `source`, `auto`.
`debug`	query	boolean	No	Enables server-side timing logs.

Status Description

200 Successfully rendered map image.

Status	Description
`200`	Successfully rendered map image.
`400`	Bad request. Possible error messages: Parameter validation errors: `invalid size` — Missing or invalid `size` parameter (must match `\d+x\d+`) `invalid center` — `center` does not match format `lat,lng` `invalid bounds` — `bounds` does not match format `lat1,lng1,lat2,lng2` `invalid bbox` — `bbox` does not match format `lng1,lat1,lng2,lat2` `invalid zoom` — `zoom` is not a valid number or is outside range 0–20 (after `delta_zoom`) `invalid ratio` — `ratio`/`factor` is not 1, 2, or 4 `invalid exptime` — `exptime` is not a valid integer `invalid credits` — `credits` does not match `\w+` or the file does not exist `invalid style` — Style string does not match `[\w\-]+` (when not a JSON object) Coordinate validation errors: `invalid longitude` — Longitude is outside range −180 to 180 `invalid latitude` — Latitude is outside range −85 to 85 Feature validation errors: `invalid marker: {marker}` — Marker does not contain a valid `center:{lat},{lng}` `invalid path: {path}` — Path does not contain a valid `points:` section `invalid geojson: {geojson}` — GeoJSON geometry cannot be parsed as JSON External resource errors: `Error parsing KML {url}: {message}` — KML document cannot be parsed or converted `Error fetching KML {url}: {message}` — HTTP request for KML URL failed `Cannot load style: {message}` — Style URL could not be loaded (falls back to cached style if available) Timeout errors: `redering aborted` — Request timeout (60 seconds) or client abort

400

Bad request. Possible error messages:

Parameter validation errors:

invalid size — Missing or invalid size parameter (must match \d+x\d+)
invalid center — center does not match format lat,lng
invalid bounds — bounds does not match format lat1,lng1,lat2,lng2
invalid bbox — bbox does not match format lng1,lat1,lng2,lat2
invalid zoom — zoom is not a valid number or is outside range 0–20 (after delta_zoom)
invalid ratio — ratio/factor is not 1, 2, or 4
invalid exptime — exptime is not a valid integer
invalid credits — credits does not match \w+ or the file does not exist
invalid style — Style string does not match [\w\-]+ (when not a JSON object)

Coordinate validation errors:

invalid longitude — Longitude is outside range −180 to 180
invalid latitude — Latitude is outside range −85 to 85

Feature validation errors:

invalid marker: {marker} — Marker does not contain a valid center:{lat},{lng}
invalid path: {path} — Path does not contain a valid points: section
invalid geojson: {geojson} — GeoJSON geometry cannot be parsed as JSON

External resource errors:

Error parsing KML {url}: {message} — KML document cannot be parsed or converted
Error fetching KML {url}: {message} — HTTP request for KML URL failed
Cannot load style: {message} — Style URL could not be loaded (falls back to cached style if available)

Timeout errors:

redering aborted — Request timeout (60 seconds) or client abort

`POST /`

Render a static map image (POST)

Same rendering logic as GET / but accepts parameters in the request body. Useful when query strings would exceed URL length limits (e.g. large GeoJSON payloads). The api_key must still be passed as a query parameter.

Parameter	In	Type	Required	Description
`api_key`	query	string	Yes	API key for authentication.