---
title: "Upload template"
method: POST
path: "/map/named"
tags: ["Named Maps"]
---

# Upload template

`POST /map/named`

Upload template

## Request body

- Template
  - `version` string, required — Spec version to use for validation.
  - `name` string, required — There can only be one template with the same name for any user. Valid names start with a letter or a number, and only contain letters, numbers, dashes (-), or underscores (_)
  - `auth` object, required
    - `method` string — token or open
    - `valid_tokens` string — when method is set to token, the values listed here allow you to instantiate the Named Map. See this [example](http://docs.carto.com/faqs/manipulating-your-data/#how-to-create-a-password-protected-named-map) for how to create a password-protected map.
  - `placeholders` TemplatePlaceholders, required — Variables that can be placed in layergroup's definition (SQL or CartoCSS of any layer). Placeholders need to be defined with a `type` and a default value for MapConfigs. See details about defining a MapConfig `type` for [Layergroup configurations](https://carto.com/developers/maps-api/guides/MapConfig-file-format/#layergroup-configurations). Valid placeholder names start with a letter and can only contain letters, numbers, or underscores. They have to be written between the `<%=` and `%>` strings in order to be replaced inside the Named Maps API. **Example**:```<%= my_color %>``` The set of supported placeholders for a template need to be explicitly defined with a specific type, and default value, for each placeholder. Placeholder default values will be used whenever new values are not provided as options, at the time of creation on the client. They can also be used to test the template by creating a default version with new options provided. When using templates, be very careful about your selections as they can give broad access to your data if they are defined loosely.
    - `type` 'sql_literal' | 'sql_ident' | 'number' | 'css_color', required — sql_literal: internal single-quotes will be sql-escaped sql_ident: internal double-quotes will be sql-escaped number: can only contain numerical representation css_color: can only contain color names or hex-values
    - `default` union, required
      - string
      - number
      - boolean
  - `layergroup` MapConfig, required
    - `version` string — Spec version to use for validation.
    - `extent` string — The default map extent for the map projection. **Note:** Currently, only webmercator is supported.
    - `srid` string — The spatial reference identifier for the map.
    - `maxzoom` string — The maximum zoom level for your map. A request beyond the defined maxzoom returns a 404 error.
    - `minzoom` string — The minimum zoom level for your map. A request beyond the defined minzoom returns a 404 error.
    - `layers` Layer[], required
      - `type` 'mapnik' | 'cartodb' | 'torque' | 'http' | 'plain' | 'named', required — A string value that defines the layer type: * **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
      - `options` union, required — Sets different options for each layer type.
        - LayerOptionsMapnik — If you are using Mapnik as a layer resource, the following configurations are required in your MapConfig file.
          - `sql` string, required — 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``` * ```attributes``` **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.
          - `cartocss` string, required — Specifies the CartoCSS style to render the tiles. **Note:** The CartoCSS specification is dependent on the layer type. For details, see mapnik-reference.json.
          - `cartocss_version` string, required — A string value, specifying the CartoCSS style version of the CartoCSS attribute. **Note:** The CartoCSS version is specific to the layer type.
          - `geom_column` string — The name of the column containing the geometry. *You **must** specify this value as part of the Mapnik layer SQLconfiguration.
          - `geom_type` 'geometry' | 'raster' — Defines the type of column as either _geometry_ or _raster_. **Note:** ```geom_type``` is not compatible with the Mapnik layer interactivity option.
          - `raster_band` string — Defines the raster band (this option is only applicable when the ```geom_type=raster```. **Note:** If the default, or no value is specified, raster bands are interpreted as either: * grayscale (for single bands) * RGB (for 3 bands) * RGBA (for 4 bands).
          - `srid` string — The spatial reference identifier for the geometry column.
          - `affected_tables` string — 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).
          - `interactivity` string — 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.
          - `attributes` object[] — 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.
            - `id` string, required — The key value used to fetch columns.
            - `columns` string, required — A string of values (columns) returned by the Mapnik attribute service.
        - LayerOptionsTorque — 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.
          - `sql` string, required — 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 * attributes
          - `cartocss` string, required — Specifies the CartoCSS style to render the tiles. **Note:** The CartoCSS specification is dependent on the layer type. For details, see mapnik-reference.json.
          - `cartocss_version` string, required — A string value, specifying the CartoCSS style version of the CartoCSS attribute. **Note:** The CartoCSS version is specific to the layer type.
          - `step` integer — The number of animation steps to render when requesting a torque.png tile.
          - `geom_column` string — The name of the column containing the geometry. *You **must** specify this value as part of the Torque layer SQLconfiguration.
          - `srid` string — The spatial reference identifier for the geometry column.
          - `affected_tables` string — 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).
          - `attributes` object[] — 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.
            - `id` string, required — The key value used to fetch columns.
            - `columns` string, required — A string of values (columns) returned by the Torque attribute service.
        - LayerOptionsHTTP
          - `urlTemplate` string, required — URL from where the tile data is retrieved. _URLs must be included in the configuration whitelist to be valid._ **Note:** It 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.
          - `subdomains` string — 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```.
          - `tms` boolean — Specifies whether the tile is using Tile Map Service format **Note:** If the value is ```true```, the TMS inverses the Y axis numbering for tiles.
          - `tms2` boolean — Specifies whether the tile is using Tile Map Service format **Note:** If the value is ```true```, the TMS inverses the Y axis numbering for tiles.
        - LayerOptionsPlain
          - `color` string — Numbers that define the valid colors to include. Valid colors: - 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.
          - `imageUrl` string — URL from where the image is retrieved * If **only** the ```imageUrl``` value is used for a plain layer, this value is Required. * If ```color``` is defined, this ```imageUrl``` value is ignored.
        - LayerOptionsNamedMap
          - `name` string, required — A string value, the name for the Named Map to use.
          - `config` object — An object, the replacement values for the Named Map’s template placeholders.
          - `auth_tokens` string[] — Strings array, the authorized tokens in case the Named Map has auth method set to ```token```.
  - `view` TemplateView — Extra keys to specify the view area for the map. It can be used to have a static preview of a Named Map without having to instantiate it. It is possible to specify it with `center` + `zoom` or with a bounding box `bbox`. Center+zoom takes precedence over bounding box. Also it is possible to choose which layers are visible or not with `preview_layers` indicating its visibility by layer index or id (visible by default).
    - `zoom` number, required — The zoom level to use
    - `center` TemplateViewCenter, required
      - `lng` number — The longitude to use for the center
      - `lat` number — The latitude to use for the center
    - `bounds` TemplateViewBounds, required — View area for the map. It can be used to have a static preview with bounding box `bbox
      - `west` number — LowerCorner longitude for the bounding box, in decimal degrees (aka most western)
      - `south` number — LowerCorner latitude for the bounding box, in decimal degrees (aka most southern)
      - `east` number — UpperCorner longitude for the bounding box, in decimal degrees (aka most eastern)
      - `north` number — UpperCorner latitude for the bounding box, in decimal degrees (aka most northern)
    - `preview_layers` TemplateViewPreviewLayers — Indicates which layers are visible or not by layer index or id (visible by default).

## Response `200`

Ok

- NamedMapResponse
  - `template_id` string

## Other responses

- `400` — The server could not understand the request due to invalid syntax or unexpected condition.
- `401` — Unauthorized. No authentication provided.
- `403` — Forbidden. The API key does not authorize this request.
- `429` — The user has sent too many requests in a given amount of time ("rate limiting" or "database timeout").
- `500` — Server encountered an unexpected condition that prevented it from fulfilling the request.

## Changes

- **2019-02-07** `86f957fde710` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/cartodb/apis/maps-api/changes/map/named/post.md)

---

[API](https://skmtc.dev/cartodb/apis/maps-api.md) · [All operations](https://skmtc.dev/cartodb/apis/maps-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cartodb/maps-api/revisions/35d2b59fee9e/schema)