Maps API

Create map layers from queries, tables and tilesets.

The Maps API turns a query, a table or a tileset into something a map can render. It returns metadata plus URLs for fetching the data — as tiles, GeoJSON, NDJSON or binary — and picks the formats that make sense for the size of the source.

You usually don't call this API directly.

CARTO + deck.gl calls it for you through data sources — vectorTableSource, h3QuerySource, rasterSource and the rest — which handle format selection, tiling, caching and authentication.

Start with Visualize your first dataset if you are building a map. Reach for these endpoints directly only when your client can't use our libraries.

Endpoint	What it does
GET /v3/maps/{connectionName}/query	Get a map layer from a query
GET /v3/maps/{connectionName}/table	Get a map layer from a table
GET /v3/maps/{connectionName}/tileset	Get a TileJSON from a tileset

Choosing an endpoint

You have	Use	Notes
A SQL query	/query	Cached for 1 year. Supports parameterized queries
A table	/table	Formats depend on table size — large tables only offer tiles
A tileset	/tileset	Returns TileJSON. Best performance for large data

Caching

Requests time out after 1 minute. Responses are cached in CARTO's CDN — send Cache-Control: max-age=<seconds> to lower the maximum age, with a minimum of 10 seconds.

Endpoint	Default cache
/query	1 year, all providers
/table	5 minutes on BigQuery, CARTO Data Warehouse and Snowflake; 30 minutes on Redshift, Databricks and PostgreSQL
/tileset	1 year, all providers

Spatial columns

From v=3.3, spatialDataColumn and spatialDataType replace geo_column, which returns 400 on newer versions. spatialDataType is one of geo, h3, h3int or quadbin.

About queryParameters and parameterized queries

CARTO uses the native mechanisms available in each data warehouse to build parameterized queries, which prevents any SQL injection.

Therefore, to specify the parameters in the query and the expected syntax for queryParameters , you will need to use the specific providers' syntax:

BigQuery

BigQuery uses named parameters.

sqlQuery: 'SELECT * FROM carto-demo-data.demo_tables.retail_stores WHERE storetype = @type AND revenue > @minRevenue'
queryParameters: { 'minRevenue': 100000, 'type': 'Supermarket' },

Please note that empty arrays are not supported as parameter values.

Snowflake

Snowflake supports positional parameters, such as:

sqlQuery: 'SELECT * FROM demo_db.public.import_retail_stores WHERE storetype = :2 AND revenue > :1'
queryParameters: [100000, "Supermarket"],

Redshift and PostgreSQL

Snowflake supports positional parameters, such as:

sqlQuery: 'SELECT * FROM carto_demo_data.demo_tables.retail_stores WHERE storetype = $2 AND revenue > $1...'
queryParameters: [100000, "Supermarket"],

Endpoints

Get a map layer from a query

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/maps/{connectionName}/query

Returns metadata and URLs to fetch a map layer built from a SQL query.

Omit format to get the full response with a URL per available format. Pass format to get that single format directly.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionNamestringRequired

Name of the connection to use.

Example: carto_dw

Query parameters

qstringRequired

The SQL query, or the name of a named source.

Example: SELECT * FROM carto-demo-data.demo_tables.airports

queryParametersstringOptional

Values for the parameters in the query, as a JSON string. Named object on BigQuery, positional array on Snowflake, Redshift and PostgreSQL.

Example: {"minRevenue": 100000, "type": "Supermarket"}

spatialDataColumnstringOptional

Column holding the geometry or spatial index. Defaults to geom. Required from v=3.3 onwards.

spatialDataTypestring · enumOptional

Type of the spatial column. Defaults to geo. Required from v=3.3 onwards.

Possible values:

geo_columnstringOptionalDeprecated

Legacy way to select the geometry column, in the form [spatialIndexType:]columnName. Use spatialDataColumn and spatialDataType instead — from v=3.3 this parameter returns 400.

columnsstringOptional

Comma-separated list of columns to return.

Example: name,geom

formatstring · enumOptional

Return a single format instead of the full response. Omit to get URLs for every available format.

Possible values:

tileResolutionnumber · enumOptional

Resolution of the generated tiles.

Possible values:

aggregationExpstringOptional

Aggregation expression applied when building spatial index tiles, for example SUM(population) as population.

aggregationResLevelintegerOptional

Resolution level for spatial index aggregation. Requires aggregationExp. Defaults to 6 for quadbin and 4 for H3.

vstring · enumOptional

API version. From 3.3, spatialDataColumn and spatialDataType replace geo_column.

Default: 3.0Possible values:

Responses

200

Map layer metadata and download URLs.

application/json

Metadata and download URLs for a map layer. Which format keys are present depends on the size of the source — large sources only offer tilejson.

sizeintegerOptional

Size of the source in bytes.

nrowsintegerOptional

Number of rows in the source.

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

422

The query can't be served for this connection — for example a Databricks connection with spatialDataType=geo.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/maps/{connectionName}/query

HTTPcURLJavaScriptPython

GET /v3/maps/{connectionName}/query?q=text HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ndjson": {
    "url": [
      "https://gcp-us-east1.api.carto.com/v3/maps/carto_dw/query?format=ndjson&q=SELECT%20*%20FROM%20carto-demo-data.demo_tables.airports&v=3.0"
    ]
  },
  "geojson": {
    "url": [
      "https://gcp-us-east1.api.carto.com/v3/maps/carto_dw/query?format=geojson&q=SELECT%20*%20FROM%20carto-demo-data.demo_tables.airports&v=3.0"
    ]
  },
  "tilejson": {
    "url": [
      "https://gcp-us-east1.api.carto.com/v3/maps/carto_dw/query?format=tilejson&q=SELECT%20*%20FROM%20carto-demo-data.demo_tables.airports&v=3.0"
    ]
  },
  "schema": [
    {
      "name": "geom",
      "type": "geometry"
    },
    {
      "name": "name",
      "type": "string"
    }
  ]
}

Get a map layer from a table

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/maps/{connectionName}/table

Returns metadata and URLs to fetch a map layer built from a table.

A tilejson URL is always included. Other formats are included depending on the size of the table — large tables only offer tiles.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionNamestringRequired

Name of the connection to use.

Example: carto_dw

Query parameters

namestringRequired

Fully qualified table name.

Example: carto-demo-data.demo_tables.airports

spatialDataColumnstringOptional

Column holding the geometry or spatial index. Defaults to geom. Required from v=3.3 onwards.

spatialDataTypestring · enumOptional

Type of the spatial column. Defaults to geo. Required from v=3.3 onwards.

Possible values:

geo_columnstringOptionalDeprecated

Legacy way to select the geometry column, in the form [spatialIndexType:]columnName. Use spatialDataColumn and spatialDataType instead — from v=3.3 this parameter returns 400.

columnsstringOptional

Comma-separated list of columns to return.

Example: name,geom

formatstring · enumOptional

Return a single format instead of the full response.

Possible values:

tileResolutionnumber · enumOptional

Resolution of the generated tiles.

Possible values:

vstring · enumOptional

API version. From 3.3, spatialDataColumn and spatialDataType replace geo_column.

Default: 3.0Possible values:

Responses

200

Map layer metadata and download URLs.

application/json

Metadata and download URLs for a map layer. Which format keys are present depends on the size of the source — large sources only offer tilejson.

sizeintegerOptional

Size of the source in bytes.

nrowsintegerOptional

Number of rows in the source.

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

406

No column matches the expected spatial data type. The response body includes the table schema so you can pick the right column.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/maps/{connectionName}/table

HTTPcURLJavaScriptPython

GET /v3/maps/{connectionName}/table?name=text HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "size": 70307,
  "nrows": 1000,
  "ndjson": {
    "url": [
      "https://gcp-us-east1.api.carto.com/v3/maps/carto_dw/table?format=ndjson&name=carto-demo-data.demo_tables.airports&v=3.0"
    ]
  },
  "tilejson": {
    "url": [
      "https://gcp-us-east1.api.carto.com/v3/maps/carto_dw/table?format=tilejson&name=carto-demo-data.demo_tables.airports&v=3.0"
    ]
  },
  "schema": [
    {
      "name": "geom",
      "type": "geometry"
    },
    {
      "name": "name",
      "type": "string"
    }
  ]
}

Get a TileJSON from a tileset

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/maps/{connectionName}/tileset

Returns the TileJSON for a tileset in your data warehouse. Learn more about tileset generation.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionNamestringRequired

Name of the connection to use.

Example: carto_dw

Query parameters

namestringRequired

Fully qualified tileset name.

Example: carto-demo-data.demo_tilesets.nasadem_glo_quadgrid15

formatstring · enumOptional

The only supported value is tilejson. Omit it to get the full response with tileset metadata.

Possible values:

vstring · enumOptional

API version. From 3.3, spatialDataColumn and spatialDataType replace geo_column.

Default: 3.0Possible values:

Responses

200

Tileset metadata, or the TileJSON when format=tilejson.

application/json

Metadata and download URLs for a map layer. Which format keys are present depends on the size of the source — large sources only offer tilejson.

sizeintegerOptional

Size of the source in bytes.

nrowsintegerOptional

Number of rows in the source.

204

The tileset returned no result.

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/maps/{connectionName}/tileset

HTTPcURLJavaScriptPython

GET /v3/maps/{connectionName}/tileset?name=text HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "size": 1,
  "nrows": 1,
  "ndjson": {
    "url": [
      "https://example.com"
    ],
    "error": "text"
  },
  "geojson": {
    "url": [
      "https://example.com"
    ],
    "error": "text"
  },
  "json": {
    "url": [
      "https://example.com"
    ],
    "error": "text"
  },
  "binary": {
    "url": [
      "https://example.com"
    ],
    "error": "text"
  },
  "tilejson": {
    "url": [
      "https://example.com"
    ],
    "error": "text"
  },
  "schema": [
    {
      "name": "text",
      "type": "number"
    }
  ]
}