Maps API v2

MapConfig File Format

CARTO uses Windshaft as the map tiler library to render multilayer maps with the Maps API. The MapConfig file is where these Windshaft layers are stored and applied. You can configure tiles and use the MapConfig document to request different resources for your map.

This section describes the MapConfig specifications, and required formats, when using the Maps API.

Layergroup Configurations

The following MapConfig Layergroup configurations are applied using the RFC 4627 JSON format.

Example of MapConfig

{
    "version": "1.7.0",
    "extent": [-20037508.5, -20037508.5, 20037508.5, 20037508.5],
    "srid": 3857,
    "maxzoom": 18,
    "minzoom": 3,
    "layers": [
        {
            "type": "mapnik",
            "options": {
                "sql": "select * from table",
                "cartocss": "#table { marker-placement: point; }",
                "cartocss_version": "2.3.0"
            }
        }
    ]
}

Mapnik Layer Options

If you are using Mapnik as a layer resource, the following configurations are required in your MapConfig file.

Example of Mapnik MapConfig

{
    "type": "mapnik",
    "options": {
        "sql": "select * from table",
        "cartocss": "#layer { marker-placement: point; }",
        "cartocss_version": "2.3.0",
        "geom_column": "the_geom_webmercator",
        "geom_type": "geometry",
        "interactivity": [ "column1", "column2", "..."],
        "attributes": {
            "id": "cartodb_id",
            "columns": ["column1", "column2"]
        }
    }
}

Torque Layer Options

If you are using Torque as a layer resource, the following configurations are required in your MapConfig file. For more details about Torque layers in general, see the Torque API documentation.

Example of Torque MapConfig

{
    "type": "torque",
    "options": {
        "sql": "select * from table",
        "cartocss": "#layer { ... }",
        "cartocss_version": "1.0.0",
        "geom_column": "the_geom_webmercator"
    }
}

HTTP Layer Options

If you are using an HTTP destination as the resource for a map layer, the following configurations are required in your MapConfig file.

Example of HTTP MapConfig

{
    "type": "http",
    "options": {
        "urlTemplate": "http://{s}.example.com/{z}/{x}/{y}.png",
        "subdomains": ["a", "b", "c"],
        "tms": false
    }
}

Plain Layer Options

If you are using plain layer options as your map resource, the following configurations are required in your MapConfig file.

Note: At least one of the plain layer options (either color or imageUrl) must be defined. If both options are defined, only color is used as part of the plain layer configuration.

Example of Plain MapConfig

{
    "type": "plain",
    "options": {
        "color": "blue",
        "imageUrl": "http://example.com/background.png"
    }
}

Named Map Layer Options

You can use a Named Map as a map layer. Note the following limitations before referencing the MapConfig options for a Named Map layer.

Limitations:

• A Named Map will not allow you to have named type layers inside of your template layergroup’s layers definition
• A named layer does not allow Named Maps from other accounts. You can only use Named Maps from the same user account

If you are using named layer options as your map resource, the following configurations are required in your MapConfig file.

Example of Named MapConfig

{
    "type": "named",
    "options": {
        "name": "world_borders",
        "config": {
            "color": "#000"
        },
        "auth_tokens": ["token1", "token2"]
    }
}

Aggregation Options

The data used to render tiles, or contained in the tiles (for the case of vector tiles), can be spatially aggregated under some circumstances.

An aggregation attribute can be used in the layer options to control the aggregation. A value of false will disable aggregation for the layer. Otherwise, an object can be passed with the following aggregation parameters:

Example of Aggregation MapConfig

{
    "version": "1.7.0",
    "extent": [-20037508.5, -20037508.5, 20037508.5, 20037508.5],
    "srid": 3857,
    "maxzoom": 18,
    "minzoom": 3,
    "layers": [
        {
            "type": "mapnik",
            "options": {
                "sql": "select * from table",
                "cartocss": "#table { marker-width: [total]; marker-fill: ramp(value, (red, green, blue), jenks); }",
                "cartocss_version": "2.3.0",
                "aggregation": {
                    "placement": "centroid",s
                    "columns": {
                        "value": {
                            "aggregate_function": "avg",
                            "aggregated_column": "value"
                        },
                        "total": {
                            "aggregate_function": "sum",
                            "aggregated_column": "value"
                        }
                    },
                    "resolution": 2, // Aggregation cell is 2x2 pixels
                    "threshold": 500000
                }
            }
        }
    ]
}

MapConfig Requirements

All of these are MapConfig requirements for Anonymous Maps.

• Identified by {z}/{x}/{y} path

• If applicable, additionally identified by LAYER_NUMBER

• Can be of different formats:
  • png
  • grid.json
  • torque.json
• Static images/previews
  • With a center or a bounding box
• Attributes -Identified by LAYER_NUMBER and FEATURE_ID

Tip: The MapConfig file may be extended for specific uses. For example, Windshaft-CartoDB defines the addition of a stat_tag element in the config. This extension is also covered as part of the Named Map Layer Options.