---
title: "Create map"
method: POST
path: "/map"
tags: ["Anonymous Maps"]
---

# Create map

`POST /map`

## Request body

- MapConfig
  - `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```.

## Response `200`

Ok

- MapResponse
  - `layergroupid` string
  - `updated_at` string, date-time
  - `metadata` object
    - `layers` object[]
      - `type` 'mapnik' | 'cartodb' | 'torque' | 'http' | 'plain' | 'named' — 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
      - `meta` object
  - `cdn_url` object
    - `http` string
    - `https` string

## Other responses

- `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` — 2 info
  - added the non-success response with the status `429`
  - added the non-success response with the status `500`

[Change history](https://skmtc.dev/cartodb/apis/maps-api/changes/map/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)