Getting started with CARTO

Helpful resources to get you up and running.

CARTO in a nutshell

CARTO is the leading Location Intelligence platform. It enables organizations to use spatial data and analysis for more efficient delivery routes, better behavioral marketing, strategic store placements, and much more.

Data Scientists, Developers, and Analysts use CARTO to optimize business processes and predict future outcomes through the power of Spatial Data Science.

Our platform helps you visualize, analyze, and build applications using location data, natively on your cloud data warehouse platforms. CARTO is available for both individual users and enterprises, in both cloud and self-hosted deployments.

Components of the CARTO platform

Depending on your usage of the CARTO platform, whether it’s for visualization, analysis, data access, or application development, you will be using different components of the platform.

Dasbhoard
Workspace

The central location of all your experience with CARTO; connect to multiple cloud data warehouses, explore your geospatial data, geocode your tables, enrich your data with a wealth of vetted datasets to enhance your geospatial analysis, and access the different CARTO tools.

Login or create an account

Builder
Builder

CARTO Builder offers powerful map making capabilities, interactive data visualizations, collaboration and publication options - everything running natively from your cloud data warehouse.

Learn more

Platfrom APIs and libraries
Platform APIs and libraries

For the Developer community, we have created a complete library of APIs, frameworks, connectors, and development tools to accelerate the spatial app development process.

View all libraries and APIs

CARTOframes
Analytics Toolbox

The CARTO Analytics Toolbox is a suite of functions and procedures to easily enhance the geospatial capabilities available in the different cloud data warehouses. It contains more than 100 advanced spatial functions, grouped in different modules such as tiler, data, clustering, statistics, etc.

Learn more

Data Observatory
Data Observatory

We catalog and distribute thousands of vetted public and premium spatial datasets, covering most global markets. These datasets are available across the different components of CARTO, so you can use them for data enrichment or as additional layers for your spatial apps and analyses.

Explore our Spatial Data Catalog

CARTO for Spatial Analysis

CARTO’s Location Intelligence platform lets you store, enrich, analyze, & visualize spatial data to make insightful decisions. Our platform extends the geospatial capabilities of the leading cloud data warehouse platform ensuring you can get the most out of your location data.

Spatial Analysis with Builder

Intro

Builder is our mapping tool to design, build, and publish interactive web maps with your location data. Maps can be easily shared or embedded on any website or blog.

In this guide, you will learn how to use the sample data available in the CARTO Data Warehouse to find the best place to create a store close to the potential customers:

Builder image

Create your first map

Log in to CARTO.

Go to Maps and click on “+ New Map”.

Builder image

Once in Builder, click on “Add source from …”

Builder image

Select “Custom Query (SQL)” and “Type your own query” using the carto_dw connection and click on “Add Source”

Builder image

Now, you have a SQL panel where you can run queries in CARTO Data Warehouse (based on Google BigQuery) and see the result in the map.

Builder image

Explore your data

The following queries should be executed in order, and each of them will show a different result:

Let’s start by just plotting a table that we have through our connection with the CARTO Data Warehouse (note that you would achieve the same result creating a map from the Data Explorer)

1
SELECT * FROM `carto-demo-data`.demo_tables.sample_customer_home_locations

Builder image

Optionally, you could spend some time and style this layer based on the customer value feature, either with the fill color of the points …

Builder image

… or their radius.

Builder image

Find clusters of points

Now, we are going to modify the SQL Query used to generate the map layer, and we are going to use the clustering functions in CARTO’s Analytics Toolbox to generate 6 clusters (which is the number of stores we want to open).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
WITH clustered_points AS
  (
    SELECT `carto-un`.clustering.ST_CLUSTERKMEANS(ARRAY_AGG(geom ignore nulls), 6) AS cluster_arr
    FROM `carto-demo-data`.demo_tables.sample_customer_home_locations
  )

SELECT 
  cluster_element.cluster, 
  ST_UNION_AGG(cluster_element.geom) AS geom 
FROM clustered_points, UNNEST(cluster_arr) AS cluster_element 
GROUP BY cluster_element.cluster

Builder image

Let’s now change the name of the layer to “Clusters of customer homes”

Builder image

Style the layer by modifying the fill color of the points based on the column “cluster”. You can change the color and width of the stroke in order to polish the visualization.

Builder image

You can also add a Widget to be able to filter the home locations based on the cluster

Builder image

Let’s also add a tooltip to the points based on the cluster number

Builder image

Locate your stores

We are now going to create another layer. In order to do that, click again on “Add source from”, “Customer Query (SQL)” and “Type your own query” from your carto_dw connection. Finally click on “Add source”.

Builder image

For this second layer we are going to adapt the previous SQL Query and compute the centroid of each of the clusters using the transformation functions in the Analytics Toolbox; this would give us a potentially optimal location to open each store in the center of each of the previously computed clusters.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
with clustered_points AS

  (
    SELECT `carto-un`.clustering.ST_CLUSTERKMEANS(ARRAY_AGG(geom ignore nulls), 6) AS cluster_arr
    FROM `carto-demo-data`.demo_tables.sample_customer_home_locations
  )

SELECT 
  cluster_element.cluster, 
  `carto-un`.transformations.ST_CENTERMEAN(ST_UNION_AGG(cluster_element.geom)) AS geom 
FROM clustered_points, UNNEST(cluster_arr) AS cluster_element 
GROUP BY cluster_element.cluster

Let’s rename this second layer as “Cluster centers” and style this layer by changing the fill color and increasing the radius of the points in order to make them more visible

Builder image

That’s it! The resulting map shows the different clusters of customer locations and the potential location of each store.

Spatial Analysis with the Analytics Toolbox

CARTO’s Analytics Toolbox is a suite of +100 functions and procedures extending the spatial analysis capabilities of your cloud data warehouse platform. The toolbox is organized in modules related to different types of functionalities, such as operating with spatial indexes, creating tilesets out of your large datasets, location data services, geostatistics and much more.

This guide is intended for those users who want to perform spatial analytics natively in their data warehouse using CARTO’s set of prepared analytical functions. In this guide we will focus on the implementation of the Analytics Toolbox for BigQuery, but this component is also available for Snowflake, Redshift, Databricks and PostgreSQL.

Intro

In this example we are going to identify hotspots of amenity POIs in Stockholm using OpenStreetMap data and the GETIS_ORD_H3 function available in the statistics module. POIs can be found in the publicly available cartobq.docs.osm_pois_stockholm table (via the CARTO Data Warehouse or a BigQuery connection). We will implement this analysis using the SQL panel available for adding data sources from SQL queries in Builder, but it can also be run directly on your BigQuery console.

Final map

Visualize the POIs

In order to visualize the OpenStreetMap data that we are using for POIs, you can simply execute the following query:

1
SELECT * FROM cartobq.docs.osm_pois_stockholm WHERE amenity IS NOT NULL

Visualize pois

With Builder, you can use widgets and tooltips in order to explore the data in more detail, as illustrated in the image below.

Visualize pois with widgets

Compute the H3 resolution 9 cell in which each POI falls into

With the execution of the following query, we run the H3_FROMGEOGPOINT method in order to transform and aggregate a point-based dataset into a grid based on the H3 spatial index.

1
2
3
4
5
6
 SELECT h3, CAST(COUNT(*) AS FLOAT64) AS n_amenity_pois,
 FROM (
   SELECT `carto-un`.carto.H3_FROMGEOGPOINT(geom, 9) AS h3,
   FROM cartobq.docs.osm_pois_stockholm
   WHERE amenity IS NOT NULL )
 GROUP BY h3

In order to visualize the output of this query remember to change the type of geometry in the SQL panel to an H3 index.

Builder spatial data type

Then you can style the map layer that gets generated based on the n_amenity_pois feature.

POIs H3 style layer

Compute the Getis-Ord Gi* statistic

The final result can be obtained by executing the following query, in which we combine both the aggregation of POIs in an H3-based grid and the computation of the Getis-Ord Gi* statistic for each of the grid cells. This measure tells you where features with either high or low values (of the n_aminity_pois) cluster spatially or not. It’s a good statistic in order to run a hotspot analysis.

POIs sql getis ord gi*

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
WITH
 stockholm AS (
 SELECT h3, CAST(COUNT(*) AS FLOAT64) AS n_amenity_pois,
 FROM (
   SELECT `carto-un`.carto.H3_FROMGEOGPOINT(geom, 9) AS h3,
   FROM cartobq.docs.osm_pois_stockholm
   WHERE amenity IS NOT NULL )
 GROUP BY h3),
 
 getis_ord AS (
 SELECT `carto-un`.carto.GETIS_ORD_H3(ARRAY_AGG(STRUCT(h3, n_amenity_pois)),
     4, 'triangular') AS output
 FROM stockholm )
 
SELECT unnested.INDEX AS h3, unnested.gi
FROM getis_ord, UNNEST(getis_ord.output) AS unnested

The results can be explored on a map such as in the example below, where we can use the histogram widget to narrow down the cells with the highest Gi* values, which correspond to the location of the hotspots of amenity POIs in Stockholm.

Remember once again to change the type of geometry in the SQL panel to an H3 index.

Builder spatial data type

POIs map getis ord gi*

CARTO for Development

Our goal is to make the development of web-based spatial applications as easy as possible. To achieve this, our developer toolkit includes industry-leading visualization, mapping, and application design components, giving developers unparalleled flexibility to create truly beautiful geospatial user experiences on the web and mobile.

The CARTO platform is based on industry standards like GeoJSON or vector tiles. You can use your choice of visualization library because most of them have support for these standards. We recommend using deck.gl with the CARTO module as we are actively contributing to ensure the best integration and performance. In this website you will find guides and examples for working with CARTO and different visualization libraries.

If you are developing a web application, the CARTO platform is framework-agnostic, so you can use Angular, Vue.js, React, or any other frontend framework/library. We recommend using React because we think reactive programming is a sound approach to spatial applications architecture. If you want to reduce development time, we encourage you to use CARTO for React, although you can build an application with CARTO and React without it. We also provide guides and examples for integrating CARTO with Angular and Vue.js.

App Development with CARTO for React

Intro

CARTO for React is our product for building faster and better spatial apps. Kickstart your development environment with our templates for Create React App and take advantage of our advanced widgets and the custom theme for Material-UI user interface components.

In this guide we will show you how easy it is to create a great looking spatial app from scratch to visualize a dataset and filter it with an interactive widget.

Final app

Kickstart your app

CARTO for React provides templates for Create React App. The basic pre-requisite is to have Node.js installed in your computer, preferably using a version manager like nvm. You also need a package manager; by default Node.js comes with npm but you can also use other package managers like yarn. To create a new app in a folder called my-app using the template for CARTO 3, you need to execute the following command in your terminal:

If you want to use npm:

1
~ npx create-react-app my-app --template @carto/base-3

If you want to use yarn:

1
~ yarn create react-app my-app --template @carto/base-3

Then you can start a development server by changing the current directory and executing the following command:

For npm:

1
2
~ cd my-app
~ npm start

For yarn:

1
2
~ cd my-app
~ yarn start

You should see the following app in your browser with a default header, a sidebar, and an area dedicated to the map:

Blank app

Adding a layer

Now we are going to add a layer to visualize data from a data source that will be displayed in a new view. These are the three main components for working with CARTO for React and we provide a code generation tool based on Hygen to make it really easy to create them.

The data source is a dataset coming from a BigQuery table named retail_stores. For this tutorial, we are using a token that provides access to the BigQuery table but you can also use OAuth for providing authenticated access. This means you also need to remove the oauth object from the initial state (or comment it out).

First you need to edit the src/store/initialStateSlice.js file and add the public access token to the credentials object:

1
2
3
4
credentials: {
  apiBaseUrl: 'https://gcp-us-east1.api.carto.com',
  accessToken: 'eyJhbGciOiJIUzI1NiJ9.eyJhIjoiYWNfbHFlM3p3Z3UiLCJqdGkiOiI1YjI0OWE2ZCJ9.Y7zB30NJFzq5fPv8W5nkoH5lPXFWQP0uywDtqUg8y8c',
},

Then you create a new view named “Stores” and include the link in the header:

1
2
3
4
5
~ yarn hygen view new
$ hygen view new
✔ Name: · Stores
✔ Route path: · stores
✔ Do you want a link in the menu? (y/N) · true

You can now create a source pointing to the BigQuery table:

1
2
3
4
5
6
~ yarn hygen source new
$ hygen source new
✔ Name: · Stores
✔ Enter a valid connection name · bqconn
✔ Choose type · table
✔ Type a query · cartobq.public_account.retail_stores

Finally you can create a layer using the source and view created in the previous steps:

1
2
3
4
5
~ yarn hygen layer new
✔ Name: · Stores
✔ Choose a source · storesSource
✔ Do you want to attach to some view (y/N) · true
✔ Choose a view · Stores (views/Stores.js)

If we look at our browser, we should see a new link “Stores” in the header. If we click on this link, the stores layer will be displayed on top of the basemap:

Add layer

Adding a widget

Now we are going to add a widget to show the revenue by store type for stores in the current viewport. To do that, we are going to use the Category widget.

We need to open the src/components/views/Stores.js folder and import the component and enumeration that we will use in the widget definition:

1
2
import { AggregationTypes } from '@carto/react-core';
import { CategoryWidget } from '@carto/react-widgets';

Then we need to remove the “Hello World” <Grid> component and add the following JSX code for the widget:

1
2
3
4
5
6
7
8
<CategoryWidget
  id='revenueByStoreType'
  title='Revenue by store type'
  dataSource={storesSource.id}
  column='storetype'
  operationColumn='revenue'
  operation={AggregationTypes.SUM}
/>

In addition to giving the widget a unique ID and a title, we link it with the layer through the dataSource property. The Category widget groups the features by the attribute specified in the column parameter and executes the aggregation operation specified in the operation parameter over the attribute specified in the operationColumn parameter.

If you go to your browser, you will see the widget in the sidebar and if you click on any of the store types, you will see how the map is filtered.

Add widget

Additional resources

In this documentation center you will find comprehensive documentation on CARTO for React. For visualization, CARTO for React uses our module for deck.gl. You can also use deck.gl with other frontend frameworks like Angular or Vue.js.

CARTO is an open ecosystem that does not force you to use a specific technology or library. Please read the following guides if you want to work with CARTO and Google Maps, Mapbox, or Amazon Location.

Your application probably provides access to datasets stored in the CARTO database. Please read this article to understand how authorization is handled and how you can take advantage of CARTO support for the OAuth 2.0 protocol.

When you are interacting with the CARTO platform, you may reach some limits that we put in place to guarantee the performance and prevent abuse. Please read this article to learn more about this.