Examples¶
This developer guide is not intended to be an extensive list of usage examples and use cases. For that, inside the examples folder of the carto-python Github repository there are sample code snippets of the carto-python client.
To run examples, you should need to install additional dependencies:
pip install -r examples/requirements.txt
carto-python examples need to setup environment variables.
- CARTO_ORG: The name of your organization
- CARTO_API_URL: The base_url including your user and/or organization
- CARTO_API_KEY: Your user API key
Please refer to the examples source code for additional info about parameters of each one
List of examples¶
Find below a list of provided examples of the carto-python library.
Take into account that the examples are not intended to provide a comprehensive list of the capabilities of carto-python but only some of its use cases.
change_dataset_privacy.py¶
Description: Changes the privacy of a user’s dataset to ‘LINK’, ‘PUBLIC’ or ‘PRIVATE’
Usage example:
python change_dataset_privacy.py tornados LINK
Output:
12:17:01 PM - INFO - Done!
check_query.py¶
Description: Analyzes an SQL query to check if it can be optimized
Usage example:
python check_query.py "select version()"
Output:
12:25:18 PM - INFO - {u'QUERY PLAN': u'Result (cost=0.00..0.00 rows=1 width=0) (actual time=0.002..0.002 rows=1 loops=1)'}
12:25:18 PM - INFO - {u'QUERY PLAN': u'Planning time: 0.006 ms'}
12:25:18 PM - INFO - {u'QUERY PLAN': u'Execution time: 0.008 ms'}
12:25:18 PM - INFO - time: 0.002
create_anonymous_map.py¶
Description: Creates an anonymous map
Usage example:
python create_anonymous_map.py "files/anonymous_map.json"
Output:
Anonymous map created with layergroupid: 50b159d8a635c94fdfd100bdc7d8fb08:1493192847307
create_named_map.py¶
Description: Creates an anonymous map
Usage example:
python create_named_map.py "files/named_map.json"
Output:
Named map created with ID: python_sdk_test_map
export_create_tables.py¶
Description: Runs a SQL query to export the CREATE TABLE scripts of the user’s datasets
Usage example:
python export_create_datasets.py
Output:
...
Found dataset: test_12
Found dataset: tornados_24
Script exported
export_dataset.py¶
Description: Exports a dataset in a given format
Usage example:
python export_dataset.py --dataset=tornados --format=csv
Output:
File saved: tornados.csv
export_map.py¶
Description: Exports a map visualization as a .carto file
Usage example:
python export_map.py "Untitled map"
Output:
URL of .carto file is: http://s3.amazonaws.com/com.cartodb.imports.production/ ... .carto
import_and_merge.py¶
Description: Import a folder with CSV files (same structure) and merge them into one dataset. Files must be named as file1.csv, file2.csv, file3.csv, etc.
Usage example:
python import_and_merge.py "files/*.csv"
Output:
12:37:42 PM - INFO - Table imported: barris_barcelona_1_part_1
12:37:53 PM - INFO - Table imported: barris_barcelona_1_part_2
12:38:05 PM - INFO - Table imported: barris_barcelona_1_part_3
12:38:16 PM - INFO - Table imported: barris_barcelona_1_part_4
12:38:27 PM - INFO - Table imported: barris_barcelona_1_part_5
12:38:38 PM - INFO - Table imported: barris_barcelona_1_part_6
12:38:49 PM - INFO - Table imported: barris_barcelona_1_part_7
12:39:22 PM - INFO - Tables merged
URL of dataset is: https://YOUR_ORG.carto.com/u/YOUR_USER/dataset/barris_barcelona_1_part_1_merged
import_from_database.py¶
Description: External database connector
Usage example:
python import_from_database.py --connection='{
"connector": {
"provider": "hive",
"connection": {
"server":"YOUR_SERVER_IP",
"database":"default",
"username":"cloudera",
"password":"cloudera"
},
"schema": "default",
"table": "YOUR_TABLE"
}
}'
Output:
Table imported: YOUR_TABLE
import_standard_table.py¶
Description: Creates a CARTO dataset from a URL
Usage example:
python import_standard_table.py files/barris_barcelona_1_part_1.csv
Output:
12:46:00 PM - INFO - Name of table: barris_barcelona_1_part_1
URL of dataset: https://YOUR_ORG.carto.com/u/YOUR_USER/dataset/barris_barcelona_1_part_1
import_sync_table_as_dataset.py¶
Description: Creates a CARTO sync dataset from a URL
Usage example:
python import_sync_table_as_dataset.py "https://academy.cartodb.com/d/tornadoes.zip" 900
Output:
12:48:08 PM - INFO - Name of table: tornados
URL of dataset is: https://YOUR_ORG.carto.com/u/YOUR_USER/dataset/tornados
import_sync_table.py¶
Description: Creates a CARTO sync dataset from a URL
Usage example:
python import_sync_table.py "https://academy.cartodb.com/d/tornadoes.zip" 900
instantiate_named_map.py¶
Description: Instantiates a named map
Usage example:
python instantiate_named_map.py "python_sdk_test_map" "files/instantiate_map.json" "example_token"
Output:
Done!
kill_query.py¶
Description: Kills a running query
Usage example:
python kill_query.py 999
Output:
Query killed
list_tables.py¶
Description: Returns graph of tables ordered by size and indicating if they are cartodbfied or not
Usage example:
python list_tables.py
Output:
...
analysis_a08f3b6124_a49b778b1e146f4bc7e5e670f5edcb027513ddc5 NO: | 0.01 MB;
analysis_971639c870_c0421831d5966bcff0731772b21d6835294c4b0a NO: | 0.01 MB;
analysis_9e88a1147e_5da714d5786b61509da4ebcd1409aae05ea8704d NO: | 0.01 MB;
testing_moving NO: | 0.0 MB;
analysis_7530d60ffc_868bfea631fa1dc8c212ad2a8a950e050607aa6c NO: | 0.0 MB;
There are: 338 datasets in this account
map_info.py¶
Description: Return the names of all maps or display information from a specific map
Usage example:
python map_info.py
Output:
12:58:28 PM - INFO - data_2_1_y_address_locations map 1
12:58:28 PM - INFO - Untitled Map 2
12:58:28 PM - INFO - Untitled map
12:58:28 PM - INFO - Untitled Map
12:58:28 PM - INFO - cartodb_germany 1
12:58:28 PM - INFO - cb_2013_us_county_500k 1
Usage example:
python map_info.py --map="Untitled map"
Output:
{ 'active_layer_id': u'5a89b00d-0a86-4a8d-a359-912458ad05c9',
'created_at': u'2016-07-11T08:50:15+00:00',
'description': None,
'display_name': None,
'id': u'7cb87e6a-4744-11e6-9b1b-0e3ff518bd15',
'liked': False,
'likes': 0,
'locked': False,
'map_id': u'7820995a-98b8-4465-9c3d-607fd5f6fa67',
'name': u'Untitled map',
'related_tables': [<carto.tables.Table object at 0x10aece5d0>],
'table': <carto.tables.Table object at 0x10acb6c90>,
'title': None,
'updated_at': u'2016-07-11T08:50:19+00:00',
'url': u'https://YOUR_ORG.carto.com/u/YOUR_USER/viz/7cb87e6a-4744-11e6-9b1b-0e3ff518bd15/map'
}
running_queries.py¶
Description: Returns the running queries of the account
Usage example:
python running_queries.py
Output:
01:00:49 PM - INFO - {u'query': u'select pid, query from pg_stat_activity WHERE usename = current_user', u'pid': 2810}
sql_batch_api_jobs.py¶
Description: Works with a Batch SQL API job
Usage example:
python sql_batch_api_jobs.py create --query="select CDB_CreateOverviews('my_table'::regclass)"
Output:
01:03:07 PM - INFO - status: pending
01:03:07 PM - INFO - job_id: 3a73d74d-cc7a-4faf-9c37-1bec05f4835e
01:03:07 PM - INFO - created_at: 2017-06-06T11:03:07.746Z
01:03:07 PM - INFO - updated_at: 2017-06-06T11:03:07.746Z
01:03:07 PM - INFO - user: YOUR_USER
01:03:07 PM - INFO - query: select CDB_CreateOverviews('my_table'::regclass)
Usage example:
python sql_batch_api_jobs.py read --job_id=3a73d74d-cc7a-4faf-9c37-1bec05f4835e
Output:
01:04:03 PM - INFO - status: done
01:04:03 PM - INFO - job_id: 3a73d74d-cc7a-4faf-9c37-1bec05f4835e
01:04:03 PM - INFO - created_at: 2017-06-06T11:03:07.746Z
01:04:03 PM - INFO - updated_at: 2017-06-06T11:03:08.328Z
01:04:03 PM - INFO - user: YOUR_USER
01:04:03 PM - INFO - query: select CDB_CreateOverviews('my_table'::regclass)
Usage example:
python sql_batch_api_jobs.py cancel --job_id=3a73d74d-cc7a-4faf-9c37-1bec05f4835e
Output:
01:04:03 PM - INFO - status: cancelled
01:04:03 PM - INFO - job_id: 3a73d74d-cc7a-4faf-9c37-1bec05f4835e
01:04:03 PM - INFO - created_at: 2017-06-06T11:03:07.746Z
01:04:03 PM - INFO - updated_at: 2017-06-06T11:03:08.328Z
01:04:03 PM - INFO - user: YOUR_USER
01:04:03 PM - INFO - query: select CDB_CreateOverviews('my_table'::regclass)
table_info.py¶
Description: Return columns and its types, indexes, functions and triggers of a specific table
Usage example:
python table_info.py tornados
Output:
General information
+------------+----------------+------------------------+----------------------+---------------+
| Table name | Number of rows | Size of the table (MB) | Privacy of the table | Geometry type |
+------------+----------------+------------------------+----------------------+---------------+
| tornados | 14222 | 2.03 | PUBLIC | [u'ST_Point'] |
+------------+----------------+------------------------+----------------------+---------------+
The columns and their data types are:
+----------------------+------------------+
| Column name | Data type |
+----------------------+------------------+
| cartodb_id | bigint |
| the_geom | USER-DEFINED |
| the_geom_webmercator | USER-DEFINED |
| latitude | double precision |
| longitude | double precision |
| damage | numeric |
| _feature_count | integer |
+----------------------+------------------+
Indexes of the tables:
+-----------------------------------+----------------------------------------------------------------------------------------------+
| Index name | Index definition |
+-----------------------------------+----------------------------------------------------------------------------------------------+
| _auto_idx_tornados_damage | CREATE INDEX _auto_idx_tornados_damage ON tornados USING btree (damage) |
| tornados_the_geom_webmercator_idx | CREATE INDEX tornados_the_geom_webmercator_idx ON tornados USING gist (the_geom_webmercator) |
| tornados_the_geom_idx | CREATE INDEX tornados_the_geom_idx ON tornados USING gist (the_geom) |
| tornados_pkey | CREATE UNIQUE INDEX tornados_pkey ON tornados USING btree (cartodb_id) |
+-----------------------------------+----------------------------------------------------------------------------------------------+
Functions of the account:
+---------------+
| Function name |
+---------------+
+---------------+
Triggers of the account:
+-------------------------------------+
| Trigger Name |
+-------------------------------------+
| test_quota |
| test_quota_per_row |
| track_updates |
| update_the_geom_webmercator_trigger |
+-------------------------------------+
user_info.py¶
Description: Returns information from a specific user
Usage example:
export CARTO_USER=YOUR_USER
python user_info.py
Output:
The attributes of the user are:
+----------------------------+----------------------------------------------------------------------------------------------------------+
| Attribute | Value |
+----------------------------+----------------------------------------------------------------------------------------------------------+
| username | YOUR_USER |
| avatar_url | //cartodb-libs.global.ssl.fastly.net/cartodbui/assets/unversioned/images/avatars/avatar_pacman_green.png |
| quota_in_bytes | 20198485636 |
| public_visualization_count | 0 |
| base_url | https://YOUR_ORG.carto.com/u/YOUR_USER |
| table_count | 217 |
| all_visualization_count | 80 |
| client | <carto.auth.APIKeyAuthClient object at 0x102eac710> |
| soft_geocoding_limit | True |
| db_size_in_bytes | 13867610112 |
| email | XXX@yyy.zzz |
+----------------------------+----------------------------------------------------------------------------------------------------------+
The quotas of the user are:
+----------------+----------+------------------+------------+---------------+
| Service | Provider | Soft limit | Used quota | Monthly quota |
+----------------+----------+------------------+------------+---------------+
| isolines | 37 | heremaps | False | 100000 |
| hires_geocoder | 20238 | heremaps | False | 100000 |
| routing | 0 | mapzen | False | 200000 |
| observatory | 482896 | data observatory | False | 1000000 |
+----------------+----------+------------------+------------+---------------+