CARTOframes

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

What is CARTOframes?

CARTOframes is a Python package for integrating CARTO maps, data observatory, data services and analyses into data science workflows. It also allows you to share your work from your work environment.

To understand the fundamentals of CARTOframes, read the guides. To go deeper, read the full reference API. To check snippets that go straight to the point, check the examples. To view the source code, browse the open-source repository and contribute. Also, if you see something is not working or you have any doubt, check the different support options.

Guides

Quick reference guides for learning how to use CARTOframes features.

Reference

Browse the interactive API documentation to search for specific CARTOframes methods, arguments, and sample code that can be used to build your applications.

Check Full Reference API
1
2
3
4
5
6
7
8
9
10
from cartoframes.auth import set_default_credentials
from cartoframes.data.observatory import Enrichment

set_default_credentials('creds.json')
enrichment = Enrichment()

enriched_df = enrichment.enrich_points(
    df,
    variables=['total_pop_3cf008b3']
)

Examples

Play with real examples and learn by doing.

Load data from a CSV file

This example illustrates how to load data from a CSV file using the pandas library.

In [1]:
from pandas import read_csv
from geopandas import GeoDataFrame, points_from_xy

remote_file_path = 'http://data.sfgov.org/resource/wg3w-h783.csv'

df = read_csv(remote_file_path)

# Clean latitude and longitude values that are NaN
df = df[df.longitude == df.longitude]
df = df[df.latitude == df.latitude]

gdf = GeoDataFrame(df, geometry=points_from_xy(df['longitude'], df['latitude']))
gdf.head()
Out[1]:
incident_datetime incident_date incident_time incident_year incident_day_of_week report_datetime row_id incident_id incident_number cad_number ... :@computed_region_6qbp_sg9q :@computed_region_qgnn_b9vv :@computed_region_26cr_cadq :@computed_region_ajp5_b2md :@computed_region_nqbw_i6c3 :@computed_region_2dwj_jsy4 :@computed_region_h4ep_8xdi :@computed_region_y6ts_4iup :@computed_region_jg9y_a9du geometry
2 2019-10-04T14:25:00.000 2019-10-04T00:00:00.000 14:25 2019 Friday 2019-10-04T16:13:00.000 85442603474 854426 190746203 192772728.0 ... 8.0 8.0 4.0 29.0 NaN NaN NaN NaN NaN POINT (-122.51129 37.77508)
3 2019-10-03T19:30:00.000 2019-10-03T00:00:00.000 19:30 2019 Thursday 2019-10-03T23:25:00.000 85419706244 854197 190744514 192764437.0 ... 28.0 3.0 5.0 5.0 5.0 NaN NaN NaN NaN POINT (-122.42746 37.76877)
4 2019-10-04T16:53:00.000 2019-10-04T00:00:00.000 16:53 2019 Friday 2019-10-04T16:53:00.000 85446351040 854463 190746532 192772932.0 ... 6.0 8.0 4.0 29.0 NaN NaN NaN NaN NaN POINT (-122.50309 37.78118)
5 2019-10-02T14:10:00.000 2019-10-02T00:00:00.000 14:10 2019 Wednesday 2019-10-02T22:59:00.000 85425706224 854257 196208142 NaN ... 99.0 6.0 3.0 23.0 NaN NaN NaN NaN NaN POINT (-122.41050 37.80696)
6 2018-10-05T16:15:00.000 2018-10-05T00:00:00.000 16:15 2018 Friday 2018-10-05T16:15:00.000 72248630200 722486 180755377 182782753.0 ... 112.0 7.0 5.0 3.0 NaN 31.0 NaN NaN NaN POINT (-122.44281 37.76601)

5 rows × 36 columns

In [2]:
from cartoframes.viz import Layer

Layer(gdf)
Out[2]:

Load data from a JSON file

This example illustrates how to load data from a remote JSON file using pandas and the process of preparing the data for spatial operations.

In [1]:
import requests

# Download the JSON file
remote_file_path = 'http://opendata.paris.fr/api/records/1.0/search/?dataset=arbresremarquablesparis&rows=200'
data_json = requests.get(remote_file_path).json()['records']
data_json[0].keys()
Out[1]:
dict_keys(['datasetid', 'recordid', 'fields', 'geometry', 'record_timestamp'])
In [2]:
from pandas.io.json import json_normalize

# Normalize the data
df = json_normalize(data_json)
df.head()
Out[2]:
datasetid recordid record_timestamp fields.geom_x_y fields.libellefrancais fields.objectid fields.idemplacement fields.arrondissement fields.typeemplacement fields.hauteurenm ... fields.pepiniere fields.remarquable fields.idbase fields.genre fields.varieteoucultivar fields.complementadresse fields.domanialite fields.dateplantation geometry.type geometry.coordinates
0 arbresremarquablesparis 432c06dfe0c4d212928a45e5d860f6cd5337c178 2019-12-27T11:00:27.207000+00:00 [48.8731110898, 2.24886478886] Hêtre 57346 000701004 BOIS DE BOULOGNE Arbre 16.0 ... Inconnue 1 2002354.0 Fagus ''Pendula'' 16-17 Jardin 1868-01-01T00:09:21+00:00 Point [2.24886478886, 48.8731110898]
1 arbresremarquablesparis 5c4b6b12f5e8d7cae07add17bc62d01e9e5d7fb0 2019-12-27T11:00:27.207000+00:00 [48.8691331657, 2.27224829769] Chicot du Canada 104688 00000007 PARIS 16E ARRDT Arbre 12.0 ... Inconnue 1 139108.0 Gymnocladus NaN 16-42 Jardin 1700-01-01T00:09:21+00:00 Point [2.27224829769, 48.8691331657]
2 arbresremarquablesparis fba1531e11191d052acd9a8c45a54665b670b55a 2019-12-27T11:00:27.207000+00:00 [48.839886234, 2.43388312679] Hêtre 109076 12-22 BOIS DE VINCENNES Arbre 16.0 ... Inconnue 1 2002372.0 Fagus ''Pendula'' 12-22 Jardin 1864-01-01T00:09:21+00:00 Point [2.43388312679, 48.839886234]
3 arbresremarquablesparis 42137814624d56acb885b44e344efcdcc952ad07 2019-12-27T11:00:27.207000+00:00 [48.821579307, 2.45494663547] Orme de Sibérie 209505 12-21 BOIS DE VINCENNES Arbre 18.0 ... Inconnue 1 2002381.0 Zelkova NaN 12-21 Jardin 2000-01-01T01:00:00+00:00 Point [2.45494663547, 48.821579307]
4 arbresremarquablesparis 1dad8e2a1f41cb8729aa3d28fb5ecf00532d6c66 2019-12-27T11:00:27.207000+00:00 [48.8201255055, 2.4451177535] Cèdre 49063 12-16 BOIS DE VINCENNES Arbre 22.0 ... Inconnue 1 2002384.0 Cedrus NaN 12-16 Jardin 1829-01-01T00:09:21+00:00 Point [2.4451177535, 48.8201255055]

5 rows × 24 columns

In [3]:
# Add Latitude and Longitude columns
df['lng'] = df.apply(lambda row: row['geometry.coordinates'][0], axis=1)
df['lat'] = df.apply(lambda row: row['geometry.coordinates'][1], axis=1)
df.head()
Out[3]:
datasetid recordid record_timestamp fields.geom_x_y fields.libellefrancais fields.objectid fields.idemplacement fields.arrondissement fields.typeemplacement fields.hauteurenm ... fields.idbase fields.genre fields.varieteoucultivar fields.complementadresse fields.domanialite fields.dateplantation geometry.type geometry.coordinates lng lat
0 arbresremarquablesparis 432c06dfe0c4d212928a45e5d860f6cd5337c178 2019-12-27T11:00:27.207000+00:00 [48.8731110898, 2.24886478886] Hêtre 57346 000701004 BOIS DE BOULOGNE Arbre 16.0 ... 2002354.0 Fagus ''Pendula'' 16-17 Jardin 1868-01-01T00:09:21+00:00 Point [2.24886478886, 48.8731110898] 2.248865 48.873111
1 arbresremarquablesparis 5c4b6b12f5e8d7cae07add17bc62d01e9e5d7fb0 2019-12-27T11:00:27.207000+00:00 [48.8691331657, 2.27224829769] Chicot du Canada 104688 00000007 PARIS 16E ARRDT Arbre 12.0 ... 139108.0 Gymnocladus NaN 16-42 Jardin 1700-01-01T00:09:21+00:00 Point [2.27224829769, 48.8691331657] 2.272248 48.869133
2 arbresremarquablesparis fba1531e11191d052acd9a8c45a54665b670b55a 2019-12-27T11:00:27.207000+00:00 [48.839886234, 2.43388312679] Hêtre 109076 12-22 BOIS DE VINCENNES Arbre 16.0 ... 2002372.0 Fagus ''Pendula'' 12-22 Jardin 1864-01-01T00:09:21+00:00 Point [2.43388312679, 48.839886234] 2.433883 48.839886
3 arbresremarquablesparis 42137814624d56acb885b44e344efcdcc952ad07 2019-12-27T11:00:27.207000+00:00 [48.821579307, 2.45494663547] Orme de Sibérie 209505 12-21 BOIS DE VINCENNES Arbre 18.0 ... 2002381.0 Zelkova NaN 12-21 Jardin 2000-01-01T01:00:00+00:00 Point [2.45494663547, 48.821579307] 2.454947 48.821579
4 arbresremarquablesparis 1dad8e2a1f41cb8729aa3d28fb5ecf00532d6c66 2019-12-27T11:00:27.207000+00:00 [48.8201255055, 2.4451177535] Cèdre 49063 12-16 BOIS DE VINCENNES Arbre 22.0 ... 2002384.0 Cedrus NaN 12-16 Jardin 1829-01-01T00:09:21+00:00 Point [2.4451177535, 48.8201255055] 2.445118 48.820126

5 rows × 26 columns

In [4]:
from geopandas import GeoDataFrame, points_from_xy

gdf = GeoDataFrame(df, geometry=points_from_xy(df['lng'], df['lat']))
gdf.head()
Out[4]:
datasetid recordid record_timestamp fields.geom_x_y fields.libellefrancais fields.objectid fields.idemplacement fields.arrondissement fields.typeemplacement fields.hauteurenm ... fields.genre fields.varieteoucultivar fields.complementadresse fields.domanialite fields.dateplantation geometry.type geometry.coordinates lng lat geometry
0 arbresremarquablesparis 432c06dfe0c4d212928a45e5d860f6cd5337c178 2019-12-27T11:00:27.207000+00:00 [48.8731110898, 2.24886478886] Hêtre 57346 000701004 BOIS DE BOULOGNE Arbre 16.0 ... Fagus ''Pendula'' 16-17 Jardin 1868-01-01T00:09:21+00:00 Point [2.24886478886, 48.8731110898] 2.248865 48.873111 POINT (2.24886 48.87311)
1 arbresremarquablesparis 5c4b6b12f5e8d7cae07add17bc62d01e9e5d7fb0 2019-12-27T11:00:27.207000+00:00 [48.8691331657, 2.27224829769] Chicot du Canada 104688 00000007 PARIS 16E ARRDT Arbre 12.0 ... Gymnocladus NaN 16-42 Jardin 1700-01-01T00:09:21+00:00 Point [2.27224829769, 48.8691331657] 2.272248 48.869133 POINT (2.27225 48.86913)
2 arbresremarquablesparis fba1531e11191d052acd9a8c45a54665b670b55a 2019-12-27T11:00:27.207000+00:00 [48.839886234, 2.43388312679] Hêtre 109076 12-22 BOIS DE VINCENNES Arbre 16.0 ... Fagus ''Pendula'' 12-22 Jardin 1864-01-01T00:09:21+00:00 Point [2.43388312679, 48.839886234] 2.433883 48.839886 POINT (2.43388 48.83989)
3 arbresremarquablesparis 42137814624d56acb885b44e344efcdcc952ad07 2019-12-27T11:00:27.207000+00:00 [48.821579307, 2.45494663547] Orme de Sibérie 209505 12-21 BOIS DE VINCENNES Arbre 18.0 ... Zelkova NaN 12-21 Jardin 2000-01-01T01:00:00+00:00 Point [2.45494663547, 48.821579307] 2.454947 48.821579 POINT (2.45495 48.82158)
4 arbresremarquablesparis 1dad8e2a1f41cb8729aa3d28fb5ecf00532d6c66 2019-12-27T11:00:27.207000+00:00 [48.8201255055, 2.4451177535] Cèdre 49063 12-16 BOIS DE VINCENNES Arbre 22.0 ... Cedrus NaN 12-16 Jardin 1829-01-01T00:09:21+00:00 Point [2.4451177535, 48.8201255055] 2.445118 48.820126 POINT (2.44512 48.82013)

5 rows × 27 columns

In [5]:
from cartoframes.viz import Layer

Layer(gdf)
Out[5]:

Load data from a GeoJSON file

This example illustrates how to load data from a GeoJSON file using geopandas.

In [1]:
from geopandas import read_file

gdf = read_file('http://libs.cartocdn.com/cartoframes/files/sustainable_palm_oil_production_mills.geojson')
gdf.head()
Out[1]:
objectid cartodb_id entity_id latitude longitude audit_stat legal_radi illegal_ra radius_umd radius_for ... carbon_r_3 peat_for_2 peat_for_3 primary_10 primary_11 mill_name parent_com rspo_certi date_updat geometry
0 1 59 ID1822 -1.585833 103.205556 ASA 1 0 0.321764 0.225759 1099 ... 1224 0 29 0.004508 0.135391 Muara Bulian Mill PT Inti Indosawit Subur yes 14-Aug POINT (103.20556 -1.58583)
1 2 153 ID1847 0.077043 102.030838 Renewal Certification 0 0.445960 0.258855 1979 ... 2038 7 523 0.017304 0.321418 Pabrik Kelapa Sawit Batang Kulim POM PT Musim Mas yes 14-Aug POINT (102.03084 0.07704)
2 3 103 ID1720 1.660222 100.590611 Initial Certification 0 0.498531 0.248520 1432 ... 1518 0 476 0.000811 0.193365 Kayangan and Kencana POM PT Salim Ivomas Pratama Tbk yes 14-Aug POINT (100.59061 1.66022)
3 4 216 ID1945 -2.894444 112.543611 ASA 1 0 0.662863 0.186332 226 ... 269 59 66 0.124882 0.189169 PT Sarana Titian Permata POM Wilmar International Ltd yes 14-Aug POINT (112.54361 -2.89444)
4 5 156 ID1553 3.593333 98.947222 Initial Certification 0 0.533668 0.028972 382 ... 412 0 0 0.000216 0.009296 Adolina POM PT Perkebunan Nusantara IV (PERSERO) yes 14-Aug POINT (98.94722 3.59333)

5 rows × 73 columns

In [2]:
from cartoframes.viz import Layer

Layer(gdf)
Out[2]:

Support

Get help or learn about known issues.