Static Maps API
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.netAuthentication
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
https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=YOUR_API_KEYhttps://styles.maptoolkit.net/maptoolkit/maptoolkit.winter.json?api_key=YOUR_API_KEYhttps://styles.maptoolkit.net/maptoolkit/maptoolkit.hiking.json?api_key=YOUR_API_KEYhttps://styles.maptoolkit.net/maptoolkit/maptoolkit.cycling.json?api_key=YOUR_API_KEYhttps://styles.maptoolkit.net/maptoolkit/maptoolkit.street.json?api_key=YOUR_API_KEYhttps://styles.maptoolkit.net/maptoolkit/maptoolkit.light.json?api_key=YOUR_API_KEYhttps://styles.maptoolkit.net/maptoolkit/maptoolkit.dark.json?api_key=YOUR_API_KEYYou 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¢er=47.3,12.3&zoom=12&marker=center:47.3,12.3|anchor:bottom&api_key=YOUR_API_KEYPolyline
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_KEYGeoJSON
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_KEYKML
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¢er=47.805,13.35&zoom=7&kml=https://static.maptoolkit.net/austria.kml&api_key=YOUR_API_KEYErrors
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 use a flexible 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.