Static maps

While we recommend an interactive map in most cases, sometimes you just need a very simple static map to embed on your web page or display in an app. We offer static map images for you to embed easily on your website or in an app.

URL format

The URL format goes like this:<theme>?api_key=<key>&center=<lat>,<long>&zoom=<zoom>[&markers=lat,long,[style_variant],[color],[label]][&manual_attribution=true]&size=<width>x<height>[@2x]

The parameters are as follows:

  • theme - The theme name. You can find the available themes in our theme library.
  • key (Optional) - Your API key. If you are trying to include static maps in a mobile application, you will need to include an API key. If you are embedding this in an image tag on a web page, do not include an API key. See here for more details.
  • lat - The latitude of the center of the map.
  • long - The longitude of the center of the map.
  • zoom - The desired zoom level (1-18).
  • markers (Optional) - Markers can be optionally specified as lat/long pairs, separated by pipes (|). For example, you could add two markers like so: 37.7776948,-122.4226193|37.7676948,-122.2226193.
    • style_variant - In addition to position, you may optionally override 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. For example, 37.7776948,-122.4226193,alidade_smooth_sm|37.7676948,-122.2226193 would indicate two markers: one normal size and one small.
    • color - If you don't like the default colors for our markers or you want to add some differentiation, you can also 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). You do not need to specify a style_variant to specify a color, but you do need to include an extra comma. For example, 37.7776948,-122.4226193,,f00b42.
    • label - 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-ish, and many additional unicode points are supported (we use Google's Noto Mono, and will accept any glyph present in this font). You can not specify a style_variant, 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. You can not specify the text color, as we select an appropriate color automatically based on contrast ratio.
  • width - 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 - 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.
  • image scale - 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.
  • dpi (Optional) - 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. (Please remember to get in touch with us before you do though, as our standard licenses only apply to online formats.) If you leave this unspecified, the de facto standard of 72 will be used.
  • manual_attribution (Optional) - 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.


To put it all together, here is a typical example: Static Map,24.742595&zoom=14&markers=59.436884,24.742595|59.437485,24.743150|59.434931,24.745442|59.441293,24.747380|59.435561,24.747605&size=600x400@2x