Introduction

The CARTO Maps API allows you to generate maps based on data hosted in your CARTO account and apply custom SQL and CartoCSS to the data. The API generates a XYZ-based URL to fetch Web Mercator projected tiles using web clients such as Leaflet, Google Maps, or OpenLayers.

Authorization

In order to access Maps API you must provide an API key. The CARTO Authorization guide explains how these keys are sent (TLDR: HTTP basic auth or query string param with the API key token). Depending on the permissions granted to the provided API key, the request will be authorized or not.

Download OpenAPI specification Have you found an error? Github issues

Anonymous Maps

Anonymous Maps allow you to instantiate a map given SQL and CartoCSS

Create map

post /map

Production server (uses live data)

https://{user}.{domain}/api/v1/map

Bla Bla

Authorizations:

ApiKeyHTTPBasicAuth

ApiKeyQueryParam

Request Body schema: application/json

version	string Default: "1.0.0" Spec version to use for validation.
extent	string The default map extent for the map projection. Note: Currently, only webmercator is supported.
srid	string Default: 3857 The spatial reference identifier for the map.
maxzoom	string Default: "undefined (infinite)" 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 required	Array of object

Responses

200

401

Unauthorized. No authentication provided.

403

Forbidden. The API key does not authorize this request.

Request samples

Payload
Curl

application/json

{

"version": "1.3.0",
"layers":
[
- {
  - "type": "mapnik",
  - "options":
    {
    "cartocss_version": "2.1.1",
    "cartocss": "#layer { polygon-fill: #FFF; }",
    "sql": "select * from european_countries_e",
    "interactivity":
    [
    "cartodb_id",
    "iso3"
    ]
    }
  }
]

}

Click to Copy

Response samples

application/json

{

"layergroupid": "string",
"updated_at": "2023-03-10T08:06:08Z",
"metadata":
{
- "layers":
  [
  - {
    "type": "mapnik",
    "meta": { }
    }
  ]
},
"cdn_url":
{
- "http": "string",
- "https": "string"
}

}

Click to Copy

Get tile

get /map/{layergroupid}/{z}/{x}/{y}.png

Production server (uses live data)

https://{user}.{domain}/api/v1/map/{layergroupid}/{z}/{x}/{y}.png

Bla Bla

Authorizations:

ApiKeyHTTPBasicAuth

ApiKeyQueryParam

path Parameters

layergroupid required	string The layergroup ID.
z required	integer >= 0 Zoom level.
x required	integer >= 0 X coordinate.
y required	integer >= 0 Y coordinate.

Responses

200

401

Unauthorized. No authentication provided.

403

Forbidden. The API key does not authorize this request.

404

The specified resource was not found

Request samples

Curl

curl -X GET \
https://username.carto.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/2/3/4.png

Click to Copy

Get tile - Layer filter

get /map/{layergroupid}/{layers_filter}/{z}/{x}/{y}.png

Production server (uses live data)

https://{user}.{domain}/api/v1/map/{layergroupid}/{layers_filter}/{z}/{x}/{y}.png

Bla Bla

Authorizations:

ApiKeyHTTPBasicAuth

ApiKeyQueryParam

path Parameters

layergroupid required	string The layergroup ID.
layers_filter required	string or string Layers to be rendered together. Supports 2 format options: a comma separated list of layer indexes (0-based). Examples: 0,1,3 - will filter and blend layers with indexes 0, 1 and 3 2 - only one layer all will blend all layers in the layergroup
z required	integer >= 0 Zoom level.
x required	integer >= 0 X coordinate.
y required	integer >= 0 Y coordinate.

Responses

200

401

Unauthorized. No authentication provided.

403

Forbidden. The API key does not authorize this request.

404

The specified resource was not found

Request samples

Curl

curl -X GET \
https://username.carto.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/2/3/4.png

Click to Copy

Get Torque layer

get /map/{layergroupid}/{layer}/{z}/{x}/{y}.torque.json

Production server (uses live data)

https://{user}.{domain}/api/v1/map/{layergroupid}/{layer}/{z}/{x}/{y}.torque.json

If the MapConfig had a Torque layer it could be possible to request it

Authorizations:

ApiKeyHTTPBasicAuth

ApiKeyQueryParam

path Parameters

layergroupid required	string The layergroup ID.
layer required	number (layer index) >= 0 0 based layer index
z required	integer >= 0 Zoom level.
x required	integer >= 0 X coordinate.
y required	integer >= 0 Y coordinate.

Responses

200

401

Unauthorized. No authentication provided.

403

Forbidden. The API key does not authorize this request.

404

The specified resource was not found

Request samples

Curl

curl -X GET \
https://username.carto.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/2/3/4.png

Click to Copy

Response samples

application/json

{ }

Click to Copy

Named Maps

Run a single SQL statement

Static Maps

Run a single SQL statement