CartoDB Map API

This document describes the way our Static Map API should be used from cartodb.js:

Quick start

Say you want to include a preview of a map in your cool cartography blog. You'd just need to do:

<script>
cartodb.Image(vizjson_url, {override_bbox: true})
  .size(600, 400)
  .center([-3.4, 44.2])
  .zoom(10)
  .write();
</script>

This will generate a <img> tag like:

<img src="http://user.cartodb.com/api/v1/maps/....../whatever.png">

You can even specify the class name and/or the id the resulting image will have, or even put an animated gif to show while the image is loading!

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

But if you just need the URL of the image, guess what, you can get it easily too!

cartodb.Image(vizjson_url).size(400, 300).getUrl(function(err, url) {
    console.log(url);
});

That will print:

http://usercartodb.com/api/v1/maps/..../whatever.png

API

Image (vizjson_url || layerdefinition)

Returns an Image object. The constructor accepts both a viz.json url or a layer definition.

Image.size(width, height)

Sets the image size. The default image size is 320x240.

Image.center(latlng)

Set the center for the preview. If a vizjson URL is used and center is not set, the bounding box in the vizjson will be used instead.

Image.zoom(zoom)

Sets the zoom for the preview. If a vizjson URL is used and zoom is not set, the one in the vizjson will be used.

Image.bbox([sw_lat, sw_lon, ne_lat, ne_lon])

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

Image.into(HTMLImageElement)

Inserts the image in the HTMLImageElement specified:

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

It uses the HTMLImageElement width and height in case size is not called:

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:

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

You can also indicate the URL of an image that will be loaded while the image is being generated:

<script>
cartodb.Image(vizjson_url, {override_bbox: true})
  .size(600, 400)
  .center([-3.4, 44.2])
  .zoom(10)
  .write({ src: "spinner.gif" });
<script>

Image.getUrl(callback(err, url))

gets the url for the image, err is null is there was no error

Image.format(format)

Image format, png (default) and jpg available (jpgs will have a default quality of 85).

layerdefinition

Besides including an array of layers, it should include the username so we can build the right endpoint.

Using into to load images:

Define the image tags in your HTML:

<div id="dashboard">
  <img data-vizjson-url="VIZJSON_URL_0" width="400" height="300" class="thumb" />
  <img data-vizjson-url="VIZJSON_URL_1" width="400" height="300" class="thumb" />
</div>

And load the associated vizjson:

$('#dashboard .thumb').each(function() {
  new cartodb.Image($(this).data('vizjson-url')).into(this);
})

Options

Basemap

It's possible to use a different basemap with the basemap param.

cartodb.Image(vizjson_url, { basemap: basemap }).size(400, 300).getUrl(function(err, url) {
  // url
});

NO_CDN

By default, we use a CDN to serve the images. It's possible to disable setting the option 'no_cdn' to true.

cartodb.Image(vizjson_url, { no_cdn: true }).size(400, 300).getUrl(function(err, url) {
  // url
});

OVERRIDE_BBOX

By default, we use the bounding box of the visualization to center the map. It's possible to use the center instead setting the option 'override_bbox' to true.

cartodb.Image(vizjson_url, { override_bbox: true }).center([0,0]).zoom(4).size(400, 300).getUrl(function(err, url) {
  // url
});