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.

Authentication¶

For local development on a web server at localhost or 127.0.0.1, you can get started without any API keys or domain setup!

For mobile, backend, and non-local web development, you'll need either domain auth or an API key. If you don't already have a Stadia Maps account, sign up for a free to get started.

Domain-based authentication

Domain-based authentication is the easiest form of authentication for production web apps. No additional application code is required, and you don't need to worry about anyone scraping your API keys. We recommend this for most browser-based applications.

Sign in to the client dashboard.
Click "Manage Properties."
Under "Authentication Configuration," click the button to add your domain.

API key authentication

Authenticating requests via API key¶

You can authenticate your requests by adding an API key to the query string or HTTP header.

The simplest is to add a query string parameter api_key=YOUR-API-KEY to your request URL. For example, to access the /tz/lookup API endpoint, your request URL might look like this.

Example URL with an API key placeholder

https://api.stadiamaps.com/tz/lookup/v1?lat=59.43696&lng=24.75357&api_key=YOUR-API-KEY

You can also use an Authorization HTTP header instead of a query string as shown below. Don't forget the Stadia-Auth prefix!

Example Authorization header with an API key placeholder

Authorization: Stadia-Auth YOUR-API-KEY

How to get an API key¶

Don't have an API key yet? Follow these easy steps!

Sign in to the client dashboard. (If you don't have an account yet, sign up for free; no credit card required!)
Click "Manage Properties."
If you have more than one property (ex: for several websites or apps), make sure you have selected the correct property from the dropdown at the top of the page.
Under "Authentication Configuration," you can generate, view or revoke your API key.

Video: How to generate your API key¶

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 following extra usage rights:

You can to store the images for digital use as long as you maintain a paid subscription.
You can print up to 5,000 copies per image if you have a paid subscription when you generate the image.

Images from the standard static maps endpoint are not cacheable beyond standard HTTP caching as dictated by headers.

Refer to our terms of service and credit schedule for the full details and acceptable usage.

GETPOST

You can make HTTP GET requests to either the standard or cacheable endpoint.

Standard Endpoint URL Format

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

Cacheable Endpoint URL Format

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

To make HTTP POST requests, you must use the cacheable endpoint. In addition to having a more permissive license, the POST endpoint is great for complex requests which exceed browser URL length limits.

Cacheable Endpoint URL 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¶

GETPOST

You can configure the map size, viewport, an annotations using query string parameters.

You can configure the map size, viewport, and annotations using JSON body parameters.

Parameter	Example	Description
`size`	`500x250@2x`	Required The size of the map, in points. Defined in size format.
`center`	`56.12,78.23` or `{"latitude": 56.12, "longitude": 78.23}` (POST only)	Required for some requests (see note about automatic calculation) The center of the map in `<lat>, <lon>` format. NB: for POST requests, this can be expressed as either a single string with comma separated values, or an object with `latitude` and `longitude` keys.
`zoom`	`7`	Required for some requests (see note about automatic calculation) The desired zoom level (0-18).
`markers` or `m` (GET only)	(see docs)	Multiple Defines a marker as documented in markers.
`lines` or `l` (GET only)	(see docs)	Multiple Defines a line as documented in lines.
`line_precision`	`5`	Specifies the precision of the polylines in `lines` definitions. Applies to all lines in the image. Defaults to `6` (the same as our routing APIs).
`manual_attribution`	`true`	Hides the attribution watermark. You are still legally bound to display this attribution somewhere on your webpage, printed material, or wherever else you use a static map.
`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 (see the note above on print licensing). If you leave this unspecified, the de facto standard of 72 will be used.

Examples¶

GETPOST

When making a GET request, you can construct a query string using the parameters like so:

URL Query String (Standard or Cacheable GET Requests)

center=59.438484,24.742595&zoom=14&m=59.436884,24.742595&m=59.437485,24.743150&m=59.435561,24.747605&size=600x400@2x&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

JSON POST Body (Cacheable Endpoint Only)

{
  "center": "59.438484,24.742595",
  "size": "600x400@2x",
  "zoom": 14,
  "lines": [
    {
      "shape": "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",
      "color": "333333",
      "width": 5
    }
  ],
  "markers": [
    {
      "lat": 59.436884,
      "lon": 24.742595
    },
    {
      "lat": 59.437485,
      "lon": 24.743150
    }
  ]
}

Automatically Calculate Zoom and Center¶

The Magic Viewport

If your request includes lines or markers, you may choose to not provide center and zoom. The API will calculate a center and zoom that fits all of your annotations automatically!

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 one or more locations on the map with a pin or custom image, and an optional label. Each marker consists of a (latitude, longitude) point and several optional components to customize its appearance.

Marker Components¶

Component	Example	Type	Description
`lat`	`37.77`	Number	Required The latitude of the marker
`lon`	`-122.42`	Number	Required The longitude of the marker
`style`	`outdoors`	String	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. You can specify a custom marker image by specifying a URL prefixed by `custom:`.
`color`	`f00b42`	String	An optional color with which to recolor the image. If specified, the color component will be replaced with this color while the alpha component is left intact. We accept two formats: 6 RGB hex digits or a CSS color name. Do not include a leading `#` as in CSS. Hex digits are case-insensitive. CSS color names are case sensitive (lowercase please).
`label`	`A`	String	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`	String	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.
`anchor`	`center` or `[32, 32]`	String or 2 integers	The anchor point at which to render your custom marker image. Valid string values are `center`, `top`, `right`, `left`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right`. If two integers are provided, they are the x and y offsets respectively from the top left corner of the marker image at which the coordinate should lie.

GETPOST

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

<lat>,<lon>,<style>,<color>,<label>,<label-color>,<anchor|anchor_x>,<anchor_y>

Note that the anchor may take either one or two places if specified! If using a convenience value like center, you only need one positional argument. However if you want to shift the image 12px to the left, you'll specify your offset as two parameters: -12,0.

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 in a GET request 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

When making a POST request to the cacheable endpoint, send a JSON object for each marker using the component names as keys. Note that the markers key in your request body must be an array.

If specifying an anchor using offsets rather than a convenience string, you must provide a JSON array of 2 integers.

{
    "markers": [
        {
            "lat": 37.77,
            "lon": -122.42,
            "style": "custom:https://docs.stadiamaps.com/img/leaf-green.png",
            "anchor": [-32, -95]
        }
    ]
}

Custom Marker Images¶

You can specify a custom marker image by including the URL prefixed by custom: in the style field. For example, custom:https://placehold.co/128x128. Each static map image request may contain up to 5 unique custom marker images (you may have more than 5 markers using any combination of custom and default images, provided that you have no more than 5 custom marker images).

Custom marker images have a maximum size of 128px in either dimension. They also have a maximum size of 128,000 bytes. Note that the marker will be rendered pixel for pixel; if you are using @2x scale (retina) maps, then your map size will be larger. If you're a mobile designer familiar with points / device-independent pixels, you can think of the images as having an effective max size of 64x64.

Custom marker images may be cached by our servers in accordance with HTTP headers to improve performance. If your images fail to load after a reasonable period of time, or they do not conform to our requirements, your request will fail (and it may consume the same credits as if it succeeded, depending on why the request failed).

Lines¶

Adding a line allow you to draw things like routes and boundaries on a static map image. Each line consists of a shape (provided as an encoded polyline) and optionally custom color and width.

GETPOST

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

<shape>,<stroke_color>,<stroke_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>,,<stroke_width>

Multiple Lines

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

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

When making a POST request to the cacheable endpoint, send a JSON object for each line using the component names as keys. Note that the markers key in your request body must be an array.

{
    "lines": [
        {
            "shape": "oaxiJgp_vCdEmB~NiMwf@cK",
            "stroke_color": "blue",
            "stroke_width": 5
        }
    ]
}

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 parameter `line_precision` (see request parameters for more details).
`stroke_color`	`cccccc`	The color of the line stroke (defaults to a style-appropriate color). We accept two formats: 6 RGB hex digits or a CSS color name. Do not include a leading `#` as in CSS. Hex digits are case-insensitive. CSS color names are case sensitive (lowercase please).
`stroke_width`	`5`	Set the line stroke 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.

Example¶

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

ImageHTMLcURL (POST)

Static Map

<img src="https://tiles.stadiamaps.com/static/alidade_smooth.png?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,,,C&m=59.437485,24.743150,,,B&m=59.434931,24.745442,,,D&m=59.441293,24.747380,custom:https%3A%2F%2Fdocs.stadiamaps.com%2Fimg%2Fleaf-green.png,,,,-32,-95&markers=59.435561,24.747605,,red,E&size=600x400@2x" />

    curl -X POST -H "Content-Type: application/json" -d '{
      "center": "59.438484,24.742595",
      "size": "600x400@2x",
      "zoom": 14,
      "lines": [
        {
          "shape": "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",
          "color": "333333",
          "width": 5
        }
      ],
      "markers": [
        {
          "lat": 59.436884,
          "lon": 24.742595
        },
        {
          "lat": 59.437485,
          "lon": 24.743150
        },
        {
          "lat": 59.434931,
          "lon": 24.745442
        },
        {
          "lat": 59.441293,
          "lon": 24.747380,
          "style": "custom:https://docs.stadiamaps.com/img/leaf-green.png",
          "anchor": [-32, -95]
        },
        {
          "lat": 59.435561,
          "lon": 24.747605,
          "color": "red",
          "label": "E"
        }
      ]
    }' "https://tiles.stadiamaps.com/static_cacheable/alidade_smooth?api_key=YOUR-API-KEY"