> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-developers/reference/carto-api/maps-api.md).

# Maps API

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.

{% hint style="warning" %}
**You usually don't call this API directly.**

[CARTO + deck.gl](/carto-for-developers/key-concepts/carto-for-deck.gl.md) calls it for you through [data sources](/carto-for-developers/reference/data-sources.md) — `vectorTableSource`, `h3QuerySource`, `rasterSource` and the rest — which handle format selection, tiling, caching and authentication.

Start with [Visualize your first dataset](/carto-for-developers/quickstart/visualize-your-first-dataset.md) if you are building a map. Reach for these endpoints directly only when your client can't use our libraries.
{% endhint %}

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

{% hint style="success" %}

## **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.

{% code overflow="wrap" %}

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

{% endcode %}

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

**Snowflake**

Snowflake supports positional parameters, such as:

{% code overflow="wrap" %}

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

{% endcode %}

**Redshift and PostgreSQL**

Snowflake supports positional parameters, such as:

{% code overflow="wrap" %}

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

{% endcode %}
{% endhint %}

## Endpoints

{% openapi src="<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>" path="/v3/maps/{connectionName}/query" method="get" %}
<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>
{% endopenapi %}

{% openapi src="<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>" path="/v3/maps/{connectionName}/table" method="get" %}
<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>
{% endopenapi %}

{% openapi src="<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>" path="/v3/maps/{connectionName}/tileset" method="get" %}
<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>
{% endopenapi %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-for-developers/reference/carto-api/maps-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.