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

Core API Functionality

In case you are not using Leaflet, or you want to implement your own layer object, CARTO provides a way to get the tiles url for a layer definition.

If you want to use this functionality, you only need to load cartodb.core.js from our cdn. No CSS is needed:

1
<script src="http://libs.cartocdn.com/cartodb.js/v3/3.15/cartodb.core.js"></script>

An example using this functionality can be found in a ModestMaps example: view live / source code.

Notice that cartodb.SQL is also included in that JavaScript file


cartodb.Tiles

cartodb.Tiles.getTiles(layerOptions, callback)

Fetch the tile template for the layer definition.

Arguments
Name Description
layerOptions the data that defines the layer. It should contain at least user_name and sublayers list.
options  
|_ user_name  
|_ sublayers  
|_ maps_api_template  
callback(tilesUrl, error) a function that recieves the tiles templates. In case of an error, the first param is null and the second one will be an object with an errors attribute that contains the list of errors.
Example

In this example, a layer with one sublayer is created. The sublayer renders all the content from a table.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var layerData = {
  user_name: 'username',
  sublayers: [{
    sql: "SELECT * FROM table_name";
    cartocss: '#layer { marker-fill: #F0F0F0; }'
  }],
  maps_api_template: 'https://{username}.carto.com' // Optional
};
cartodb.Tiles.getTiles(layerData, function(tilesUrl, error) {
  if (tilesUrl == null) {
    console.log("error: ", error.errors.join('\n'));
    return;
  }
  console.log("url template is ", tilesUrl.tiles[0]);
}

The tilesUrl object contains url template for tiles and interactivity grids:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  tiles: [
    "http://{s}.carto.com/HASH/{z}/{x}/{y}.png",
    ...
  ],
  grids: [
    // for each sublayer there is one entry on this array
    [
      "http://{s}.carto.com/HASH/0/{z}/{x}/{y}.grid.json"
    ],
    [
      "http://{s}.carto.com/HASH/1/{z}/{x}/{y}.grid.json"
    ],
    ...
  ]
}