Static Maps API

On this page

The Static Maps API returns a map as a JPEG, PNG, or WebP image. You specify the location, zoom, size, and optional overlays like markers or routes.

Use this API to embed maps in emails, PDFs, or anywhere you need a plain image instead of an interactive map.

Base URL

https://staticmap.maptoolkit.net

Authentication

Add your API key as ?api_key=YOUR_API_KEY to every request. See Authentication for details.

Parameters

Location

Parameter	Type	Required	Description
`center`	`lat,lng`	Yes (or `bounds`)	Center of the map.
`zoom`	number	Yes (or `bounds`)	Zoom level (1-17). 1 = whole world, 17 = neighborhood level.
`bounds`	`north,east,south,west`	Yes (or `center`+`zoom`)	Bounding box. The map is automatically fitted to these coordinates.
`delta_zoom`	number	No	Adjusts the zoom level calculated from `bounds`.

Map Style

Parameter	Type	Required	Description
`size`	`{width}x{height}`	Yes	Image size in pixels, e.g., `750x400`.
`maptype`	string	No	Map style. Use the bold style name from Standard Map Styles below.
`format`	string	No	Output format: `png` (default), `jpeg`, or `webp`.
`factor`	number	No	Image scale factor. Use `2` for retina displays. Default: `1`.

Overlays

Parameter	Type	Description
`marker`	string	Add a marker to the map. Can be repeated for multiple markers.
`path`	string	Draw a polyline on the map. Can be repeated.
`path_icons`	string	Add direction arrows to all polylines. Use `true` for defaults.
`geojson`	string	Render a GeoJSON `LineString` or `MultiLineString`.
`kml`	URL	Render polylines and polygons from a KML file.

Standard Map Styles

maptoolkit-maptoolkit.summer

Topographic outdoor map with terrain shading (default)

https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=YOUR_API_KEY

maptoolkit-maptoolkit.winter

Topographic outdoor map with a winter look

https://styles.maptoolkit.net/maptoolkit/maptoolkit.winter.json?api_key=YOUR_API_KEY

maptoolkit-maptoolkit.hiking

Hiking-focused outdoor map

https://styles.maptoolkit.net/maptoolkit/maptoolkit.hiking.json?api_key=YOUR_API_KEY

maptoolkit-maptoolkit.cycling

Cycling-focused outdoor map

https://styles.maptoolkit.net/maptoolkit/maptoolkit.cycling.json?api_key=YOUR_API_KEY

maptoolkit-maptoolkit.street

Detailed street map

https://styles.maptoolkit.net/maptoolkit/maptoolkit.street.json?api_key=YOUR_API_KEY

maptoolkit-maptoolkit.light

Minimal light theme

https://styles.maptoolkit.net/maptoolkit/maptoolkit.light.json?api_key=YOUR_API_KEY

maptoolkit-maptoolkit.dark

Dark theme with high contrast

https://styles.maptoolkit.net/maptoolkit/maptoolkit.dark.json?api_key=YOUR_API_KEY

You can preview all styles at maptoolkit.com/map.

Overlays

Marker

The marker parameter uses pipe-separated key:value pairs:

marker=icon:{icon_url}|anchor:{center|bottom}|center:{lat,lng}

Key	Description
`center`	Marker position as `lat,lng`. Required.
`icon`	URL to a PNG image to use as the marker icon.
`anchor`	Where the icon anchors to the coordinate: `bottom` (default) or `center`.

The example map above uses this URL:

https://staticmap.maptoolkit.net/?maptype=maptoolkit-maptoolkit.summer&size=750x300&center=47.3,12.3&zoom=12&marker=center:47.3,12.3|anchor:bottom&api_key=YOUR_API_KEY

Polyline

The path parameter uses pipe-separated key:value pairs:

path=width:{px}|color:{RRGGBBAA}|points:{lat,lng}|{lat,lng}|...

Key	Description
`points`	List of `lat,lng` pairs separated by `\|`.
`width`	Line thickness in pixels. Default: `3`.
`color`	Line color as a 32-bit hex RGBA value, e.g., `FF0000FF` for solid red.

The example map above also sets path_icons=true and uses this URL:

https://staticmap.maptoolkit.net/?maptype=maptoolkit-maptoolkit.light&size=750x300&bounds=47.28852,12.52935,47.21155,12.16843&path_icons=true&path=width:4|color:b50006ff|points:47.21359,12.16856|47.21155,12.16860|47.22167,12.18551|47.22563,12.18671|47.23277,12.19839|47.23571,12.19585|47.24233,12.21152|47.24244,12.21654|47.24664,12.21920|47.24693,12.22783|47.24399,12.22757|47.24419,12.24448|47.23644,12.24632|47.23242,12.24504|47.23134,12.24714|47.23828,12.25392|47.24402,12.26336|47.24533,12.27194|47.25212,12.27336|47.25369,12.27696|47.25372,12.28628|47.25101,12.28508|47.24947,12.28688|47.24923,12.29417|47.25200,12.29641|47.25016,12.30331|47.25296,12.31632|47.25978,12.31834|47.26720,12.33580|47.27093,12.33911|47.27268,12.34790|47.27591,12.35331|47.27524,12.36142|47.27978,12.37425|47.27306,12.37558|47.27871,12.39824|47.27757,12.41674|47.27358,12.42245|47.27792,12.42352|47.27882,12.44373|47.28336,12.45489|47.28307,12.48025|47.28103,12.48150|47.28060,12.48562|47.27786,12.48729|47.27780,12.49296|47.28118,12.50270|47.28051,12.52274|47.28255,12.52695|47.28852,12.52935&api_key=YOUR_API_KEY

GeoJSON

The `geojson` parameter renders a `LineString` or `MultiLineString`:

geojson=color:{RRGGBBAA}|width:{px}|geometry:{GeoJSON}

The example map above uses this URL:

https://staticmap.maptoolkit.net/?maptype=maptoolkit-maptoolkit.dark&size=750x300&geojson=color:0dbf9566|width:6|geometry:{"type":"MultiLineString","coordinates":[[[16.431427001953125,47.845883513447276],[16.481552124023438,47.821915003877976],[16.495285034179688,47.817304405844226],[16.556396484375,47.832056878293166]],[[16.53511047363281,47.8703015638657],[16.53717041015625,47.85740289465826],[16.5234375,47.83482250011287],[16.513824462890625,47.816382237102744],[16.489105224609375,47.794245273679884],[16.478118896484375,47.77855921633884]]]}&api_key=YOUR_API_KEY

KML

Use the kml parameter to render lines and polygons from a KML file. The kml parameter can only be defined once. Polylines or Polygons will be extracted from the KML file and rendered on the staticmap.

kml={kml_file_url}

The example map above uses this URL:

https://staticmap.maptoolkit.net/?maptype=maptoolkit-maptoolkit.summer&size=750x400&center=47.805,13.35&zoom=7&kml=https://static.maptoolkit.net/austria.kml&api_key=YOUR_API_KEY

Errors

Errors return the HTTP status code with a plain-text message in the body.

Status	Meaning
`403`	The API key is missing (`Access denied!`) or not recognized (`Api-key not found!`). See First Steps.
`400`	A parameter failed validation, a feature could not be parsed, or rendering timed out.

Parameter validation

Message	Cause
`invalid size`	`size` is missing or does not match `{width}x{height}`.
`invalid center`	`center` does not match `lat,lng`.
`invalid bounds`	`bounds` does not match `lat1,lng1,lat2,lng2`.
`invalid bbox`	`bbox` does not match `lng1,lat1,lng2,lat2`.
`invalid zoom`	`zoom` is not a number, or falls outside 0 to 20 after `delta_zoom` is applied.
`invalid ratio`	`ratio` or `factor` is not 1, 2, or 4.
`invalid exptime`	`exptime` is not an integer.
`invalid credits`	`credits` does not match `\w+`, or the file does not exist.
`invalid style`	The style string does not match `[\w\-]+` and is not a JSON object.
`invalid longitude`	Longitude is outside -180 to 180.
`invalid latitude`	Latitude is outside -85 to 85.

Features and external resources

Message	Cause
`invalid marker: {marker}`	The marker has no valid `center:{lat},{lng}`.
`invalid path: {path}`	The path has no `points:` section.
`invalid geojson: {geojson}`	The GeoJSON geometry is not valid JSON.
`Error parsing KML {url}: {message}`	The KML document could not be parsed or converted.
`Error fetching KML {url}: {message}`	The HTTP request for the KML URL failed.
`Cannot load style: {message}`	The style URL could not be loaded. A cached style is used if one is available.
`redering aborted`	The request hit the 60 second render timeout, or the client disconnected.

The redering aborted spelling is what the service returns; match on it exactly.

Rate limits

Limits are monthly request quotas tied to your plan rather than a per-second rate: the service returns no RateLimit-* or Retry-After headers. Current allowances are on the pricing page.

The free Basic plan has a hard limit, so requests are refused once it is reached. On Pro and Ultra, requests past the allowance are billed rather than refused. Enterprise plans have no request limit.

Requests to this endpoint count toward your plan’s request allowance.

Pricing

Self-service plans (Basic, Pro, and Ultra) are billed through RapidAPI; see RapidAPI for how to subscribe and authenticate. Plan limits and prices are listed on the Maptoolkit pricing page. Enterprise customers call the native hosts directly with a Maptoolkit API key.