Your search returned no results

Try another search term or view Stack Exchange, where we have active conversations with Developers about GIS.

    http://gis.stackexchange.com/
    Support channel in Stack Exchange

    Thousands of developers around the world have helped make CartoDB a success, and we have active conversations with them about GIS in Stack Exchange.

    Go to Stack Exchange

    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.

    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 tiles

    cartodb, an alias for mapnik (for backward compatibility)

    torque, render vector tiles in torque format

    http, load tiles over HTTP

    plain, color or background image url

    named, 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

    Example of MapConfig

    {
        "version": "1.4.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.

    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.

    Note: The CartoCSS specification is dependent on the layer type. For details, see mapnik-reference.json.
    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
    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 SQLconfiguration.
    *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 SQLconfiguration.
    *Optional
    id The key value used to fetch columns. Required
    columns A string of values (columns) returned by the Mapnik attribute service. Required

    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.

    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 SQLconfiguration.
    *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 SQLconfiguration.
    *Optional
    id The key value used to fetch columns. Required
    columns A string of values (columns) returned by the Torque attribute service. Required

    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.

    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 coordinates

    Optionally, 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

    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.

    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

    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.

    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

    Example of Named MapConfig

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

    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.