Getting started with CARTO

CARTO is the only cloud-first spatial platform built for accelerated, modern GIS. It runs natively on top of your cloud data warehouse platform (e.g. Google BigQuery, Snowflake, AWS Redshift, Databricks, Oracle, etc.), providing easy access to highly scalable spatial analysis and visualization capabilities in the cloud — be it for analytics, app development, data engineering, and more.

CARTO Platform

CARTO unlocks the power of spatial analysis in the cloud, extending the visualization, analysis and development capabilities of the leading cloud data warehouse platforms, such as Google BigQuery, Snowflake, Oracle, and Amazon Redshift.

Find out how to get the most out of our Location Intelligence platform with our product documentation:

CARTO for Agents

Data and Analysis

Development tools

Run SQL on your data warehouse using existing connections. Two modes: query returns result rows; job runs DDL/DML and polls to completion without returning a result set.

Run a SQL query and return results. Default behavior is POST (no caching, no URL length limit, 1-minute timeout).

Options:

Build AI-first spatial apps with CARTO Agentic Tools for developers

Mar 30th, 2026

New CARTO for Developers

Building AI-powered apps with geospatial capabilities just got a lot easier. We're releasing @carto/agentic-deckgl, an open-source TypeScript library built on CARTO + deck.gl that lets any AI Agent create and style map layers, run spatial analytics, and interact with the map through natural language — with one npm install. It's framework-agnostic, includes Zod-validated tool definitions, a geospatial system prompt builder, and SDK converters for major AI frameworks.

The library gives AI Agents full control over the map experience: creating and styling vector tile, H3, GeoJSON, and raster layers from any CARTO data source; navigating the globe with smooth transitions; switching basemaps; placing and managing markers; applying spatial filters from user-drawn areas or analytical workflows; and managing widgets, visual effects, and layer ordering.

Learn more about this new library in our .

Mar 30th, 2026

New Builder

Creating AI Agents just got significantly easier. The new Agent Configuration Assistant lets you design, set up, and iterate on your agents using natural language.

Instead of manually defining instructions, selecting tools, and configuring capabilities step by step, you can now simply describe what your agent should do. The Assistant generates a complete configuration for you — including the use case, structured instructions, model selection, tool setup, capabilities, and a tailored introduction message.

The Assistant is context-aware, meaning its recommendations are grounded in your actual map. It understands your datasets, layers, widgets, and available tools, helping you create more accurate and relevant agents from the start. You can refine any part of the configuration through conversation or combine it with manual edits for full control.

Mar 27th, 2026

New Workflows

Workflows can now be shared with Viewer Mode, allowing editors to publish interactive workflows that other users can run without editing the canvas. This opens up new possibilities for delivering analytical tools and reports to stakeholders and business users.

• Viewer parameters: Editors define which variables are exposed to viewers as configurable parameters, with custom display names and helper text. Supported types include Number, String, and the new Geo type, which lets viewers draw geographic features on a map.

• Viewer Result Output: A new component that defines which node's output is displayed to viewers, giving editors full control over what results are visible.

• Viewer settings: Granular controls over the viewer experience, including toggling the canvas visibility, SQL preview, data export, result caching, and more.

.

Mar 19th, 2026

Improvement CARTO platform

We've expanded the AI models available for AI Agents with the latest generation of Anthropic models.

• More CARTO-managed models: Claude Opus 4.6 and Claude Sonnet 4.6 are now available out of the box with no additional configuration.

• Broader bring-your-own-model support: You can now use Claude Opus 4.6 and Claude Sonnet 4.6 through any of our supported providers, including Vertex AI, AWS Bedrock, Azure OpenAI, Anthropic, Snowflake Cortex, and Databricks Serving Model.

The 4.6 models deliver better performance across reasoning, tool usage, and complex geospatial workflows.

Configure your models in Settings > CARTO AI — see the for the full list of supported models and providers.

February 17th, 2026

Improvement CARTO platform

We've expanded the AI models available for AI Agents with more advanced models from Anthropic, Google, and OpenAI.

• More CARTO-managed models: Claude Opus 4.5, Claude Sonnet 4.5, Gemini 3 Pro, and Gemini 3 Flash are now available out of the box with no additional configuration.

• Broader bring-your-own-model support: You can now use Gemini 3, Claude Opus 4.5, and GPT-5.2 through any of our supported providers, including Vertex AI, Google AI Studio, Snowflake Cortex, Databricks Serving Model, AWS Bedrock, Azure OpenAI, OpenAI, and Anthropic.

We recommend upgrading to the newest models available — you'll see a significant improvement in agent performance, reasoning, and tool usage.

Configure your models in Settings > CARTO AI — see the for the full list of supported models and providers.

February 9th, 2026

Improvement Builder

can now generate and render interactive charts directly inside the conversation. Users can ask for data visualizations and see charts rendered inline — no need to leave the chat.

Charts expand the way AI Agents can communicate insights, complementing map layers with statistical visualizations like bar charts for comparisons, line charts for trends, or histograms for distributions. Combined with other tools, AI Agents can query your data, analyze it, and present findings in the format that best fits the question.

.

January 29th, 2026

New CARTO platform

We're excited to announce the , which brings command line power to your CARTO organization. Manage Maps, Workflows, connections and credentials; transfer assets between organizations, and query your organization's activity data; all from the terminal!

The CLI supports structured JSON output, non-interactive execution, and headless authentication, making it a natural interface to script and automate. To get started, head over to our .

January 29th, 2026

Improvement Workspace

Public maps are the way to distribute geospatial data and insights across wider audiences outside your organization. From coverage maps to deforestation storytelling, many geospatial dashboards are making an impact on public websites thanks to CARTO.

Starting now, CARTO administrators can measure that impact, and answer questions like:

• How many times my public maps have been viewed

• Which are my most active public maps

• How many exports from public maps last month...

We've automatically added to our the data coming from your public maps thanks to a robust, secure, event pipeline that can track millions of events coming from unauthenticated users.

To get started, simply or .

January 20th, 2026

New CARTO platform

CARTO now supports seven additional AI providers, expanding the AI and LLM integrations available to power AI Agents.

Previously limited to OpenAI and Google AI Studio, you can now connect AI Agents to models hosted on your preferred cloud or data platform:

• Google Vertex AI: Enterprise GCP deployments with service account authentication.

• Amazon Bedrock: Claude models through AWS infrastructure.

• Snowflake Cortex: AI models within your Snowflake environment.

These new integrations allow AI Agents to run on your preferred cloud or data platform, leverage existing cloud contracts, meet data residency requirements, and access the latest large language models available from each provider.

Configure providers in Settings > CARTO AI. See the for setup instructions.

January 14th, 2026

Improvement Builder

When using CARTO Basemaps, labels (like city and street names) now automatically appear on top of your map layers instead of being hidden underneath them.

This makes it easier to read your maps, especially when working with multiple overlapping layers. You can still turn labels off in the basemap settings if you prefer a cleaner look.

January 12th, 2026

New Workflows, Analytics Toolbox

A new capability is now available for generating H3-based isochrones using , expanding how accessibility and travel-time analysis can be performed in CARTO.

This release introduces a new endpoint in the Location Data Services (LDS) API that leverages TravelTime’s H3 isochrone support. In addition, corresponding functions are available in the Analytics Toolbox (for , , and ), along with a new component in Workflows, enabling low-code and programmatic access to this functionality.

Customers can now generate H3-indexed isochrones directly, with support for the same configuration options provided by the underlying TravelTime API, including departure time and transport mode. Using H3 as the output format simplifies downstream analysis, aggregation, and visualization, particularly for workflows that already rely on hexagonal indexing.

January 7th, 2026

New CARTO Platform

A new type is now generally available across all CARTO accounts, delivering deeper and more modern support for Databricks as a data warehouse and compute platform.

This integration adopts Databricks SQL Warehouses as the sole compute resource, providing a serverless, cloud-native experience without the need to manage traditional compute clusters. It also leverages Databricks’ , including the GEOMETRY data type and Spatial SQL functions documented by Databricks, enabling efficient storage and processing of spatial data directly in SQL without external libraries.

Connectivity options include Personal Access Tokens (PAT), M2M, and U2M integrations, offering flexibility in how authentication and access are managed. Builder and Workflows fully support Databricks tables with geometry types out of the box, including query sources, SQL parameters, Location Data Services, and Create Builder Map workflows — no additional data preparation is required to work with spatial columns.

The now installs directly into the Databricks Unity Catalog with no external dependencies, simplifying governance and deployment. Older Databricks connection types remain available for existing accounts that used them previously. This release represents a significant step in CARTO’s support for major cloud data warehouse providers and extends CARTO’s capabilities for spatial analytics on modern data platforms.

Can I license premium data with a trial or student account?

Are premium data subscriptions based on perpetual licenses?

Can I export the data from CARTO and use it on other platforms?

Can I license premium data with a trial, or student account?

No, premium data subscriptions are only available for Enterprise plans. For Trial and Student plans, you will only have access to data samples or public data products from the Data Observatory.

Individual plans do not get access to the Data Observatory. If you need to use it, you would need to upgrade to a Starter plan, or get in touch with [email protected]

Are premium data subscriptions based on perpetual licenses?

Premium subscriptions are offered on a Data-as-a-Service model based on yearly or multi-yearly licenses. Once the subscription expires and it is not renewed, the user needs to stop using and delete the associated datasets from the account.

It will depend on the data provider and the type of license you have purchased for your premium data subscription. Some data providers offer different types of licenses if their data is going to be used only within a CARTO application or exported into other technologies.

What frameworks and libraries can I use for developing custom apps with CARTO?

Are “CARTO for deck.gl” and “CARTO for React” compatible with the new version of the platform?

What frameworks and libraries can I use for developing custom apps with CARTO?

You can use any framework or visualization library because CARTO is based on industry-standards. If there is not a hard requirement, we recommend using deck.gl for visualization and CARTO for React for creating apps that extend the platform functionality.

Are “CARTO for deck.gl” and “CARTO for React” compatible with the new version of the platform?

Yes, you can use both tools with the previous and the new version of the platform.

Does CARTO provide an SDK for the development of Mobile applications?

CARTO does not currently offer an SDK for the development of mobile apps as a component of our cloud native platform. In order to develop mobile applications with geospatial data, we recommend using the relevant SDK of your cloud vendor, or from products such as Google Maps, Apple Maps, Mapbox or Maplibre.

Particularly for the visualization of small datasets with spatial data (< 30MB), all SDKs will support visualization of GeoJSON files (e.g. ), and CARTO’s can be the technology to serve them.

The Mobile SDK in the previous version of the CARTO platform will not be further developed, and we don’t recommend starting new projects with it.

This may be because the data warehouse connection associated with the workflow does not have the required permissions to run Workflows in the data warehouse, such as the permission of creating schemas in the Workflows temp. location (configured in the advanced options of the connection card). Please choose or create another connection with data owner permissions or modify the permissions in the current connection and try again. If the issue persists, please contact our support team at [email protected].

In order to function, CARTO Workflows creates a temporal dataset in BigQuery named workflows_temp

To add a data source to a map as a new layer you can either:

• Pick a table or tileset from one of your active connections to cloud data warehouses

CARTO’s Analytics Toolbox is a set of UDFs and Store Procedures to unlock Spatial Analytics directly on top of your cloud data warehouse platform. It is organized in a set of modules based on the functionality they offer.

You can use the functions in the Analytics Toolbox via CARTO Builder, SQL Notebooks, and directly in the console of your cloud data warehouse platform.

Yes. We provide a basemap service using vector tiles, and we make them automatically available in all the components in the CARTO platform (Builder, Workflows, etc...), for all users.

Our basemaps are also compatible with Maplibre GL JS, so that .

The data for the CARTO basemaps is based on OpenStreetMap. Our basemaps are fully managed and powered by CARTO, including our own CDN, which makes them performant, scalable and customizable. Developers and users can choose between multiple , or even design their own styles following the

If you have never signed up for CARTO before, this can normally be fixed by clearing your browser’s cache. If you have previously used CARTO or created another CARTO organization - including a free trial - please see the FAQs below.

The CARTO CLI is published on npm as and installs as a global carto binary.

• Node.js 18 or newer. Check with node --version.

• A CARTO organization. The CLI works against CARTO Cloud (any region) and CARTO Self-Hosted deployments.

Personal authentication to CARTO. Manage login sessions, named profiles, and view current user information.

For an overview of the OAuth flow, profiles, and re-authentication behavior, see .

Open a browser-based OAuth 2.0 + PKCE login flow and store the resulting credentials.

Arguments:

• [profile] — Optional profile name. If omitted, an auto-generated name tenant_id/org_name/[email protected] is used.

Transfer data between warehouses. Waits for completion by default.

CLI-based agents such as Gemini CLI connect to the CARTO MCP Server using API Access Tokens. You create a token in CARTO Workspace, then pass it as an authorization header when registering the MCP Server in your agent.

• A CARTO organization with access to the Developers section.

• At least one Workflow exposed as an MCP Tool. See for setup instructions.

The MCP Server requires authentication via an :

The CARTO Workspace is the user interface for our next generation cloud-native Location Intelligence platform. It allows you to create stunning maps and perform spatial analytics at scale, with everything running directly on top of your cloud data warehouse(s). Learn how to make the most out of our Builder tool, Analytics Toolbox, Data Observatory, and other new features.

Check out the following pages for setting up your organization, getting acclimated to the workspace, and creating your first map:

What cloud data warehouses can I use with CARTO?

What are the device/web browser requirements for CARTO?

When I connect to a data warehouse, do you copy or store any data?

What happens if I do not have any cloud data warehouse platform to connect?

Can I import geospatial files into CARTO’s new platform?

What are the Location Data Services (LDS) providers configured by default in a CARTO organization?

What cloud data warehouses can I use with CARTO?

CARTO's new platform is designed to give you a fully cloud native experience, allowing you to run CARTO on top of your leading cloud data warehouse platform of choice (i.e. Google BigQuery, Snowflake, AWS Redshift, Oracle, Databricks, and any PostgreSQL-based data warehouse platform).

CARTO is designed to work in all modern browsers that meet the following criteria:

• Complete support, including hardware acceleration, for

• A browser version not older than 2 years

This includes the latest stable versions of Google Chrome, Safari, Firefox, Microsoft Edge, and Opera, but other browsers using standard technology and meeting the criteria above should be compatible as well.

While CARTO should work in all browsers meeting the criteria above, the best performance and compatibility are expected with Chromium-based browsers.

Please note that the user's device must also have hardware that supports these features. A desktop device with a dedicated GPU and at least 8 GB of RAM is recommended.

No, your connection allow us to perform queries against your data on your behalf, and the results are either stored again in your data warehouse or rendered in the client, as visible maps. CARTO being fully cloud native means no storage needs, less security concerns and no need for data replication or complex ETL processing.

For users who do not have any cloud data warehouse platform to which they want to connect CARTO, we are offering cloud storage and computing resources in what we call the CARTO Data Warehouse. A CARTO Data Warehouse connection is offered by default with your CARTO subscription.

Yes, at the moment you can import both local or remote (via URL) Shapefiles, CSV or GeoJSON files. You have more details available in the corresponding section of our .

CARTO offers access to Location Data Services (LDS) such as geocoding, isolines and routing by leveraging the APIs of 3rd party service providers. Since December 2023, by default, CARTO uses APIs for geocoding and routing, and for isolines.

CARTO retains the right to adjust the default configuration of these services at its sole discretion when deemed necessary. Other options to the default can be made available under special commercial and usage terms.

These guides will help you get started with CARTO. They're easy to follow with detailed steps, and will help you kickstart your project with your own connections, maps, workflows, and applications.

The CARTO CLI (@carto/carto-cli) is the official command-line interface for CARTO. It exposes nearly every platform operation as a scriptable command. Find and manage maps, workflows, connections and credentials, import and export geospatial data, run SQL on connected warehouses, manage users, audit activity, transfer assets between organizations, and chat with the AI agents configured on your maps.

The CLI is designed to be driven by:

• Humans at the terminal, for one-off admin tasks, scripting, and CI/CD.

• AI agents like Claude Code, Cursor, Codex, or Gemini CLI through tool use. The --json global flag gives agents machine-readable output for every command.

• Builder maps. Create, update, validate, publish, and copy CARTO Builder maps from a round-trippable JSON bundle. Inspect the AI agent surface available on each map. (Map screenshot is also available as an experimental command.)

• Workflows. Create, update, validate, verify, run, schedule, share, and publish CARTO Workflows. Publish a workflow as an MCP tool so any connected agent can call it. Install workflow extensions and browse the component catalog.

• Projects (folders). Group maps and workflows into projects, with a local-sync workflow that lets you clone, edit, and push changes back from your machine.

1. .

2. to your CARTO organization with carto auth login. Configure additional if you work with several organizations.

3. to see every available command, flag, and example.

If you're driving the CLI from an AI coding agent, also see , the catalog of skills that teach Claude Code, Cursor, Codex, and Gemini CLI how to use the CLI idiomatically.

Export a warehouse table to a file. Returns a download URL (24 h expiry) or writes to cloud storage.

Formats: geoparquet, geojson, shapefile, csv, geopackage, kml, kmz, tab.

carto export --connection <name> --source <table> --format <fmt>
carto export status <jobId>                     # Fetch status of an async export job

Options

What are the different deployment options for the CARTO platform?

Where can I find information about the requirements for deploying CARTO as Self-hosted?

How are updates and product releases managed in a Self-hosted deployment?

Where can I find information about deploying CARTO with Snowflake Container Services?

What are the different deployment options for the CARTO platform?

There are two different deployment options for the CARTO platform:

• CARTO Cloud: A fully managed deployment that CARTO hosts on our own cloud. When you use CARTO in our cloud, we manage configuration, updates, and versioning. This option is available in different regions that you can select when .

• Self-Hosted: With this option, you host your own CARTO tenant. That means it can be deployed in your virtual private cloud (VPC) or behind your virtual private network (VPN).

• (BETA) Snowflake Container Services: Fully deploy CARTO inside Snowflake by leveraging Snowflake Native Apps and Container Services.

Find links to the documentation and technical requirements .

While in CARTO Cloud updates and product releases are continously added to the platform, if you’re self-hosting your own CARTO tenant, it will need to be updated periodically to enjoy the latest version of the platform.

The CARTO team publishes versioned releases on the public Self-hosted repositories that can be used to upgrade your deployment. Find the latest releases for and

Find links to the documentation .

The CARTO Workspace includes functionalities for creating and publishing maps in a simple manner, using the CARTO map tool: Builder.

Builder is designed to allow technical and non-technical audiences to visualize, explore, and filter large amount of location data in your browser.

This guide will teach you how to create a map in the CARTO Builder, and perform data analysis by adding data to a map, adding filters, and more.

In the Maps section of the Workspace, you will see the list of your current maps. If you haven’t created a map yet, you will see the following page:

To create a new map, click Create your first map. This will open the CARTO map tool: Builder.

CARTO Builder contains many features that guide you through the process of creating a map, changing the styling, and selecting how your data appears. Use the following task list as guide for some of the main CARTO Builder features:

• Add your data

• Style your maps

• Set widgets

For new CARTO cloud deployments, users can choose between four different regions. These correspond to four separate CARTO tenants, each located in a different geographical location:

• United States East

• Europe West (located in the EU)

• Asia Northeast (located in Japan)

• Australia Southeast

These tenants are fully managed CARTO deployments that we host on our own cloud (on the Google Cloud Platform). We manage configuration, updates, and versioning. Changes to CARTO are pushed simultaneously to these four tenants, so they are functionally equivalent.

All your organization’s data such as maps, workflows, applications, etc; will be stored in the selected region. In addition, the of your organization will be located in that region as well.

There are a two main considerations when choosing a region:

• Proximity to your data

• Compliance and data regulations

Ideally, you should choose the region that is closest to your data to reduce latency and improve performance. For example, if you’re planning to connect CARTO to your Google BigQuery or Snowflake data in any US region, we recommend you choose the CARTO US region for optimal performance.

Some organizations might also have to choose a region that complies with specific data protection and privacy regulations, such as GDPR in the EU.

For additional help, you can use to help you select a cloud region.

The region of your organization is visible from the admin panel in the .

If you're not an admin, you can still check your organization's region by looking at the URL:

• clausa stands for United States East

• pinea for Europe West

• thunbergii for Asia Northeast

Heatmap point aggregation allows you to dynamically display your point data as a heatmap visualization, even when working with large-scale data. This type of visualization is ideal for simplifying complex datasets, identify hotspot patterns and gain insights from your data.

Visualization

In the Visualization section you can specify the Opacity setting at layer source. Additionally, within the Advanced visualization options , you can access Zoom Visibility to define the range at which your layer should be visualized.

Area of influence

The area of influence for heatmap layers defines the radius around each point that contributes to the heatmap. A smaller radius results in a smoother heatmap with lower detail, whereas a larger radius shows more distinct variations. This radius can either be uniform or vary according to a specific property.

Color

You can style your heatmap choosing the desired palette in the Color section. For more information about color palettes supported in Builder check this .

Raster data is composed of grids of pixels, where each pixel contains a value representing specific information, such as temperature, elevation, or vegetation indices. These datasets can represent continuous surfaces or sparse data with defined no-data regions. The CARTO platform provides seamless tools for importing, analyzing and visualizing raster sources directly in your data warehouse.

Visualizing rasters

To visualize raster sources, they must first be stored in your data warehouse using the CARTO raster loader. This tool ensures your raster files are properly uploaded and formatted for seamless integration with the CARTO platform. Learn more about preparing and uploading your raster data.

To optimize performance, raster sources should include overviews—lower-resolution versions of the raster data—enabling efficient visualization at different zoom levels. Additionally, if your raster source contains a color interpreter (e.g., palette, grayscale, or RGB), CARTO will automatically apply default styling based on the metadata, making it easier to quickly render the raster on your map.

When you add a source, Builder attempts to recognize if there is a spatial definition to render its associated layer. The spatial definition of your source depends on the column storing your spatial data and its specific type. Builder will automatically recognize the spatial data definition when possible. If not, you can manually define your data using the layer panel UI in the data section.

Automatic definition of spatial data

For Builder to automatically recognize the spatial data definition, regardless of whether the source is a table or an SQL query, your source must contain at least one valid spatial column with its related type as follows:

• Column storing geometry type: This column should store either point, line, or polygon geometry in a valid format. The column can have any name.

• Column storing spatial index ID: To be recognized by default, the spatial column should follow our naming convention:

  • H3: The column must be named h3.

  • Quadbin: The column must be named quadbin.

If Builder cannot automatically recognize a spatial data definition, you can still load it as a source in the map and use the UI to define your spatial column and type. Once your definition is set, you can click "Apply Selection" and Builder will use that definition to render your layer.

If your source contains multiple spatial columns, you can use the UI to decide which specific spatial column and type you want to use to render the layers associated with your source. For example, you might have a column containing the point geometry and additional columns representing the isochrones from that location.

Note: The spatial data definition is set at the source level; therefore, you must ensure consistency in the definition for all layers linked to that source.

Cluster point aggregation allows you to dynamically group and display your point data as clusters, even when working with large-scale datasets. This type of visualization is ideal for simplifying complex data, identifying concentration patterns, and gaining insights by visualizing data density in a more digestible format.

Visualization

In the Visualization section you can specify the Opacity setting at layer source. Additionally, within the Advanced visualization options , you can access Zoom Visibility to define the range at which your layer should be visualized.

Symbol

In this section, you can define the cluster radius range and adjust the symbol’s aggregation size. This allows you to control the level of detail in the clustering—lower values result in more detailed, granular clusters.

Fill

Define the Color that will be used to fill your cluster. You can set a simple color or use a color schema based on a given property to add depth and meaning to your lines. Additionally, you can adjust the fill opacity to your desired percentage for better visual effects.

When configuring either the color based on a property, you can access Advanced fill options to set the . This allows for a more granular and informative visualization.

In the Stroke section, you can customize the stroke color and adjust its opacity. Additionally, you can set the stroke weight to match your visualization needs.

Labels for cluster layers allow you to display the number of aggregated points within each cluster. You can customize both the text color and the halo (outline) color to fit your visualization needs.

In this guide, we'll walk through the process of creating your first CARTO organization. This will be the first step to start creating stunning maps and perform spatial analytics at scale, with everything running directly on top of your cloud data warehouse.

1. Account sign up

   • Go to the CARTO Sign up page.

   • Enter your email address and password. You can also sign up with your existing Google account by clicking Continue with Google.

   • Follow the steps to verify your email and continue with your new organization setup.

1. Organization setup

If your email domain is already associated with an existing CARTO organization, you will be able to join (or request to join) any of the existing organizations associated with that domain. Alternatively, you will be able to create a brand new organization.

For new organizations, you will need to choose an organization name (e.g. CARTO) and a deployment region. As a rule of thumb, you should choose the region closest to your data warehouse. For more information, check our article on .

After finishing the form, click "Let's get started with CARTO!" to complete the sign up process and get access to the CARTO Workspace. By signing up you accept the and the .

You are ready to start using CARTO!

The CARTO MCP Server exposes a catalog of tools an agent can call to explore your data, render maps, and run analytical workflows. Tools fall into three categories, each with its own page in this reference.

Builder now enables you to modify the location or connection of your data sources easily using the 'Change data source’ option available in the source card. This functionality ensures that map configurations remain consistent as long as the updated data sources maintain the same field names and types. For any components where a property cannot be identified, the map component will revert to its default settings.

How to change the source location and/or connection

• Table Data Sources:

  • Navigate to the source card panel and click on the three dots menu.

  • Select the ‘Change data source’ option and locate the new data source.

  • Once the new dataset is identified, click 'Change source'.

• SQL Query Data Sources:

  • Access the three dots menu in the source card panel to update the connection.

  • Alternatively, in the SQL Editor panel, click on the connection information in the top-right corner to modify it.

If the new data source contains the same fields with matching names and types, the map will retain its existing configuration, and no changes are expected. However, if some properties used in the map are missing in the updated data source, the following behavior should be expected:

Styling and Interactions:

• If a property used in interactions (e.g., hover or click actions) is missing in the new data source, those interactions will be removed.

• If a property used for layer styling (e.g., coloring by a column) is no longer available, the layer will revert to the default style.

Widgets:

• Widgets linked to missing properties will remain visible, and their configurations will be preserved.

• As an Editor, you can manually select a new column from the dropdown menu in the widget configuration panel or remove the widget entirely if no replacement column exists.

SQL Parameters:

• The updated connection must have access to the tables referred to in your custom SQL query. If not, you’ll need to update the query to refer to the relevant table locations.

• For SQL Parameters, ensure that the updated query is still valid so that parameter controls continue to work as expected.

Pre-generated tilesets are sources with tiles that have been previously generated using either the CARTO Analytics Toolbox or Workflows. Both the creation and storage of these tilesets occur in the data warehouse. This type of data source is ideal for managing very large, static datasets. They are efficient, cost-effective, and provide high-performance visualization.

Visualizing pre-generated tilesets

Builder supports the visualization of the four types of pre-generated tilesets:

• Vector Tilesets: Pre-generated tilesets processed from point, line, or polygon tables for smooth, interactive maps.

• Point Aggregation Tilesets: These tilesets aggregate point data with their properties into tilesets, perfect for visualizing dense point clusters.

• Quadbin Aggregation Tilesets: Aggregated grid for scallable hierarchy management.

• H3 Aggregation Tilesets: Aggregate quadbin indices into tilesets for scallable spatial hierarcy management.

To ensure optimizal visualization and performance, you must make use of the different parameters that allow you to have full-control of the tileset specification. To learn more about this type of source in terms of performance consideration, review this .

You can find a step-by-step guide to develop your first public application in the CARTO for Developers documentation:

Here you will learn the basic concepts required to create a public web application using CARTO, compatible with any Javascript Development Framework. With CARTO you don't need to be a geospatial expert to develop a geospatial application, so if you're a web developer you shouldn't have any issues following this guide.

After completing this guide you will be familiar with the following concepts:

• Scaffolding your application.

• Adding a

• Creating an with limited access to your data warehouse.

• Visualizing a dataset with

• Publishing your app

Organization-wide statistics and quotas.

carto org stats

View organization statistics, resources, and quota consumption.

carto org stats
carto org stats --json

The displayed information depends on your permissions:

• Regular users see resource counts and basic stats.

• Admin users see full organization statistics including quotas.

• If access is denied for some sections, partial data is shown with notes.

Surfaces shown (when available):

• Users — total, editors, viewers, superadmins, API access tokens.

• Resources — maps (yours and total), workflows, connections, applications.

• Usage & Quotas — usage quota, LDS credits, geocoding/isolines, map loads.

For an example of the full output, see .

In CARTO Builder, the Point layer visualization option allows you to render and style point features on your map. This layer type offers various advanced styling options to enhance the visual representation of your data such as creating heatmap or grid visualizations dynamically from your original source.

Visualization

Within the Advanced visualization options , you can access Zoom Visibility to define the range at which your layer should be visualized. This ensures that your lines are displayed at appropriate zoom levels, improving the clarity and relevance of your map.

If your data source contains identical geometries with varying attributes (e.g., weather stations, admin regions or buildings), you can use the Aggregate by geometry functionality to aggregate your layer based on a distinct spatial column. Learn more in this section.

Stroke

The stroke of your line layer can be customized in various ways to suit your visualization needs:

• Stroke Color: Set a simple color or use a color schema based on a given property to add depth and meaning to your lines. Additionally, you can adjust the stroke opacity to your desired percentage for better visual effects.

• Stroke Weight: Define the stroke weight as either a fixed value or based on a given property. You can modify the stroke weight using a simple slider when set to fixed, or by defining a weight range when configured by a property.

When configuring either the stroke color or stroke weight based on a property, you can access Advanced stroke options to set the color scale or weight scale. This allows for a more granular and informative visualization.

On layers using , apart from the predefined aggregation methods (avg, sum, min, max, count), you can write a custom SQL aggregation expression that runs on your data warehouse. This is useful for derived metrics like rates, ratios and weighted averages.

Custom aggregation is also available in popup fields. See .

June 30th, 2025

Improvement Workflows

Workflows now supports for teams. Editors can share workflows with their entire organization, SSO groups, or specific users to enable collaborative development.

This feature eliminates the need to duplicate workflows for minor changes, ensuring teams work from a single, consistent source of truth. Asynchronous editing with a request/approval model reduces conflicts while supporting smooth, coordinated teamwork.

Editor collaboration makes it easier for organizations to use Workflows at scale and promotes more frequent, effective use across teams.

June 25th, 2025

CARTO for Agents lets AI agents (Claude, ChatGPT, Cursor, Gemini, and others) work directly with the CARTO platform. Agents can connect to data warehouses, import and export geospatial data, build Builder maps, author and run workflows, expose those workflows as MCP tools, and check usage and activity.

There are three pieces:

• . A command-line interface (@carto/carto-cli) that exposes nearly every platform operation as a script-friendly command. Used by humans in a terminal, and by agents through tool use.

Manage data warehouse connections (BigQuery, Snowflake, Redshift, PostgreSQL, Databricks, …).

List all connections.

Get details for a specific connection.

Create a new connection. The body's shape depends on the provider.

Update a connection.

Delete a connection.

Browse the resource tree exposed by a connection (databases, schemas, tables, tilesets). Useful for picking source paths when authoring maps or workflows without leaving the terminal.

Options:

The CARTO MCP Server is the AI integration into your CARTO platform: your workspace, saved Builder maps, workflows, and connected data warehouses. Through the (MCP), agents like Claude or ChatGPT can explore your data, render interactive maps inline in the chat (ad-hoc visualizations or saved Builder maps), inspect data assets and column distributions, and run your organization's saved analytical workflows.

1. Get the MCP Server URL

   In your CARTO Workspace, go to Developers > Workflow API & MCP Server. Copy the MCP Server URL displayed under the CARTO AI section.

   The URL follows this pattern:

Manage Named Sources — server-side aliases for SQL queries. Instead of exposing raw SQL in client applications, create a Named Source with a name and reference it by name wherever the CARTO APIs accept a sqlQuery parameter.

Builder supports simple features stored as geometry or geography in cloud data warehouses. These simple features are defined as a standard which specifies digital storage of geographical data, usually point, line or polygon, storing both spatial and non-spatial features.

This table shows the current type of simple features (geometry or geography) supported on each data warehouse:

CARTO Agent Skills is a public catalog of short, on-demand playbooks that teach AI coding tools (Claude Code, Skills CLI, Codex, Gemini CLI) how to drive the CARTO platform fluently. The repository is at on GitHub.

Generic LLMs know about CARTO but make small mistakes when actually driving it: wrong CLI flags, outdated SQL dialects, missing async-job handling, the wrong import shape for a tileset. Each skill in the catalog is a focused playbook the agent loads on demand when a user's request matches the skill's domain, so the agent ships idiomatic, working CARTO output the first time.

Skills run locally inside your AI agent. When a skill is triggered, the agent reads the skill's instructions and uses the on your machine to act on your behalf. It authenticates with your local CARTO profile and operates against the warehouses you've already connected. No data leaves your environment via the skills repository. Everything flows through the CARTO CLI you control.

The catalog is organized in three layered tiers. An agent routes to the right skill automatically based on user intent.

CARTO Agent Skills are distributed from the public repo at . Each supported AI harness installs them differently, but they all read the same upstream catalog.

Before installing the skills, every harness needs:

• A with workspace access.

• Node.js 18+ and the installed and authenticated:

The CARTO platform natively supports spatial indexes, enabling you to leverage their capabilities when working with large-scale data directly in your data warehouse. Spatial indexes are excellent for large-scale analytics and visualization. Using Builder, you can create stunning and powerful visualizations by connecting directly to these types of sources. The supported spatial index formats are quadbins and H3.

Based on Discrete Global Grid (DGG) systems, spatial indexes reference each cell of the grid. Think of a spatial index as an id that always makes reference to the same portion of the surface on Earth.

• This portion of the Earth is called a cell.

Import a geospatial file into your data warehouse from a local file or URL. Waits for completion by default.

Supported formats: CSV, GeoJSON, GeoPackage, GeoParquet, KML, KMZ, Shapefile (zip). Size limit: 1 GB per file. Supported warehouses: CARTO DW, BigQuery, Snowflake, PostgreSQL, Redshift.

Data sources using spatial column storing quadbin identifiers and spatial type quadbin will be rendered as a Grid layer type. Grid layers uses quadbin to natively render features on the map in an aggregated manner.

In the Visualization section, you can easily identify the type of layer your visualizing. Additionally, within the Advanced visualization options , you can access Zoom Visibility to define the range at which your layer should be visualized. This ensures that your lines are displayed at appropriate zoom levels, improving the clarity and relevance of your map.

When using Grid layer visualization type in Builder, data is aggregated as you zoom in and out on the map. In the Cell section, you can define the aggregation size to determine the level of granularity you prefer for your data aggregation.

In this section you can define Color that will be used to fill your point symbol. You can set a simple color or use a

In CARTO Builder, the Point layer visualization option allows you to render and style point features on your map. This layer type offers various advanced styling options to enhance the visual representation of your data such as creating heatmap or grid visualizations dynamically from your original source.

Within the Advanced visualization options , you can access Zoom Visibility to define the range at which your layer should be visualized. This ensures that your lines are displayed at appropriate zoom levels, improving the clarity and relevance of your map.

If your data source contains identical geometries with varying attributes (e.g., weather stations or buildings), you can use the Aggregate by geometry functionality to aggregate your layer based on a distinct spatial column. .

In this section you can define Color that will be used to fill your point symbol. You can set a simple color or use a based on a given property to add depth and meaning to your lines. Additionally, you can adjust the fill opacity to your desired percentage for better visual effects.

Why should I migrate to the new version of the CARTO platform?

Is CARTO going to provide me assistance if I would like to migrate to the new platform?

What type of objects can be migrated between platforms?

Can I migrate my maps from the previous version to the new version of CARTO?

What information will you need to provide to receive assistance with the migration?

Do I need to provide an authorization for CARTO to work on my platform migration?

If my data tables are migrated to the CARTO Data Warehouse in the new platform, are there any associated costs with its usage?

The new platform offers you a complete cloud native experience, and unparalleled geospatial analysis and visualization capabilities on top of the leading cloud data warehouse platforms (i.e. Google BigQuery, Snowflake, AWS Redshift, Oracle and Databricks), eliminating the need of complex ETLs and the limits of scalability that our previous platform had.

In the new CARTO, we have implemented a new and more powerful version of CARTO Builder, further advanced our Data Observatory and Development tools, and created a new suite of geospatial analytics functions that can be run natively in the aforementioned cloud data warehouse platforms.

Our teams are currently laser focused on evolving both functionality and user experience to make the new CARTO the most powerful spatial analytics platform available in the market. Although we currently do not have any plans to deprecate the previous version, we recommend you to start your new projects in the new CARTO platform. CARTO will not be doing any further developments on the components of the old version of the platform, which will remain “as is”.

CARTO offers technical assistance for platform migrations to all our enterprise customers at no additional cost. If you have an Enterprise plan and you would like our assistance to migrate to the new version of our platform, please contact your CARTO representative or the Support team at .

We can only offer migration support between platform versions for data tables and your active Data Observatory subscriptions.

No. Unfortunately, since the technology stack between platforms is completely different, we cannot offer compatibility of maps built in the previous version of CARTO with our new technology. If you have TAM hours in your Support package, please ask your Customer Success Manager for an evaluation of the effort required to build your maps in the new platform.

In order for us to assist you with the migration to the new CARTO platform, we will need to receive the following information about your CARTO account in the previous version of the platform:

• The name(s) of the CARTO organization(s) in the previous version of the platform that you want to migrate to the new version;

• The name of the CARTO organization in the new platform to which you want to migrate your data to;

• A list of the data tables to migrate;

Yes. For us to be able to actively assist you with the platform migration, we will need you to send us a written authorization with the following text in order to give us the required permissions:

CARTO provides an instance of the CARTO Data Warehouse and monthly usage quotas with every subscription plan depending on the tier. Please get in touch with your CARTO representative to understand the service level associated with your subscription plan. You can read more information on this topic .

Any task associated with the platform migration is not expected to interfere with your CARTO service. In any case, CARTO will agree with you on a timeframe to carry out the migration activities, so you are completely informed on when these will be performed and therefore reduce the chances of any interference with your own usage of your CARTO accounts.

What is the new version of the CARTO platform?

Is the previous version of CARTO going to be deprecated?

How can I log into the legacy CARTO platform?

What happens to my current CARTO subscription? Will I have to pay extra to access the new platform?

Can I login to both versions of the CARTO platform with the same credentials?

Will all my data in the previous platform be readily available when I access the new version of CARTO?

Will I be forced to move all my data to the new version of the CARTO platform?

In October 2021, we launched a fully revamped version of the . The new platform offers a complete cloud native experience, allowing to run CARTO on top of the leading cloud data warehouse platforms (e.g. Google BigQuery, AWS Redshift, Snowflake, Databricks, Oracle, etc.), eliminating ETL complexity and limits on scalability.

This new platform works completely independent of the previous version of CARTO; hence, requires a different set of user credentials to access. You can learn more about the new platform with our .

No, we don’t have plans to deprecate the previous version of our platform for our existing Enterprise customers, so you don’t need to worry about that now. However, it is important to note that any new product developments will happen only in the new version of CARTO.

You can continue to login to the previous version of CARTO from .

Free trials for the new CARTO platform are already available on our . We also welcome all of our existing enterprise customers to contact us so we can provision them an account to the new platform for the reminder of their subscription term.

Although direct login to the legacy platform was removed from CARTO's website homepage in February 2024, you can continue to log into your account in the previous version of CARTO from .

If you are an existing CARTO Enterprise customer, we will give you an account to the new version of our platform without any additional cost for the reminder of your subscription term. Please get in touch with your CARTO representative or our Support team and we will provision you an enterprise account to the new platform according to your subscription plan.

No, the two platforms are completely independent, and hence they require their own set of credentials to login. In our login page users can select which version of CARTO they want to access. To access your old account, select “CARTO Dashboard”.

No, by default it is not. Both versions of the platform are completely independent. Get in touch with your CARTO representative or our Support team, and we can assist you to migrate your datasets across our two platform versions.

No, you won’t. If you are an existing CARTO customer you can enjoy both versions of the platform. If you are an existing enterprise customer, and you would like to make available in the new platform some of the tables you have in your existing account, please get in touch with your CARTO representative or our Support team, and we can assist you to migrate data across our two platform versions.

Yes, it is. Check and learn how to activate your CARTO Student account using the Github Student Developer Pack.

Yes, check all the details in . To get started, just get in touch with your contact or with and we’ll guide you through the process. In the end, users in your organization will see your SSO integration as the only way to access your organization.

To understand the current plan limits (quotas) and how far are you from reaching them, there’s a section located in Workspace > Settings > Subscription > Quotas where you can check all this information at any time. Check for examples and more information.

Every CARTO CLI command, organized by command group. The CLI uses a hierarchical structure:

carto [global-options] <command> <subcommand> [args...]

For global options (--json, --debug, --profile, …) and environment variables, see Configuration.

Manage CARTO projects — the containers that group maps and workflows. A project is a top-level folder; it can hold subfolders, native maps and workflows, and shortcuts to maps or workflows that live elsewhere.

# Read
carto projects list [options]                      # Top-level projects
carto projects get <id|name>                       # Project details + full contents tree

# Top-level CRUD
carto projects create --name <name>                # New top-level project
carto projects rename <path> --to <name>           # Rename a folder
carto projects delete <path>                       # Delete a folder or shortcut

# Asset placement
carto projects add <path> --folder <name>          # Create a subfolder inside a project
carto projects add <path> --map <map-id>           # Add an existing map (creates a shortcut)
carto projects add <path> --workflow <wf-id>       # Add an existing workflow (creates a shortcut)
carto projects move <path> --to <path>             # Move a folder or shortcut to a new parent

# Local-sync workflow
carto projects init <name>                         # New project + scaffold a local working dir
carto projects clone <id|name>                     # Materialize an existing project to disk
carto projects status                              # Show local-vs-clone diff (run inside a checkout)

Identifier resolution

Project arguments accept either the UUID (e.g. 62c90ed4-eeec-46d0-bda9-c7ea173e26f0) or the project name. Names are resolved via the entries search; ambiguous matches error out and ask for the UUID.

Nested locations use slash paths: Q2 Analytics/Maps/Drafts. The first segment must be a top-level project (or its UUID); subsequent segments walk the tree by title-match within each parent folder.

Adding maps and workflows: shortcuts under the hood

The CARTO platform doesn't currently expose a way to move an existing map or workflow into a folder — assets live at the account root. The mechanism for making one appear inside a project is to create a shortcut (an alias entry pointing at the underlying asset). carto projects add <path> --map <id> creates that shortcut for you. The map itself is not moved; deleting the shortcut later only removes the alias, not the map.

Treat a CARTO project as a working directory you can clone, edit, and sync:

The clone lays down:

• .carto/project.json — manifest with project ID, content hashes, server timestamps, and the recursive entry tree.

• AGENTS.md, README.md — tracked scaffold docs (their hashes go in the manifest, so edits show up in status).

Pushing edits back uses the existing per-resource verbs:

projects list — --in <id|name>, --search <query>, --owner <me|others>, --mine, --order-by <field> (updatedAt / title), --order-direction <ASC|DESC>, --page, --page-size.

projects get — --depth <n> (0 = unbounded, 1 = top level only), --budget <n> (folder-lookup cap, default 500), --no-entries (metadata only).

projects create — --name <name>, --color <hex>, --file <path> (read full create payload from JSON).

projects add — exactly one of --folder <name>, --map <map-id>, --workflow <id>, plus --color <hex> for new subfolders.

projects rename — --to <new-name>.

projects move — --to <path>. Top-level → top-level is not supported by the API today.

projects delete — --yes to skip the confirmation prompt.

projects init / projects clone — --path <dir> (default: ./<slug-of-name>/), --force (write into a non-empty dir / overwrite scaffold). clone adds --shallow (skip bundle fetches, just structure) and --budget <n>.

projects status — --path <dir> (project root, defaults to walking up from CWD), --server (also check for changes on the CARTO server since clone).

Superadmin operations: list resources across all users, batch delete, and transfer resources between users. Requires superadmin permissions.

carto admin list <resource-type>

List all resources across the organization (not just yours).

carto admin list maps
carto admin list workflows
carto admin list connections

# With pagination and search
carto admin list maps --page-size 50
carto admin list connections --search snowflake

# Fetch every page
carto admin list maps --all
carto admin list workflows --all

Resource types: maps, workflows, connections.

Options:

Delete multiple resources in a single call.

Transfer resources from one user to another.

Round-trip org-wide administrative settings (basemaps toggles, palettes, maps, connections, workflows, builder-gen-ai, carto-ai) as a single JSON bundle. The same shape that apply accepts is what get emits, so the three subcommands compose for moving settings between environments or capturing a snapshot for audit.

Subcommands:

Options:

CARTO Builder allows you to add sources by connecting directly with your data warehouses, ensuring security and data governance. Once a source is added, the related layer associated with the source is also rendered on the map. From this point, you can start styling your layer, adding widgets, and creating your interactive application.

Data sources types

Builder currently support the following data sources types:

• Simple features: Unaggregated features using standard geometry (point, line or polygon) and attributes, ready to use in Builder.

• Spatial Indexes: Aggregated data sources for improved performance or specific use cases, including Quadbin and H3 spatial indexes.

• : Tilesets pre-generated using CARTO Analytics Toolbox procedures or Workflows and stored directly in your data warehouse, ideal for handling very large, static datasets.

• : A raster source is composed of grids of pixels, where each pixel contains a value representing specific information

• Sources without an associated layer: These are data sources added to a map that has not associated layer. They are typically used to power widgets, SQL parameters, or AI Agents, enabling advanced interactivity and insights without visual clutter. You can add a layer from these sources at any time.

In Builder, you can add data sources either as table sources by connecting to a materialized table in your data warehouse or through custom SQL queries. These queries execute directly in your data warehouse, fetching the necessary properties for your map.

• Table sources: Connect directly to your data warehouse table through the data explorer dialog. Once connected, the data source is added including its related layer.

• SQL query sources: Perform a custom SQL query that will act as your input source. Once you execute it, if valid, a new data source and its linked layer will be added to the Builder.

To add sources in Builder, click on "Add source from" and choose from the following options:

• : Browse and add tables as sources from your existing connections.

• Write your own SQL query using the connection of your choice.

• : Start the process of importing a file to a CARTO connection. You can also drag and drop your files directly on Builder to start the import flow.

To add a source, navigate to the desired location, select your table and click 'Add Source'. The source and its associated layer will be added to the map.

Use the SQL Editor panel in Biulder to add a source by selecting a specific connection. Create your own SQL queries to perform simple analysis, create WHERE statements to pre-filter your data, or use SQL Parameters. You can also leverage CARTO Analytics Toolbox directly from this interface.

CARTO allows creating tables in your connections by importing files from your computer or via URL. Once a file is imported, the resulting table can be previewed in Data Explorer and used in Builder and external applications.

Manage users and invitations in your CARTO organization.

User management commands require admin or superadmin permissions. Regular users may not have access to view all organization users; invitation commands require permission to invite users to the organization.

carto users list

List users.

carto users list
carto users list --page 1 --page-size 20
carto users list --role Builder
carto users list --search "john"
carto users list --all

Options:

Get detailed information for a user. Accepts a user ID or an email address.

Output includes the user profile, roles, organization, identities, and groups.

Invite one or more users to the organization. Both comma-separated and multi-argument forms are accepted.

Options:

Available roles:

• Builder — full access to create and edit maps, workflows, and connections.

• Viewer — read-only access to view maps and data.

• Guest — limited access, typically for external collaborators.

List pending invitations.

Resend a pending invitation.

Cancel a pending invitation.

Remove a user from the organization. Requires admin permissions.

H3 point aggregation allows you to dynamically visualize your point data as an aggregated hexagonal bins, leveraging CARTO's native support for H3 spatial indexes. This type of visualization is ideal for simplifying large datasets, improving performance by reducing rendering complexity, and identifying patterns and trends within the data.

Visualization

In the Visualization section, you can easily identify the type of layer your visualizing. Additionally, within the Advanced visualization options , you can access Zoom Visibility to define the range at which your layer should be visualized. This ensures that your lines are displayed at appropriate zoom levels, improving the clarity and relevance of your map.

Cell

When using Grid layer visualization type in Builder, data is aggregated as you zoom in and out on the map. In the Cell section, you can define the aggregation size to determine the level of granularity you prefer for your data aggregation.

Fill

In this section you can define the Color that will be used to fill your cell. You can set a simple color or use a based on a given property to add depth and meaning to your lines. Additionally, you can adjust the fill opacity to your desired percentage for better visual effects.

When configuring either the color based on a property, you can access Advanced fill options to set the . This allows for a more granular and informative visualization.

The stroke of your line layer can be customized in various ways to suit your visualization needs:

• Stroke Color: Set a simple color or use a color schema based on a given property to add depth and meaning to your lines. Additionally, you can adjust the stroke opacity to your desired percentage for better visual effects.

• Stroke Weight: Define the stroke weight as either a fixed value or based on a given property. You can modify the stroke weight using a simple slider when set to fixed, or by defining a weight range when configured by a property.

When configuring either the stroke color or stroke weight based on a property, you can access Advanced stroke options to set the color scale or weight scale. This allows for a more granular and informative visualization.

You can enable height visualization to extrude the height of your grid layer. When this is enabled, make sure to change the map view to 3D so you can see the features on this view mode.

Set a fixed height or set the height value based on a given property. You use the slider to multiple the height value according to your need.

When configuring the height based on a property, you can access Advanced height options to set the height scale. Additionally, you can enable the Show wireframe option to visualize the stroke of the 3D objects.

Apart from the predefined aggregation methods (avg, sum, min, max, count), you can write a custom SQL aggregation expression that runs on your data warehouse. This is useful for derived metrics like rates, ratios and weighted averages.

Custom aggregation is also available in popup fields. See .

Grid point aggregation allows you to dynamically visualize your point data as an aggregated grid, leveraging CARTO's native support for spatial indexes. This type of visualization is ideal for simplifying large datasets, improving performance by reducing rendering complexity, and identifying patterns and trends within the data.

Visualization

In the Visualization section, you can easily identify the type of layer your visualizing. Additionally, within the Advanced visualization options , you can access Zoom Visibility to define the range at which your layer should be visualized. This ensures that your lines are displayed at appropriate zoom levels, improving the clarity and relevance of your map.

For this type of layer, there is an additional COUNT aggregation operation available for numeric properties. In order to ensure a precise count, our recommendation is to use a unique id column in your data.

Cell

When using Grid layer visualization type in Builder, data is aggregated as you zoom in and out on the map. In the Cell section, you can define the aggregation size to determine the level of granularity you prefer for your data aggregation.

In this section you can define Color that will be used to fill your cell. You can set a simple color or use a based on a given property to add depth and meaning to your lines. Additionally, you can adjust the fill opacity to your desired percentage for better visual effects.

When configuring either the color based on a property, you can access Advanced fill options to set the . This allows for a more granular and informative visualization.

The stroke of your line layer can be customized in various ways to suit your visualization needs:

• Stroke Color: Set a simple color or use a color schema based on a given property to add depth and meaning to your lines. Additionally, you can adjust the stroke opacity to your desired percentage for better visual effects.

• Stroke Weight: Define the stroke weight as either a fixed value or based on a given property. You can modify the stroke weight using a simple slider when set to fixed, or by defining a weight range when configured by a property.

When configuring either the stroke color or stroke weight based on a property, you can access Advanced stroke options to set the color scale or weight scale. This allows for a more granular and informative visualization.

You can enable height visualization to extrude the height of your grid layer. When this is enabled, make sure to change the map view to 3D so you can see the features on this view mode.

Set a fixed height or set the height value based on a given property. You use the slider to multiple the height value according to your need.

When configuring the height based on a property, you can access Advanced height options to set the height scale. Additionally, you can enable the Show wireframe option to visualize the stroke of the 3D objects.

Apart from the predefined aggregation methods (avg, sum, min, max, count), you can write a custom SQL aggregation expression that runs on your data warehouse. This is useful for derived metrics like rates, ratios and weighted averages.

Custom aggregation is also available in popup fields. See .

Maintaining accurate analytics in your map visualizations depends greatly on the freshness of your data. This section will delve into how Builder ensures your data remains current and will detail the options you have for refreshing your data sources.

Caching and data freshness

Builder makes it straightforward to manage data freshness right from the initial map load. Data caching is enabled by default, varying by data type and warehouse provider, but you have the liberty to set specific freshness intervals for your map's data sources.

Default freshness settings

• SQL Query sources: By default, data is cached for one year across all connections. If your data remains unchanged, it will be automatically refreshed after a year.

• Table sources: The duration of data caching varies depending on your data warehouse provider:

  • BigQuery, Snowflake, and Oracle: Requests are cached for a minimum of 5 minutes. CARTO continues to serve cached results if the table data hasn't been updated.

  • Redshift, Databricks, and PostgreSQL: Requests are cached for 30 minutes.

• Pre-generated tileset sources: Data is cached for a year. It's automatically refreshed after this period if unchanged.

• Raster sources: Data is cached for a year. It's automatically refreshed after this period if unchanged.

Customizing data freshness

Choose from predefined freshness periods for your data sources to ensure maps load with the most current data, providing reliable analytics.

Caching plays a crucial role in optimizing the performance and responsiveness of your map. Each component, such as a map layer, leverages its own cache to store data essential for its visualization. Here's how it functions:

• Data Storage: When you view a layer within a specific map extent, the system caches the data retrieved by that particular query. This means that if you or another user views the same layer with the same map extent again, the system can quickly display the data from the cache without needing to re-fetch it from the data source.

• Handling Changes: Any modifications to the viewport extent, adjustments to widget filters, or changes in SQL parameter inputs trigger a new query to the data warehouse for data that hasn't been cached yet. Once this query is executed, its results are stored in the cache for future use.

This caching mechanism ensures efficient data retrieval and visualization, significantly enhancing the user experience by reducing load times and improving the map's overall performance.

Refreshing your data sources couldn't be simpler. Whether you need to update all sources or just specific ones, Builder's "Refresh" options are designed for efficiency. Initiating a refresh reloads your data sources and their associated layers, clearing any previous cache and sending a new request to your data warehouse. This process guarantees you're always working with the latest data.

Some AI platforms — including Claude.ai, ChatGPT, and others — connect to MCP Servers using OAuth authentication. Instead of manually copying an API token, you log in through the platform's interface and are redirected to CARTO to authorize access.

This is an alternative to the . OAuth is well suited for web-based AI platforms that handle the authentication flow natively, while API Access Tokens work better for CLI-based agents like Gemini CLI.

Claude.ai and Claude Code use Client Identifier Metadata Document (CIMD) registration, so CARTO recognizes them automatically. No OAuth client setup is required: paste the MCP Server URL into the client and log in with your CARTO account when redirected.

The rest of this page covers the manual OAuth client setup required by other platforms, including ChatGPT, MCP Inspector, and MCP Jam.

When you log in to your CARTO user account, you will be presented with your Workspace. The Workspace allows you to access all components of the CARTO platform via a single interface. It will allow you to manage connections to your data warehouse(s), explore your data, subscribe to Data Observatory datasets, develop spatial applications, and run visualizations and spatial analysis through our tools Builder and Workflows.

The first time that you access the Workspace, you will see a Welcome banner with links providing quick access to different actions to get you started with CARTO, like creating your first connection or your first map and workflow, or starting with your spatial analysis in an easy guided way from our editable pre-built demo maps and demo workflows.

From the “Connect your data warehouse” banner, you can easily connect your data warehouse(s) to start using CARTO by clicking on Create new connection button. Check the quick guides to and to get started.

The CLI stores authentication credentials in ~/.carto_credentials.json with support for multiple profiles:

Structure:

• current_profile — the default profile used when --profile is not specified.

Manage application credentials — API tokens, SPA OAuth clients, and M2M OAuth clients. These credentials are separate from your personal authentication (carto auth login) and are used by applications and backend services to call CARTO APIs.

Credential types:

• API Access Tokens — server-side API access with specific connection and source grants.

• SPA OAuth Clients — Single Page Application authentication flows.

Browse, search, and subscribe to datasets from the CARTO Data Observatory catalog (10,000+ spatial datasets from 50+ providers).