Skip to content

Static Map Images

Free

Starter

Standard

Professional

Static map images let you easily add non-interactive maps to your website or app. These easy-to-use maps push the rendering complexity off to our APIs, while still giving you flexibility to customize the maps with annotations.

URL format

Static map images are specified by a base URL and a set of parameters. The base URL depends on your style, format, and whether you intend to cache the map for reuse.

Cacheable and Printable Static Maps

Do you want to re-use a static map image across many requests (for example, to show an event location or a fixed tour route that rarely changes)? Or print them out for redistribution? The cacheable endpoint grants you the right to store the images for digital use as long as you maintain a paid subscription, and print up to 5,000 copies per image! It's available for all styles except Alidade Satellite.

Special pricing applies to the cacheable endpoint. You can always find our current credit schedule at stadiamaps.com/pricing. Images from the standard static maps endpoint are not cacheable beyond standard HTTP caching as dictated by headers. Refer to our terms of service for the full details and acceptable usage.

https://tiles.stadiamaps.com/static/<style><format>

https://tiles.stadiamaps.com/static_cacheable/<style><format>

URL Path Parameters

The following parameters appear directly in the URL path component. Fill these in where the placeholders appear in the URL format (above).

Parameter Example Description
style outdoors Required
The style name. You can find the supported styles in our style library.
format .png Optional The image format. Supported options: .png, .jpeg, .jpg. Defaults to .png.

Request Parameters

These request parameters let you customize size and viewport, and draw annotations on top of the map. Note that some parameters may be specified multiple times in the query string.

Parameter Example Description
size 500x250@2x Required
The size of the map, in points. Defined in size format.
center 56.12,78.23 Required for some requests (see note about automatic calculation)
The center of the map in (<lat>, <lon>) format.
zoom 7 Required for some requests (see note about automatic calculation)
The desired zoom level (0-18).
markers
or
m		 (see docs) Multiple
Defines a marker as documented in markers.
lines
or
l		 (see docs) Multiple
Defines a line as documented in lines.
line_precision 5 Specify the precision of the polylines in lines definitions. Applies to all lines in the image. Defaults to 6 (the same as our routing APIs and OSM generally).
manual_attribution true If you are providing attribution elsewhere on the page, printed material, or wherever else you use a static map, you may use this query string argument. It is your responsibility to add the correct attribution if you use this flag.
dpi 72 If you would like to specify a DPI hint, you may do so. Note that this doesn't really change anything about the actual rendering process or the number of pixels in the final output. If you need to use the resulting images in print, this may be useful to you.1 If you leave this unspecified, the de facto standard of 72 will be used.

Authenticating your Requests

Like other requests, static map requests require authentication. If you're using domain-based auth on your website, you're good to go! Otherwise, add an api_key parameter in the query string.

Automatically Calculate Zoom and Center

The Magic Viewport

If you provide either lines or markers, you may choose to not provide center and zoom, and a center and zoom that fits all lines and markers will be calculated for you.

Size Format

The size parameter defines the size of the map, in points.

size=<width>x<height>[<scale>]
Parameter Example Description
width 500 Required
The desired image width, in points. If a scale modifier is included, then this value may be multiplied to provide extra pixels. The minimum value is 256, unless you specify that you will be including an attribution manually, in which case it is 64. The maximum is 4096. Note that browsers may have trouble rendering anything larger than 1024.
height 250 Required
The desired image height, in points. If a scale modifier is included, then this value may be multiplied to provide extra pixels. The minimum value is 64, and the maximum is 4096. Note that browsers may have trouble rendering anything larger than 1024.
scale @2x We recommend including an @2x suffix unless you know your site will not be displayed on any high DPI displays. You can omit this though to save bandwidth if that is a concern. You can set the width in screen-independent points using the HTML img tag.

Markers

Adding a marker to a map is a way to highlight a significant location in the image with a pin or a label. Each marker consists of a (latitude, longitude) point with four optional components to customize its appearance.

Our API supports multiple markers, and when provided, we can use the markers to automatically center and zoom the image to a suitable viewport.

Marker components are separated by a comma (,), and a fully specified marker would use the following form:

<lat>,<lon>,<style>,<color>,<label>,<label-color>

Marker Components

Component Example Description
lat 37.77 Required
The latitude of the marker
lon -122.42 Required
The longitude of the marker
style outdoors Set the marker style. The default marker style name is the same as the map style (alidade_smooth for example). You can explicitly use markers from another map style, or you can specify the small variant by adding _sm to the style name. Note: this parameter is ignored if a label is set.
color f00b42 If you want to change the color of a marker, you can specify a color as a 4th component of a marker definition. We accept two formats: 6 RGB hex digits or a CSS color name. Do not include a leading # as in a CSS definition. Hex digits are case-insensitive. CSS color names are case sensitive (lowercase please).
label A If you want to differentiate your markers with labels, you can also specify a single character label (anything beyond this will be truncated) as a 5th component of a marker definition. All Latin characters, and many additional unicode points are supported (we use Google's Noto Mono, and will accept any glyph present in this font). You may not specify a style, and color is optional. As noted in the docs for color, you do need one or two extra commas. For example, 37.7776948,-122.4226193,,f00b42,A or 37.7776948,-122.4226193,,,A.
label-color f00b42 If you prefer to use your own text color for the marker label, you may optionally specify a text color (using the same methods as defined above in color). If you do not specify a color, it will default to either white or black, based on the marker background color.

Order Matters!

The order and position of the marker components matters. Optional components may be left blank, but you need to use extra commas to specify components later in the order.

For example, specifying a label with a custom color, while leaving defaults for the marker style and color would look like this:

37.77,-122.42,,,a,f004b2

Multiple Markers

You may specify markers or m multiple times to create multiple markers.

&markers=59.437485,24.743150&markers=59.436884,24.742595

or

&m=59.437485,24.743150&m=59.436884,24.742595

Lines

Adding a line allow you to draw a route or a shape on the static map. Each line consists of a shape (provided as an encoded polyline) with an optional custom color and width.

Similar to markers, line components are separated by a comma (,), and a fully specified line would have the following form:

<shape>,<color>,<width>

Also like markers, line components are ordered, and position matters. Use an "empty" slot, if you want to specify a width without a color:

<shape>,,<width>

Line Components

Component Example Description
shape oaxiJgp_vCdEmB~NiMwf@cK Required
The polyline defining the shape of the marker.
Polyline precision is set by the global query parameter line_precision (see query parameters for more details).
color cccccc The color of the marker. Like markers, both hex and CSS colors are accepted (see marker components for more details).
width 5 Set the line width (in points).

Polyline Precision

Polylines are interpreted with a default precision of 6, a convention well established in the OSM community and adopted by our other APIs. Some competitors' products default to a precision of 5. If you add a line and it's not showing up, or appears in an unexpected location, check if perhaps the precision is wrong.

See this great article on why choosing a precision of 6 makes a lot of sense.

Multiple Lines

You may specify lines or l multiple times to create multiple lines.

&l=oaxiJgp_vCdEmB~NiMwf@cK&l=oaxiJgp_vCdEmB~NiMwf@cK

Example

To put it all together, here is a typical example:

Static Map

<img src="https://tiles.stadiamaps.com/static/alidade_smooth?center=59.438484,24.742595&zoom=14&l=oj_kpBkhmen@vFvDlStSdIzN`BxCfMfShA`B~@|AvCrDpG`FfVfRb\zSrBdBhZx\pFdM~BpFn@zAxCrHrH|QjOh_@NtM|Vv@d@aHdHEfD^\DhCh@nIjFlFvE~CfCzAzAdFjFt@t@~EdG]cEc@{Fm@uF]oDgAwJhAm@vMqGoAs{@dAMfG_@dE_@Ezb@ExWzBBZ?L@|DnTtAqE~CyMp@sB|@n@XUx@uBjAiApBi@lBp@hAtAzAClSjJzAkMtAl@dA}@~CVbB`@pDtAN}DxD`AdFi@vBIxBIe@aMuAgPyFwy@{Ca_@yFar@[{C_AsGuAkGqEgY_CmLqAuFuHi[m@vBq@hC,333333,5&m=59.436884,24.742595&m=59.437485,24.743150&m=59.434931,24.745442&m=59.441293,24.747380&m=59.435561,24.747605&size=600x400@2x" />

  1. Remember to get in touch with us before you do though, as our standard licenses only apply to online formats. ↩