CARTOframes

Data Management

In this guide you will learn how to load different data files into DataFrames and how to interact with the CARTO platform to upload DataFrames into tables and download tables or SQL queries into DataFrames.

CARTOframes is built on top of Pandas and GeoPandas. Therefore, it’s compatible with all the data formats supported in those projects like GeoJSON, Shapefile, CSV, etc.

There are two main concepts we should know before continuing with the guide:

• A DataFrame is a two-dimensional data structure for generic data. It can be thought of as a table with rows and columns. It’s composed of Series objects, which are one-dimensional data structures.
• A GeoDataFrame is a DataFrame with an extra geometry column. This geometry column is a GeoSeries object.

Every time we manage geographic data, a GeoDataFrame should be used. In case a DataFrame with an encoded geometry column is used (WKB, WKT, etc.), every method contains a geom_col param to provide the name of that column and decode the geometry internally.

For further learning you can checkout the Data Management examples.

Read a GeoJSON file

This is how to load geographic data from a GeoJSON file using GeoPandas. To read pure JSON files check this example.

1
2
3
4
from geopandas import read_file

gdf = read_file('https://libs.cartocdn.com/cartoframes/samples/starbucks_brooklyn_geocoded.geojson')
gdf.head()

Read a Shapefile

Shapefile is a complex format, compared to CSV or GeoJSON. To learn more about this format check GeoPandas documentation.

1
2
3
4
from geopandas import read_file

gdf = read_file('https://libs.cartocdn.com/cartoframes/samples/starbucks_brooklyn_geocoded.zip')
gdf.head()

Read a CSV file

Compute geometry from longitude and latitude

1
2
3
4
5
6
7
from pandas import read_csv
from geopandas import GeoDataFrame, points_from_xy

df = read_csv('https://libs.cartocdn.com/cartoframes/samples/sf_incidents.csv')

gdf = GeoDataFrame(df, geometry=points_from_xy(df['longitude'], df['latitude']))
gdf.head()

Compute geometry from WKT/WKB

1
2
3
4
5
6
7
8
from pandas import read_csv
from geopandas import GeoDataFrame
from cartoframes.utils import decode_geometry

df = read_csv('https://libs.cartocdn.com/cartoframes/samples/starbucks_brooklyn_geocoded.csv')

gdf = GeoDataFrame(df, geometry=decode_geometry(df['the_geom']))
gdf.head()

Read data from a CARTO table

Note: You’ll need your CARTO Account credentials to perform this action.

1
2
3
from cartoframes.auth import set_default_credentials

set_default_credentials('cartoframes')

1
2
3
4
from cartoframes import read_carto

gdf = read_carto('starbucks_brooklyn')
gdf.head()

Read data from a CARTO SQL Query

Note: You’ll need your CARTO Account credentials to perform this action.

1
2
3
from cartoframes.auth import set_default_credentials

set_default_credentials('cartoframes')

1
2
3
4
from cartoframes import read_carto

gdf = read_carto("SELECT * FROM starbucks_brooklyn WHERE revenue > 1200000")
gdf.head()

Upload data to CARTO

Note: You’ll need your CARTO Account credentials to perform this action.

1
2
3
from cartoframes.auth import set_default_credentials

set_default_credentials('creds.json')

1
2
3
from cartoframes import to_carto

to_carto(gdf, 'starbucks_brooklyn_filtered', if_exists='replace')

1
2
3
4
5
6
7
Success! Data uploaded to table "starbucks_brooklyn_filtered" correctly





'starbucks_brooklyn_filtered'