Windshaft-cartodb/docs/quickstart.md

Quickstart

Anonymous maps

Here is an example of how to create an anonymous map with JavaScript:

var mapconfig = {
  "version": "1.3.1",
  "layers": [{
    "type": "cartodb",
    "options": {
      "cartocss_version": "2.1.1",
      "cartocss": "#layer { polygon-fill: #FFF; }",
      "sql": "select * from european_countries_e"
    }
  }]
}

$.ajax({
  crossOrigin: true,
  type: 'POST',
  dataType: 'json',
  contentType: 'application/json',
  url: 'https://documentation.cartodb.com/api/v1/map',
  data: JSON.stringify(mapconfig),
  success: function(data) {
    var templateUrl = 'https://documentation.cartodb.com/api/v1/map/' + data.layergroupid + '/{z}/{x}/{y}.png'
    console.log(templateUrl);
  }
})

Named maps

Let's create a named map using some private tables in a CartoDB account. The following map config sets up a map of European countries that have a white fill color:

{
  "version": "0.0.1",
  "name": "test",
  "auth": {
    "method": "open"
  },
  "layergroup": {
    "layers": [{
      "type": "mapnik",
      "options": {
        "cartocss_version": "2.1.1",
        "cartocss": "#layer { polygon-fill: #FFF; }",
        "sql": "select * from european_countries_e"
      }
    }]
  }
}

The map config needs to be sent to CartoDB's Map API using an authenticated call. Here we will use a command line tool called curl. For more info about this tool, see this blog post, or type man curl in bash. Using curl, and storing the config from above in a file mapconfig.json, the call would look like:

Call

curl 'https://{account}.cartodb.com/api/v1/map/named?api_key=APIKEY' -H 'Content-Type: application/json' -d @mapconfig.json

To get the URL to fetch the tiles you need to instantiate the map, where template_id is the template name from the previous response.

Call

curl -X POST 'https://{account}.cartodb.com/api/v1/map/named/:template_id' -H 'Content-Type: application/json'

The response will return JSON with properties for the layergroupid, the timestamp (last_updated) of the last data modification and some key/value pairs with metadata for the layers.

Note: all layers in metadata will always have a type string and a meta dictionary with the key/value pairs.

Response

{
  "layergroupid": "c01a54877c62831bb51720263f91fb33:0",
  "last_updated": "1970-01-01T00:00:00.000Z",
  "metadata": {
    "layers": [
      {
        "type": "mapnik",
        "meta": {}
      }
    ]
  }
}

You can use the layergroupid to instantiate a URL template for accessing tiles on the client. Here we use the layergroupid from the example response above in this URL template:

https://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/{z}/{x}/{y}.png