A Python package for integrating CARTO maps, analysis, and data services into data science workflows.

Python data analysis workflows often rely on the de facto standards pandas and Jupyter notebooks. Integrating CARTO into this workflow saves data scientists time and energy by not having to export datasets as files or retain multiple copies of the data. Instead, CARTOframes give the ability to communicate reproducible analysis while providing the ability to gain from CARTO’s services like hosted, dynamic or static maps and Data Observatory augmentation.


  • Create interactive maps from pandas DataFrames (CARTO account not required)
  • Publish interactive maps to CARTO’s platform
  • Write and read pandas DataFrames to/from CARTO tables and queries
  • Create customizable, interactive CARTO maps in a Jupyter notebook using DataFrames or hosted data
  • Augment your data with CARTO’s Data Observatory
  • Use CARTO for cloud-based analysis
  • Try it out without needing a CARTO account by using the Examples functionality

Common Uses

  • Visualize spatial data programmatically as matplotlib images, as notebook-embedded interactive maps, or published map visualizations
  • Perform cloud-based spatial data processing using CARTO’s analysis tools
  • Extract, transform, and Load (ETL) data using the Python ecosystem for getting data into and out of CARTO
  • Data Services integrations using CARTO’s Location Data Streams

Try it out

The easiest way to try out cartoframes is to use the cartoframes example notebooks running in binder: If you already have an API key, you can follow along and complete all of the example notebooks.

If you do not have an API key, you can still use cartoframes for creating maps locally.


The example context only provides read access, so not all cartoframes features are available. For full access, Start a free 14 day trial or get free access with a GitHub Student Developer Pack.

More info


cartoframes users must have a CARTO API key for most cartoframes functionality. For example, writing DataFrames to an account, reading from private tables, and visualizing data on maps all require an API key. CARTO provides API keys for education and nonprofit uses, among others. Request access at API key access is also given through GitHub’s Student Developer Pack.

Install Instructions

To install cartoframes on your machine, do the following to install the latest version:

$ pip install cartoframes

cartoframes is continuously tested on Python versions 2.7, 3.5, and 3.6. It is recommended to use cartoframes in Jupyter Notebooks (pip install jupyter). See the example usage section below or notebooks in the examples directory for using cartoframes in that environment.

Virtual Environment

Using virtualenv

Make sure your virtualenv package is installed and up-to-date. See the official Python packaging page for more information.

To setup cartoframes and Jupyter in a virtual environment:

$ virtualenv venv
$ source venv/bin/activate
(venv) $ pip install cartoframes jupyter
(venv) $ jupyter notebook

Then create a new notebook and try the example code snippets below with tables that are in your CARTO account.

Using pipenv

Alternatively, pipenv provides an easy way to manage virtual environments. The steps below are:

  1. Create a virtual environment with Python 3.4+ (recommended instead of Python 2.7)
  2. Install cartoframes and Jupyter (optional) into the virtual environment
  3. Enter the virtual environment
  4. Launch a Jupyter notebook server
$ pipenv --three
$ pipenv install cartoframes jupyter
$ pipenv run jupyter notebook

Native pip

If you install packages at a system level, you can install cartoframes with:

$ pip install cartoframes

Example usage

Data workflow

Get table from CARTO, make changes in pandas, sync updates with CARTO:

from cartoframes.auth import set_default_context
from import Dataset

# `base_url`s are of the form `` for most users
    api_key='your API key'

# create a dataset object
d = Dataset.from_table('brooklyn_poverty_census_tracts')

# read a table from your CARTO account to a DataFrame
df =

# perform operations on you dataframe
df['poverty_per_pop'] = df['poverty_count'] / df['total_population']

# update CARTO table with all changes from this session
d_updated = Dataset.from_dataframe(df)

Map workflow

There are two types of maps in CARTOframes: vector using CARTO VL and raster using CARTO.js. Vector maps are currently available as interactive HTML documents which can be displayed in a notebook, exported to an HTML file, or published to CARTO’s platform. The raster-based maps can be displayed interactively in a notebook or as static matplotlib images.

CARTO VL-based Maps

Interactive vector maps can be created programmatically in CARTOframes. In addition to hosted tables and queries, these maps can also display geographic information in pandas DataFrames and geopandas GeoDataFrames. This means that these maps do not need to be tied to a CARTO account (i.e., no need for an API key).

from cartoframes.viz import Map
from cartoframes.viz.helpers import color_continuous_layer
from cartoframes.auth import set_default_context


# display map in a notebook
Map(color_continuous_layer('brooklyn_poverty', 'poverty_per_pop'))

Publish map to CARTO

from cartoframes.viz import Map
from cartoframes.viz.helpers import color_continuous_layer
from cartoframes.auth import set_default_context

    api_key='your api key'

# display map in a notebook
bk_map = Map(color_continuous_layer('brooklyn_poverty', 'poverty_per_pop'))
bk_map.publish('Brooklyn Poverty')

This will publish a map like this one.

CARTO.js-based Maps

The following will embed a CARTO map in a Jupyter notebook, allowing for custom styling of the maps driven by TurboCARTO and CARTOColors. See the CARTOColors wiki for a full list of available color schemes.

from cartoframes import Layer, BaseMap, styling
cc = cartoframes.CartoContext(base_url=BASEURL,
                     color={'column': 'simpson_index',
                            'scheme': styling.tealRose(5)}),
                     color={'column': 'bird_id',
                            'scheme': styling.vivid(10)})],

Data Observatory

Interact with CARTO’s Data Observatory:

import cartoframes
cc = cartoframes.CartoContext(BASEURL, APIKEY)

# total pop, high school diploma (normalized), median income, poverty status (normalized)
# See Data Observatory catalog for codes:
data_obs_measures = [{'numer_id': 'us.census.acs.B01003001'},
                     {'numer_id': 'us.census.acs.B15003017',
                      'normalization': 'predenominated'},
                     {'numer_id': 'us.census.acs.B19013001'},
                     {'numer_id': 'us.census.acs.B17001002',
                      'normalization': 'predenominated'},]
df ='transactions', data_obs_measures)

CARTO Credential Management

Typical usage

The most common way to input credentials into cartoframes is through the CartoContext, as below. Replace {your_user_name} with your CARTO username and {your_api_key} with your API key, which you can find at https://{your_user_name}

from cartoframes import CartoContext
cc = CartoContext(

You can also set your credentials using the Credentials class:

from cartoframes import Credentials, CartoContext
cc = CartoContext(
    creds=Credentials(key='{your_api_key}', username='{your_user_name}')

Save/update credentials for later use

from cartoframes import Credentials, CartoContext
creds = Credentials(username='eschbacher', key='abcdefg')  # save credentials for later use (not dependent on Python session)

Once you save your credentials, you can get started in future sessions more quickly:

from cartoframes import CartoContext
cc = CartoContext()  # automatically loads credentials if previously saved