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. It is available for both individual users and enterprises.

Components of the CARTO platform

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

Dasbhoard
Dashboard

Connect to multiple data sources, including local or remote files, cloud data warehouses, and BI solutions. Seamlessly access a wealth of vetted datasets to enhance your geospatial analysis.

Login or create an account

Builder
Builder

CARTO Builder offers powerful map making, data visualization, and pre-packaged analytics.

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
CARTOframes

CARTOframes is a Python package for integrating CARTO maps, spatial analytics, and data services into your data science workflows.

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

Spatial Analysis with Builder

Intro

Builder is our drag & drop 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 upload a .csv file and create your first dataset, create a simple map, and publish it.

Builder image

Import your data

Download the following dataset:

World Ports 3,669 rows 708 kB Download

In the “Connect dataset” tab, click on “Browse”, select the file, and then click on “Connect dataset”

Builder image

Explore your new dataset

Once the upload has finished and the new dataset has been created, you will be redirected to the Dataset view. Here, you can explore your data.

Builder image2

Double-click on any cell to edit it. Click on any of the columns to change the order, rename it, change its data type, remove it, or even add new columns. You can also add new rows and export your data in different formats.

Create a map using your new dataset

From the dataset view, click on the “Create map” button (on the bottom right of your screen). Your map will be created and you will be redirected to Builder, CARTO’s map editor:

Builder image2

Double click on the name of the map (Untitled Map) and rename it to “My first map”. This will also be the name that you will see on your dashboard.

Change the style of the features on the map (eg: point size, point color, strike size, strike color) by clicking on the layer name and playing with the styling options.

Builder image2

Publish and share your map with the world

1.- Click “Publish” to publish your map.

2.- Click on the red privacy button to make your map “Public”.

3.- Click “Publish” to publish this version of your map.

Your map has now been published and you can use the link or embed code to share your map.

Builder image2

Spatial Analysis with CARTOframes

This guide is intended for those who want to start augmenting their data using CARTOframes, our Python library. You can find full guides and examples in the documentation page.

Intro

We define enrichment as the process of augmenting your data with new variables by means of a spatial join between your data and a dataset aggregated at a given spatial resolution in the CARTO Data Observatory.

The enrichment process can be performed using CARTOframes following a few simple steps. In this guide, we’ll show you how to find out how many people live in the areas of influence that can be covered during an 8-minute walk around each of these stores:

First, we need to set the credentials of the CARTO account that will be used to perform these operations.

1
2
3
from cartoframes.auth import set_default_credentials

set_default_credentials('creds.json')
Get areas of influence

Let’s read the file where we have our areas of influence stored and check out the first few records:

1
2
aoi_gdf = read_file('http://libs.cartocdn.com/cartoframes/files/starbucks_brooklyn_isolines.geojson')
aoi_gdf.head()
data_range geometry
8 min. MULTIPOLYGON (((-73.95959 40.67571, -73.95971 …
17 min. POLYGON ((-73.95988 40.68110, -73.95863 40.681 …
25 min. POLYGON ((-73.95986 40.68815, -73.95711 40.688 …
8 min. MULTIPOLYGON (((-73.96185 40.58321, -73.96231 …
17 min. MULTIPOLYGON (((-73.96684 40.57483, -73.96830 …

Let’s keep only the 8-minute range:

1
aoi_gdf_8 = aoi_gdf[aoi_gdf['range_label']=='8 min.']
Get population data from the Data Observatory

After browsing the Data Catalog, we’ve decided we are going to enrich our data with demographics data aggregated at the Census block group level from this dataset provided by AGS.

We can then list the variables available in this dataset with just a couple of lines of code:

1
2
3
4
5
from cartoframes.data.observatory import *

dataset = Dataset.get('ags_sociodemogr_a7e14220')
variables = dataset.variables
variables
1
2
3
4
5
6
7
[<Variable.get('BLOCKGROUP_30e525a6')> #'Geographic Identifier',
 <Variable.get('POPCY_4534fac4')> #'Population (2019A)',
 <Variable.get('POPCYGRP_3033ef2e')> #'Population in Group Quarters (2019A)',
 <Variable.get('POPCYGRPI_1e42899')> #'Institutional Group Quarters Population (2019A)',
 <Variable.get('AGECY0004_aaae373a')> #'Population age 0-4 (2019A)',
 <Variable.get('AGECY0509_d2d4896c')> #'Population age 5-9 (2019A)',
 ...]

Let’s visualize the total population variable, POPCY_4534fac4 in the context of one of our stores and its area of influence:

Enrich areas of influence

To enrich our areas of influence, we first have to select the variable that we are going to use for the enrichment (total population):

1
variable = Variable.get('POPCY_4534fac4')

Next, we run the enrichmenth of our areas of influence with this simple command:

1
2
enriched_aoi_gdf = Enrichment().enrich_polygons(aoi_gdf_8, [variable])
enriched_aoi_gdf.head()

As a result, we get a new column added to our dataset, containing the total population that lives inside each the areas of influence:

data_range geometry POPCY
8 min. MULTIPOLYGON (((-73.95959 40.67571, -73.95971 … 21893.52
8 min. MULTIPOLYGON (((-73.96185 40.58321, -73.96231 … 23118.11
8 min. MULTIPOLYGON (((-73.99010 40.62280, -73.99067 … 18204.30
8 min. MULTIPOLYGON (((-74.02791 40.63631, -74.02809 … 17606.95
8 min. MULTIPOLYGON (((-74.00100 40.59815, -74.00141 … 2517.66
Visualize the result

Map visualizations can be created very easily using CARTOframes. In fact, all the maps that you’ve seen so far in this guide have been created with it.

Let’s create a map where we can see the result of our enrichment, that is, the areas of influence colored according to the number of people who live in it. We can do it with a really simple single line of code:

1
Layer(enriched_aoi_gdf, color_continuous_style('POPCY'))

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. To create a new app in a folder called my-app using the template for CARTO 3 (our fully cloud native platform), you need to execute the following command in your terminal (requires Node.js):

1
~ npx 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 (requires the yarn package manager):

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
5
credentials: {
  apiVersion: API_VERSIONS.V3,
  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.