CARTO.js

Integrate interactive maps and location data into your web applications and websites.

This library is still under support but it will not be further developed. We don’t recommend starting new projects with it as it will eventually become deprecated. Instead, learn more about our current CARTO for deck.gl library here

Static Maps

Static views of CARTO maps can be generated using the Static Maps API within CARTO.js. The map’s style, including the zoom and bounding box, follows from what was set in the viz.json file, but you can change the zoom, center, and size of your image with a few lines of code. You can also change your basemap Images can be placed in specified DOM elements on your page, or you can generate a URL for the image.

Quick Start

The easiest way to generate an image is by using the following piece of code, which generates is replaced by an img tag once run in an HTML file:

1
2
3
4
5
6
7
8
9

<script>
var vizjson_url = 'https://documentation.carto.com/api/v2/viz/008b3ec6-02c3-11e4-b687-0edbca4b5057/viz.json';

cartodb.Image(vizjson_url)
  .size(600, 400)
  .center([-3.4, 44.2])
  .zoom(4)
  .write({ class: "thumb", id: "AwesomeMap" });
</script>
Result
1

<img id="AwesomeMap" src="https://cartocdn-ashbu.global.ssl.fastly.net/documentation/api/v1/map/static/center/04430594691ff84a3fdac56259e5180b:1419270587670/4/-3.4/44.2/600/400.png" class="thumb">

cartodb.Image(layerSource[, options])

Arguments
Name Description
layerSource can be either a viz.json object or a MapConfig object.

Note: If defining an image through the MapConfig layer definition, you must set the tiler_domain, tiler_port, and tiler_protocol, as displayed in this example. Otherwise the Static Image API tries to use your localhost to source the tiles and an error appears.
options  
|_ basemap change the basemap specified in the layer definition. Type: Object defining base map properties (see example below).
|_ no_cdn Disable CDN usage. Type: Boolean. Default: false (use CDN)
|_ override_bbox Override default of using the bounding box of the visualization. This is needed to use Image.center and Image.zoom. Type: Boolean. Default: false (use bounding box)
Returns

An Image object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<script>
var vizjson_url = 'https://documentation.carto.com/api/v2/viz/008b3ec6-02c3-11e4-b687-0edbca4b5057/viz.json';
var basemap = {
  type: "http",
  options: {
    urlTemplate: "http://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
    subdomains: ["a", "b", "c"]
  }
};

cartodb.Image(vizjson_url, {basemap: basemap})
  .size(600, 400)
  .center([0,0])
  .write({ class: "thumb", id: "AwesomeMap" });
</script>

cartodb.Image

Image.size(width, height)

Sets the size of the image.

Arguments
Name Description
width the width of the resulting image in pixels
height the height of the resulting image in pixels
Returns

An Image object

Image.center(latLng)

Sets the center of the map.

Arguments
Name Description
latLng an array of the latitude and longitude of the center of the map. Example: [40.4378271, -3.6795367]
Returns

An Image object

Image.zoom(zoomLevel)

Sets the zoom level of the static map. Must be used with the option override_bbox: true if not using Image.center or Image.bbox.

Arguments
Name Description
zoomLevel the zoom of the resulting static map. zoomLevel must be an integer in the range [0,24].
Returns

An Image object

Image.bbox(boundingBox)

If you set bbox, center and zoom will be overridden.

Arguments
Name Description
boundingBox an array of coordinates making up the bounding box for your map. boundingBox takes the form: [sw_lat, sw_lon, ne_lat, ne_lon].
Returns

An Image object

Image.into(HTMLImageElement)

Inserts the image into the HTML DOM element specified.

Arguments
Name Description
HTMLImageElement the DOM element where your image is to be located.
Returns

An Image object

Example
1

cartodb.Image(vizjson_url).into(document.getElementById('map_preview'))

Image.write(attributes)

Adds an img tag in the same place script is executed. It’s possible to specify a class name (class) and/or an id attribute (id) for the resulting image:

Arguments
Name Description
class the DOM class applied to the resulting img tag.
id the DOM id applied to the resulting img tag.
src path to a temporary image that acts as a placeholder while the static map is retrieved.
Returns

An Image object

Example
1
2
3
4
5
6
7

<script>
cartodb.Image(vizjson_url)
  .size(600, 400)
  .center([-3.4, 44.2])
  .zoom(10)
  .write({ class: "thumb", id: "ImageHeader", src: 'spinner.gif' });
</script>

Image.getUrl(callback(err, url))

Gets the URL for the image requested.

Callback Arguments
Name Description
err error associated with the image request, if any.
url URL of the generated image.
Returns

An Image object

Example
1
2
3
4
5
6
7

<script>
cartodb.Image(vizjson_url)
  .size(600, 400)
  .getUrl(function(err, url) {
    console.log('image url',url);
  })
</script>

Image.format(format)

Gets the URL for the image requested.

Arguments
Name Description
format image format of resulting image. One of png (default) or jpg (which have a quality of 85 dpi)
Returns

An Image object