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.
The following MapConfig Layergroup configurations are applied using the RFC 4627 JSON format.
Layergroup Configuration | Description | Optional or Required? |
---|---|---|
version |
Spec version to use for validation. Note: The default value is "1.0.0" . |
Optional |
extent |
The default map extent for the map projection. Note: Currently, only webmercator is supported. |
Optional |
srid |
The spatial reference identifier for the map. The default is 3857 . |
Optional |
maxzoom |
The maximum zoom level for your map. A request beyond the defined maxzoom returns a 404 error. Note: The default value is undefined (infinite). |
Optional |
minzoom |
The minimum zoom level for your map. A request beyond the defined minzoom returns a 404 error. Note: The default value is 0 . |
Optional |
layers |
Defines the layer type, and the layers, in rendering order. Note: The following layers options are available: |
|
type | A string value that defines the layer type. You can define up to four values:mapnik , rasterized tilescartodb , an alias for mapnik (for backward compatibility)torque , render vector tiles in torque formathttp , load tiles over HTTPplain , color or background image urlnamed , use a Named Map as a layer |
Required |
options | An object value that sets different options for each layer type. Note: Options that are not defined in different layers will be discarded. |
Required |
If you are using Mapnik as a layer resource, the following configurations are required in your MapConfig file.
Mapnik Layer Option | Description | Optional or Required? |
---|---|---|
sql |
A string value, the SQL request to the user database that will fetch the rendered data. Tip: The SQL request should include the following Mapnik layer configurations: geom_column , interactivity , and attributes , as described in this section.Note: The SQL request may contain substitutions tokens, such as !bbox! , !pixel_width! , and !pixel_height! . It is suggested to define the layergroup minzoom and extent variables to prevent errors. |
Required |
cartocss |
A string value, specifying the CartoCSS style to render the tiles. If this is not present, only vector tiles can be requested for this layer. For a map to be valid either all the layers or none of them must have CartoCSS style. Note: The CartoCSS specification is dependent on the layer type. For details, see mapnik-reference.json. |
Optional |
cartocss_version |
A string value, specifying the CartoCSS style version of the CartoCSS attribute. Note: The CartoCSS version is specific to the layer type. |
Optional |
geom_column |
The name of the column containing the geometry. The default is the_geom_webmercator .*You must specify this value as part of the Mapnik layer SQL configuration. |
*Optional |
geom_type |
Defines the type of column as either geometry (the default) or raster .Note: geom_type is not compatible with the Mapnik layer interactivity option. |
Optional |
raster_band |
Defines the raster band (this option is only applicable when the geom_type=raster . The default value is 0 .Note: If the default, or no value is specified, raster bands are interpreted as either: grayscale (for single bands), RGB (for 3 bands), or RGBA (for 4 bands). |
Optional |
srid |
The spatial reference identifier for the geometry column. The default is 3857 . |
Optional |
affected_tables |
A string of values containing the tables that the Mapnik layer SQL configuration is using. This value is used if there is a problem guessing what the affected tables are from the SQL configuration (i.e. when using PL/SQL functions). |
Optional |
interactivity |
A string of values that contains the fields rendered inside grid.json. All the parameters should be exposed as a result of executing the Mapnik layer SQL query.Note: interactivity is not compatible with the Mapnik layer geom_type option. For example, you cannot create a layergroup instance with a raster layer by defining the geom_type=raster .*You must specify this value as part of the Mapnik layer SQL configuration. |
*Optional |
attributes |
The id and column values returned by the Mapnik attributes service. (This option is disabled if no configuration is defined). *You must specify this value as part of the Mapnik layer SQL configuration. |
*Optional |
id | The key value used to fetch columns. | Required |
columns | A string of values (columns) returned by the Mapnik attribute service. | Required |
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.
Torque Layer Option | Description | Optional or Required? |
---|---|---|
sql |
A string value, the SQL request to the user database that will fetch the rendered data. Tip: The SQL request should include the following Torque layer configurations: geom_column , interactivity , and attributes , as described in this section. |
Required |
cartocss |
A string value, specifying the CartoCSS style to render the tiles. Note: The CartoCSS specification is dependent on the layer type. For details, see Torque cartocss-reference.js. |
Required |
cartocss_version |
A string value, specifying the CartoCSS style version of the CartoCSS attribute. Note: The CartoCSS version is specific to the layer type. |
Required |
step |
The number of animation steps to render when requesting a torque.png tile. The default value is 0 . |
Optional |
geom_column |
The name of the column containing the geometry. The default is the_geom_webmercator .*You must specify this value as part of the Torque layer SQL configuration. |
*Optional |
srid |
The spatial reference identifier for the geometry column. The default is 3857 . |
Optional |
affected_tables |
A string of values containing the tables that the Mapnik layer SQL configuration is using. This value is used if there is a problem guessing what the affected tables are from the SQL configuration (i.e. when using PL/SQL functions). |
Optional |
attributes |
The id and column values returned by the Torque attributes service. (This option is disabled if no configuration is defined). *You must specify this value as part of the Torque layer SQL configuration. |
*Optional |
id | The key value used to fetch columns. | Required |
columns | A string of values (columns) returned by the Torque attribute service. | Required |
If you are using an HTTP destination as the resource for a map layer, the following configurations are required in your MapConfig file.
HTTP Layer Option | Description | Optional or Required? |
---|---|---|
urlTemplate |
A string value, end URL, from where the tile data is retrieved. URLs must be included in the configuration whitelist to be valid. Note: The {String} value includes: {z} as the zoom level{x} and {y} as the tile coordinatesOptionally, the subdomain {s} may be included as part of the urlTemplate configuration. Otherwise, you can define the subdomains separately, as shown below. |
Required |
subdomains |
A string of values used to retrieve tiles from different subdomains. The default value is [a , b , c ] when {s} is defined in the urlTemplate configuration. Otherwise, the default value is [ ] .Note: The subdomains value will consistently replace the {s} value defined in the urlTemplate . |
Optional |
tms |
A boolean value that specifies whether the tile is using Tile Map Service format. The default value is false .Note: If the value is true , the TMS inverses the Y axis numbering for tiles. |
Optional |
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.
Plain Layer Option | Description | Optional or Required? |
---|---|---|
color |
A string value of numbers that defines the valid colors to include. The default value is null . Valid colors include:- A string value that includes CSS colors (i.e. blue ) or a hex color string (i.e. #0000ff )- An integer array of r,g,b values (i.e. [255,0,0] )- An integer array of r,g,b,a values (i.e. [255,0,0,128] )* If only the color value is used for a plain layer, this value is Required.* If both color and imageUrl are defined, only the color value is used for the plain layer configuration. |
*Both |
imageUrl |
A string value, end URL, from where the image is retrieved. The default value is null .* If only the imageUrl value is used for a plain layer, this value is Required.* If color is defined, this imageUrl value is ignored. |
*Both |
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:
named
type layers inside of your template layergroup’s layers definitionnamed
layer does not allow Named Maps from other accounts. You can only use Named Maps from the same user accountIf you are using named
layer options as your map resource, the following configurations are required in your MapConfig file.
Named Layer Option | Description | Optional or Required? |
---|---|---|
name |
A string value, the name for the Named Map to use. | Required |
config |
An object, the replacement values for the Named Map’s template placeholders. | Optional |
auth_tokens |
Strings array, the authorized tokens in case the Named Map has auth method set to token . |
Optional |
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:
Parameter | Description | Default value |
placement |
Determines the kind of aggregated geometry generated (“point-sample”, “point-grind” or “centroid”). | “centroid” |
columns |
Defines aggregated columns; each one by an “aggregate_function” (“sum”, “avg”, “min, “max”, “mode”, “count”) and “aggregated_column” name. | |
resolution |
Defines the cell-size of the spatial aggregation grid. | 1 (for 256x256 cells per tile) |
threshold |
Minimum rows in the dataset to apply aggregation. |
All of these are MapConfig requirements for Anonymous Maps.
Identified by {z}/{x}/{y}
path
If applicable, additionally identified by LAYER_NUMBER
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.