carto package API documentation¶

carto.auth module¶

Module for authenticated access to CARTO’s APIs

class carto.auth.APIKeyAuthClient(base_url, api_key, organization=None, session=None, client_id=None, user_agent=None)¶

Bases: carto.auth._UsernameGetter, carto.auth._BaseUrlChecker, carto.auth._ClientIdentifier, pyrestcli.auth.BaseAuthClient

This class provides you with authenticated access to CARTO’s APIs using your API key.

You can find your API key by clicking on the API key section of the user dropdown menu

prepare_send(http_method, **requests_args)¶

send(relative_path, http_method, **requests_args)¶

Makes an API-key-authorized request

Parameters:	relative_path (str) – URL path relative to self.base_url http_method (str) – HTTP method requests_args (kwargs) – kwargs to be sent to requests
Returns:	A request response object
Raise:	CartoException

class carto.auth.AuthAPIClient(base_url, api_key, organization=None, session=None)¶

Bases: carto.auth._UsernameGetter, carto.auth._BaseUrlChecker, pyrestcli.auth.BasicAuthClient

This class provides you with authenticated access to CARTO’s APIs using your API key at Basic authentication header, as provided by Auth API.

Auth API is still under development. You might want to take a look at APIKeyAuthClient for missing features or an stable API.

You can find your API key by clicking on the API key section of the user dropdown menu

is_valid_api_key()¶

Checks validity. Right now, an API key is considered valid if it can list user API keys and the result contains that API key. This might change in the future.

Returns:	True if the API key is considered valid for current user.

class carto.auth.NonVerifiedAPIKeyAuthClient(base_url, api_key, organization=None, session=None)¶

Bases: carto.auth.APIKeyAuthClient

This class provides you with authenticated access to CARTO’s APIs using your API key but avoids verifying SSL certificates. This is useful for onpremises instances of CARTO

You can find your API key by clicking on the API key section of the user dropdown menu

send(relative_path, http_method, **requests_args)¶

Makes an API-key-authorized request not verifying SSL certs

Parameters:	relative_path (str) – URL path relative to self.base_url http_method (str) – HTTP method requests_args (kwargs) – kwargs to be sent to requests
Returns:	A request response object
Raise:	CartoException

carto.api_keys module¶

Module for working with CARTO Auth API

https://carto.com/developers/auth-api/

class carto.api_keys.APIKey(auth_client, **kwargs)¶

Bases: pyrestcli.resources.Resource

Represents an API key in CARTO. API keys are used to grant permissions to tables and maps. See the Auth API reference for more info: https://carto.com/developers/auth-api/

class Meta¶

collection_endpoint = 'api/v3/api_keys/'¶

id_field = 'id'¶

json_data = True¶

name_field = 'name'¶

parse_json = True¶

created_at¶: Field to store datetimes in resources

fields = ['name', 'type', 'created_at', 'updated_at', 'token', 'grants']¶

grants¶: carto.api_keys.Grants

name¶: Convenient class to make explicit that an attribute will store chars

regenerate_token()¶

Regenerates the associated token

Returns:
Raise:	CartoException

token¶: Convenient class to make explicit that an attribute will store chars

type¶: Convenient class to make explicit that an attribute will store chars

updated_at¶: Field to store datetimes in resources

class carto.api_keys.APIKeyManager(auth_client)¶

Bases: carto.resources.Manager

Manager for the APIKey class.

create(name, apis=['sql', 'maps'], tables=None, services=None)¶

Creates a regular APIKey.

Parameters:	name (str) – The API key name apis (list) – Describes which APIs does this API Key provide access to tables (TableGrant or dict) – Describes to which tables and which privleges on each table this API Key grants access to services (list) – Describes to which data services this API Key grants access to
Returns:	An APIKey instance with a token

json_collection_attribute = 'result'¶

paginator_class¶: alias of carto.paginators.CartoPaginator

resource_class¶: alias of APIKey

class carto.api_keys.Grants(auth_client, **kwargs)¶

Bases: pyrestcli.resources.Resource

apis¶: Convenient class to make explicit that an attribute will store chars

fields = ['tables', 'apis', 'services']¶

get_id()¶

services¶: Convenient class to make explicit that an attribute will store chars

tables¶: carto.api_keys.TableGrant

class carto.api_keys.TableGrant(auth_client, **kwargs)¶

Bases: pyrestcli.resources.Resource

Describes to which tables and which privleges on each table this API Key grants access to trough tables attribute. This is an internal data type, with no specific API endpoints

See https://carto.com/developers/auth-api/reference/#section/API-Key-format

Example:

{
    "type": "database",
    "tables": [
        {
            "schema": "public",
            "name": "my_table",
            "permissions": [
                "insert",
                "select",
                "update"
            ]
        }
    ]
}

fields = ['name', 'permissions', 'schema']¶

name¶: Convenient class to make explicit that an attribute will store chars

permissions¶: Convenient class to make explicit that an attribute will store chars

schema¶: Convenient class to make explicit that an attribute will store chars

to_json()¶

carto.datasets module¶

Module for working with CARTO datasets

class carto.datasets.Dataset(auth_client, **kwargs)¶

Bases: carto.resources.WarnResource

Represents a dataset in CARTO. Typically, that means there is a table in the PostgreSQL server associated to this object.

Warning

Non-public API. It may change with no previous notice

class Meta¶

collection_endpoint = 'api/v1/viz/'¶

id_field = 'id'¶

json_data = True¶

name_field = 'name'¶

parse_json = True¶

active_child¶: Convenient class to make explicit that an attribute will store chars

active_layer_id¶: Convenient class to make explicit that an attribute will store chars

attributions¶: Convenient class to make explicit that an attribute will store chars

auth_tokens¶: Convenient class to make explicit that an attribute will store chars

children¶: Convenient class to make explicit that an attribute will store chars

connector¶: Convenient class to make explicit that an attribute will store chars

created_at¶: Field to store datetimes in resources

delete()¶: Deletes the resource from the server; Python object remains untouched :return:

dependent_visualizations¶: carto.visualizations.Visualization

dependent_visualizations_count¶: Convenient class to make explicit that an attribute will store integers

description¶: Convenient class to make explicit that an attribute will store chars

display_name¶: Convenient class to make explicit that an attribute will store chars

external_source¶: Convenient class to make explicit that an attribute will store chars

fields = ['dependent_visualizations', 'liked', 'prev_id', 'likes', 'active_layer_id', 'table', 'children', 'display_name', 'privacy', 'permission', 'id', 'connector', 'parent_id', 'next_id', 'type', 'external_source', 'map_id', 'description', 'tags', 'dependent_visualizations_count', 'updated_at', 'attributions', 'synchronization', 'user', 'stats', 'kind', 'locked', 'name', 'license', 'url', 'active_child', 'created_at', 'uses_builder_features', 'transition_options', 'source', 'auth_tokens', 'title']¶

force_delete()¶

id¶: Convenient class to make explicit that an attribute will store chars

kind¶: Convenient class to make explicit that an attribute will store chars

license¶: Convenient class to make explicit that an attribute will store chars

liked¶: Convenient class to make explicit that an attribute will store booleans

likes¶: Convenient class to make explicit that an attribute will store integers

locked¶: Convenient class to make explicit that an attribute will store booleans

map_id¶: Convenient class to make explicit that an attribute will store chars

name¶: Convenient class to make explicit that an attribute will store chars

next_id¶: Convenient class to make explicit that an attribute will store chars

parent_id¶: Convenient class to make explicit that an attribute will store chars

permission¶: carto.permissions.Permission

prev_id¶: Convenient class to make explicit that an attribute will store chars

privacy¶: Convenient class to make explicit that an attribute will store chars

source¶: Convenient class to make explicit that an attribute will store chars

stats¶: Field to store datetimes in resources

synchronization¶: carto.synchronizations.Synchronization

table¶: carto.tables.Table

tags¶: Convenient class to make explicit that an attribute will store chars

title¶: Convenient class to make explicit that an attribute will store chars

transition_options¶: Convenient class to make explicit that an attribute will store a dictionary

type¶: Convenient class to make explicit that an attribute will store chars

updated_at¶: Field to store datetimes in resources

url¶: Convenient class to make explicit that an attribute will store chars

user¶: carto.users.User

uses_builder_features¶: Convenient class to make explicit that an attribute will store booleans

class carto.datasets.DatasetManager(auth_client)¶

Bases: carto.resources.Manager

Manager for the Dataset class.

Warning

Non-public API. It may change with no previous notice

create(archive, interval=None, **import_args)¶

Creating a table means uploading a file or setting up a sync table

Parameters:	archive (str) – URL to the file (both remote URLs or local paths are supported) or StringIO object interval (int) – Interval in seconds. If not None, CARTO will try to set up a sync table against the (remote) URL import_args (kwargs) – Arguments to be sent to the import job when run
Returns:	New dataset object
Return type:	Dataset
Raise:	CartoException

is_sync_table(archive, interval, **import_args)¶

Checks if this is a request for a sync dataset.

The condition for creating a sync dataset is to provide a URL or a connection to an external database and an interval in seconds

Parameters:	archive – URL to the file (both remote URLs or local paths are supported) or StringIO object interval (int) – Interval in seconds. import_args (kwargs) – Connection parameters for an external database
Returns:	True if it is a sync dataset

json_collection_attribute = 'visualizations'¶

paginator_class¶: alias of carto.paginators.CartoPaginator

resource_class¶: alias of Dataset

send(url, http_method, **client_args)¶

Sends an API request, taking into account that datasets are part of the visualization endpoint.

Parameters:	url (str) – Endpoint URL http_method (str) – The method used to make the request to the API client_args (kwargs) – Arguments to be sent to the auth client
Returns:	A request response object
Raise:	CartoException

carto.exceptions module¶

Module for carto-python exceptions definitions

exception carto.exceptions.CartoException¶

Bases: exceptions.Exception

Any Exception produced by carto-python should be wrapped around this class

exception carto.exceptions.CartoRateLimitException(response)¶

Bases: carto.exceptions.CartoException

This exception is raised when a request is rate limited by SQL or Maps APIs (429 Too Many Requests HTTP error). More info about CARTO rate limits: https://carto.com/developers/fundamentals/limits/#rate-limits

It extends CartoException with the rate limits info, so that any client can manage when to retry a rate limited request.

static is_rate_limited(response)¶

Checks if the response has been rate limited by CARTO APIs

Parameters:	response (requests.models.Response class) – The response rate limited by CARTO APIs
Returns:	Boolean

carto.export module¶

Module for exporting visualizations

class carto.export.ExportJob(client, visualization_id)¶

Bases: carto.resources.WarnAsyncResource

Equivalent to a .carto export in CARTO.

Allows a CARTO export to be created using a visualization in the user’s CARTO account

Warning

Non-public API. It may change with no previous notice

class Meta¶

collection_endpoint = 'api/v3/visualization_exports/'¶

id_field = 'id'¶

json_data = True¶

name_field = 'id'¶

parse_json = True¶

created_at¶: Field to store datetimes in resources

fields = ['user_id', 'url', 'created_at', 'updated_at', 'state', 'visualization_id', 'id']¶

id¶: Convenient class to make explicit that an attribute will store chars

run(**export_params)¶

Make the actual request to the Import API (exporting is part of the Import API).

Parameters:	export_params (kwargs) – Any additional parameters to be sent to the Import API
Returns:

Note

The export is asynchronous, so you should take care of the progression, by calling the carto.resources.AsyncResource.refresh() method and check the export job state attribute. See carto.visualizations.Visualization.export() method implementation for more details

state¶: Convenient class to make explicit that an attribute will store chars

updated_at¶: Field to store datetimes in resources

url¶: Convenient class to make explicit that an attribute will store chars

user_id¶: Convenient class to make explicit that an attribute will store chars

visualization_id¶: Convenient class to make explicit that an attribute will store chars

carto.fields module¶

Module for defining response objects

class carto.fields.Base64EncodedField(many=False)¶: Bases: pyrestcli.fields.CharField

class carto.fields.EntityField(many=False)¶

Bases: pyrestcli.fields.ResourceField

carto.permissions.Entity

value_class = 'carto.permissions.Entity'¶

class carto.fields.GrantsField(many=False)¶

Bases: pyrestcli.fields.ResourceField

carto.api_keys.Grants

type_field = {'apis': 'apis', 'services': 'dataservices', 'tables': 'database'}¶

value_class = 'carto.api_keys.Grants'¶

class carto.fields.PasswordAndPrivacyFields(many=False)¶: Bases: pyrestcli.fields.CharField

class carto.fields.PermissionField(many=False)¶

Bases: pyrestcli.fields.ResourceField

carto.permissions.Permission

value_class = 'carto.permissions.Permission'¶

class carto.fields.SynchronizationField(many=False)¶

Bases: pyrestcli.fields.ResourceField

carto.synchronizations.Synchronization

value_class = 'carto.synchronizations.Synchronization'¶

class carto.fields.TableField(many=False)¶

Bases: pyrestcli.fields.ResourceField

carto.tables.Table

value_class = 'carto.tables.Table'¶

class carto.fields.TableGrantField(many=False)¶

Bases: pyrestcli.fields.ResourceField

carto.api_keys.TableGrant

value_class = 'carto.api_keys.TableGrant'¶

class carto.fields.UserField(many=False)¶

Bases: pyrestcli.fields.ResourceField

carto.users.User

value_class = 'carto.users.User'¶

class carto.fields.VisualizationField(many=False)¶

Bases: pyrestcli.fields.ResourceField

carto.visualizations.Visualization

value_class = 'carto.visualizations.Visualization'¶

carto.file_import module¶

Module for importing remote and local files into CARTO

class carto.file_import.FileImportJob(archive, auth_client)¶

Bases: carto.resources.AsyncResource

This class provides support for one-time uploading and importing of remote and local files into CARTO

class Meta¶

collection_endpoint = 'api/v1/imports/'¶

id_field = 'item_queue_id'¶

json_data = True¶

name_field = 'id'¶

parse_json = True¶

content_guessing¶: Convenient class to make explicit that an attribute will store booleans

create_visualization¶: Convenient class to make explicit that an attribute will store booleans

data_type¶: Convenient class to make explicit that an attribute will store chars

display_name¶: Convenient class to make explicit that an attribute will store chars

error_code¶: Convenient class to make explicit that an attribute will store integers

fields = ['quoted_fields_guessing', 'data_type', 'queue_id', 'user_defined_limits', 'item_queue_id', 'type_guessing', 'display_name', 'visualization_id', 'id', 'content_guessing', 'user_id', 'create_visualization', 'success', 'table_id', 'synchronization_id', 'is_raster', 'state', 'table_name', 'tables_created_count', 'error_code']¶

get_error_text = None¶

id¶: Convenient class to make explicit that an attribute will store chars

is_raster¶: Convenient class to make explicit that an attribute will store booleans

item_queue_id¶: Convenient class to make explicit that an attribute will store chars

queue_id¶: Convenient class to make explicit that an attribute will store chars

quoted_fields_guessing¶: Convenient class to make explicit that an attribute will store booleans

run(**import_params)¶

Actually creates the import job on the CARTO server

Parameters:	import_params (kwargs) – To be send to the Import API, see CARTO’s docs on Import API for an updated list of accepted params
Returns:

Note

The import job is asynchronous, so you should take care of the progression, by calling the carto.resources.AsyncResource.refresh() method and check the import job state attribute. See carto.datasets.DatasetManager.create() for a unified method to import files into CARTO

state¶: Convenient class to make explicit that an attribute will store chars

success¶: Convenient class to make explicit that an attribute will store booleans

synchronization_id¶: Convenient class to make explicit that an attribute will store chars

table_id¶: Convenient class to make explicit that an attribute will store chars

table_name¶: Convenient class to make explicit that an attribute will store chars

tables_created_count¶: Convenient class to make explicit that an attribute will store integers

type_guessing¶: Convenient class to make explicit that an attribute will store booleans

user_defined_limits¶: Convenient class to make explicit that an attribute will store chars

user_id¶: Convenient class to make explicit that an attribute will store chars

visualization_id¶: Convenient class to make explicit that an attribute will store chars

warnings = None¶

class carto.file_import.FileImportJobManager(auth_client)¶

Bases: carto.resources.Manager

create(archive, **kwargs)¶

Creates a file import on the server

Parameters:	archive (str) – archive can be a pointer to a remote location, a path to a local file or a StringIO object kwargs (kwargs) – Attributes (field names and values) of the new resource
Returns:	The `carto.file_import.FileImportJob`

filter()¶

Get a filtered list of file imports

Returns:	A list of file imports, with only the id set (you need to refresh them if you want all the attributes to be filled in)
Return type:	list of `carto.file_import.FileImportJob`
Raise:	CartoException

json_collection_attribute = 'imports'¶

paginator_class¶: alias of carto.paginators.CartoPaginator

resource_class¶: alias of FileImportJob

carto.maps module¶

Module for working with named and anonymous maps

class carto.maps.AnonymousMap(auth_client)¶

Bases: carto.maps.BaseMap

Equivalent to creating an anonymous map in CARTO.

class Meta¶

collection_endpoint = 'api/v1/map/'¶

id_field = 'id'¶

json_data = True¶

name_field = 'id'¶

parse_json = True¶

fields = []¶

instantiate(params)¶

Allows you to fetch the map tiles of a created map

Parameters:	params (dict) – The json with the styling info for the named map
Returns:
Raise:	CartoException

update_from_dict(attribute_dict)¶: Update the fields of the resource out of a data dictionary taken out of an API response :param attribute_dict: Dictionary to be mapped into object attributes :return:

class carto.maps.BaseMap(auth_client)¶

Bases: pyrestcli.resources.Resource

Base class for NamedMap and AnonymousMap

fields = []¶

get_tile_url(x, y, z, layer_id=None, feature_id=None, filter=None, extension='png')¶

Prepares a URL to get data (raster or vector) from a NamedMap or AnonymousMap

Parameters:	x (int) – The x tile y (int) – The y tile z (int) – The zoom level layer_id (str) – Can be a number (referring to the # layer of your map), all layers of your map, or a list of layers. To show just the basemap layer, enter the value 0 To show the first layer, enter the value 1 To show all layers, enter the value ‘all’ To show a list of layers, enter the comma separated layer value as ‘0,1,2’ feature_id (str) – The id of the feature filter (str) – The filter to be applied to the layer extension (str) – The format of the data to be retrieved: png, mvt, …
Returns:	A URL to download data
Return type:	str
Raise:	CartoException

class carto.maps.NamedMap(auth_client)¶

Bases: carto.maps.BaseMap

Equivalent to creating a named map in CARTO.

class Meta¶

collection_endpoint = 'api/v1/map/named/'¶

id_field = 'template_id'¶

json_data = True¶

name_field = 'name'¶

parse_json = True¶

fields = []¶

instantiate(params, auth=None)¶

Allows you to fetch the map tiles of a created map

Parameters:	params (dict) – The json with the styling info for the named map auth (`carto.auth.APIKeyAuthClient`) – The auth client
Returns:
Raise:	CartoException

update_from_dict(attribute_dict)¶: Method overriden from the base class

class carto.maps.NamedMapManager(auth_client)¶

Bases: pyrestcli.resources.Manager

Manager for the NamedMap class

create(**kwargs)¶

Creates a named map

Parameters:	kwargs (kwargs) – Attributes for creating the named map. Specifically an attribute template must contain the JSON object defining the named map
Returns:	New named map object
Return type:	NamedMap
Raise:	CartoException

json_collection_attribute = 'template_ids'¶

resource_class¶: alias of NamedMap

carto.paginators module¶

Used internally to retrieve results paginated

class carto.paginators.CartoPaginator(json_collection_attribute, base_url, params=None)¶

Bases: pyrestcli.paginators.Paginator

Used internally to retrieve results paginated

get_urls(initial_url)¶

process_response(response)¶

carto.permissions module¶

Entity classes for defining permissions

class carto.permissions.Entity(auth_client, **kwargs)¶

Bases: pyrestcli.resources.Resource

Represents an entity in CARTO. This is an internal data type, with no specific API endpoints

fields = ['type', 'id']¶

id¶: Convenient class to make explicit that an attribute will store chars

type¶: Convenient class to make explicit that an attribute will store chars

class carto.permissions.Permission(auth_client, **kwargs)¶

Bases: pyrestcli.resources.Resource

Represents a permission in CARTO. This is an internal data type, with no specific API endpoints

acl = None¶

created_at¶: Field to store datetimes in resources

entity¶: carto.permissions.Entity

fields = ['created_at', 'updated_at', 'entity', 'id', 'owner']¶

id¶: Convenient class to make explicit that an attribute will store chars

owner¶: carto.users.User

updated_at¶: Field to store datetimes in resources

carto.resources module¶

Extensions for pyrestcli Resource and Manager classes

class carto.resources.AsyncResource(auth_client, **kwargs)¶

Bases: pyrestcli.resources.Resource

fields = []¶

refresh()¶

Updates the information of the async job against the CARTO server. After calling the refresh() method you should check the state attribute of your resource

Returns:

run(**client_params)¶

Actually creates the async job on the CARTO server

Parameters:	client_params (kwargs) – To be send to the CARTO API. See CARTO’s documentation depending on the subclass you are using
Returns:
Raise:	CartoException

class carto.resources.Manager(auth_client)¶

Bases: pyrestcli.resources.Manager

Manager class for resources

class carto.resources.WarnAsyncResource(auth_client, **kwargs)¶

Bases: carto.resources.AsyncResource

AsyncResource class for resources that represent non-public CARTO APIs. You’ll be warned not to used the in production environments

fields = []¶

class carto.resources.WarnResource(auth_client, **kwargs)¶

Bases: pyrestcli.resources.Resource

Resource class for resources that represent non-public CARTO APIs. You’ll be warned not to used the in production environments

fields = []¶

carto.sql module¶

Module for the SQL API

class carto.sql.BatchSQLClient(client, api_version='v2')¶

Bases: object

Allows you to send requests to CARTO’s Batch SQL API

cancel(job_id)¶

Cancels a job

Parameters:	job_id (str) – The id of the job to be cancelled
Returns:	A status code depending on whether the cancel request was successful
Return type:	str
Raises:	CartoException –

create(sql_query)¶

Creates a new batch SQL query.

Batch SQL jobs are asynchronous, once created you should call carto.sql.BatchSQLClient.read() method given the job_id to retrieve the state of the batch query

Parameters:	sql_query (str or list of str) – The SQL query to be used
Returns:	Response data, either as json or as a regular response.content object
Return type:	object
Raise:	CartoException

create_and_wait_for_completion(sql_query)¶

Creates a new batch SQL query and waits for its completion or failure

Batch SQL jobs are asynchronous, once created this method automatically queries the job status until it’s one of ‘done’, ‘failed’, ‘canceled’, ‘unknown’

Parameters:	sql_query (str or list of str) – The SQL query to be used
Returns:	Response data, either as json or as a regular response.content object
Return type:	object
Raise:	CartoException when there’s an exception in the BatchSQLJob execution or the batch job status is one of the BATCH_JOBS_FAILED_STATUSES (‘failed’, ‘canceled’, ‘unknown’)

read(job_id)¶

Reads the information for a specific Batch API request

Parameters:	job_id (str) – The id of the job to be read from
Returns:	Response data, either as json or as a regular response.content object
Return type:	object
Raise:	CartoException

send(url, http_method, json_body=None, http_header=None)¶

Executes Batch SQL query in a CARTO server

Parameters:	url (str) – Endpoint url http_method (str) – The method used to make the request to the API json_body (dict) – The information that needs to be sent, by default is set to None http_header (str) – The header used to make write requests to the API, by default is none
Returns:	Response data, either as json or as a regular response.content object
Return type:	object
Raise:	CartoException

update(job_id, sql_query)¶

Updates the sql query of a specific job

Parameters:	job_id (str) – The id of the job to be updated sql_query (str) – The new SQL query for the job
Returns:	Response data, either as json or as a regular response.content object
Return type:	object
Raise:	CartoException

update_from_dict(data_dict)¶

Parameters:	data_dict (dict) – Dictionary to be mapped into object attributes
Returns:

class carto.sql.CopySQLClient(client, api_version='v2')¶

Bases: object

Allows to use the PostgreSQL COPY command for efficient streaming of data to and from CARTO.

copyfrom(query, iterable_data, compress=True, compression_level=1)¶

Gets data from an iterable object into a table

Parameters:	query (str) – The “COPY table_name [(column_name[, …])] FROM STDIN [WITH(option[,…])]” query to execute iterable_data (object) – An object that can be iterated to retrieve the data
Returns:	Response data as json
Return type:	str
Raises:	CartoException –

copyfrom_file_object(query, file_object, compress=True, compression_level=1)¶

Gets data from a readable file object into a table

Parameters:	query (str) – The “COPY table_name [(column_name[, …])] FROM STDIN [WITH(option[,…])]” query to execute file_object (file) – A file-like object. Normally the return value of open(‘file.ext’, ‘rb’)
Returns:	Response data as json
Return type:	str
Raises:	CartoException –

copyfrom_file_path(query, path, compress=True, compression_level=1)¶

Gets data from a readable file into a table

Parameters:	query (str) – The “COPY table_name [(column_name[, …])] FROM STDIN [WITH(option[,…])]” query to execute path (str) – A path to a file
Returns:	Response data as json
Return type:	str
Raises:	CartoException –

copyto(query)¶

Gets data from a table into a Response object that can be iterated

Parameters:	query (str) – The “COPY { table_name [(column_name[, …])] \| (query) } TO STDOUT [WITH(option[,…])]” query to execute
Returns:	response object
Return type:	Response
Raises:	CartoException –

copyto_file_object(query, file_object)¶

Gets data from a table into a writable file object

Parameters:	query (str) – The “COPY { table_name [(column_name[, …])] \| (query) } TO STDOUT [WITH(option[,…])]” query to execute file_object (file) – A file-like object. Normally the return value of open(‘file.ext’, ‘wb’)
Raises:	CartoException –

copyto_file_path(query, path, append=False)¶

Gets data from a table into a writable file

Parameters:	query (str) – The “COPY { table_name [(column_name[, …])] \| (query) } TO STDOUT [WITH(option[,…])]” query to execute path (str) – A path to a writable file append (bool) – Whether to append or not if the file already exists Default value is False
Raises:	CartoException –

copyto_stream(query)¶

Gets data from a table into a stream

Parameters:	query (str) – The “COPY { table_name [(column_name[, …])] \| (query) } TO STDOUT [WITH(option[,…])]” query to execute
Returns:	the data from COPY TO query
Return type:	raw binary (text stream)
Raise:	CartoException

class carto.sql.SQLClient(auth_client, api_version='v2')¶

Bases: object

Allows you to send requests to CARTO’s SQL API

send(sql, parse_json=True, do_post=True, format=None, **request_args)¶

Executes SQL query in a CARTO server

Parameters:	sql (str) – The SQL parse_json (boolean) – Set it to False if you want raw reponse do_post (boolean) – Set it to True to force post request format (str) – Any of the data export formats allowed by CARTO’s SQL API request_args (dictionary) – Additional parameters to send with the request
Returns:	response data, either as json or as a regular response.content object
Return type:	object
Raise:	CartoException

carto.sync_tables module¶

Module for the IMPORT API with sync tables

class carto.sync_tables.SyncTableJob(url, interval, auth_client)¶

Bases: carto.resources.AsyncResource

This class provides support for creating Sync Tables into CARTO

class Meta¶

collection_endpoint = 'api/v1/synchronizations/'¶

id_field = 'id'¶

json_data = True¶

name_field = 'id'¶

parse_json = True¶

checksum¶: Convenient class to make explicit that an attribute will store chars

content_guessing¶: Convenient class to make explicit that an attribute will store booleans

created_at¶: Field to store datetimes in resources

enqueued¶: Convenient class to make explicit that an attribute will store booleans

error_code¶: Convenient class to make explicit that an attribute will store integers

error_message¶: Convenient class to make explicit that an attribute will store chars

etag¶: Convenient class to make explicit that an attribute will store chars

fields = ['interval', 'service_name', 'updated_at', 'run_at', 'type_guessing', 'service_item_id', 'id', 'ran_at', 'user_id', 'synchronization_id', 'state', 'etag', 'quoted_fields_guessing', 'from_external_source', 'visualization_id', 'content_guessing', 'name', 'success', 'url', 'checksum', 'created_at', 'error_message', 'modified_at', 'enqueued', 'log_id', 'retried_times', 'error_code']¶

force_sync()¶

Forces to sync the SyncTableJob

Returns:
Raise:	CartoException

from_external_source¶: Convenient class to make explicit that an attribute will store booleans

get_force_sync_endpoint()¶

Get the relative path to the specific API resource

Returns:	Relative path to the resource
Raise:	CartoException

id¶: Convenient class to make explicit that an attribute will store chars

interval¶: Convenient class to make explicit that an attribute will store integers

log_id¶: Convenient class to make explicit that an attribute will store chars

modified_at¶: Field to store datetimes in resources

name¶: Convenient class to make explicit that an attribute will store chars

quoted_fields_guessing¶: Convenient class to make explicit that an attribute will store booleans

ran_at¶: Field to store datetimes in resources

retried_times¶: Convenient class to make explicit that an attribute will store integers

run(**import_params)¶

Actually creates the job import on the CARTO server

Parameters:	import_params (kwargs) – To be send to the Import API, see CARTO’s docs on Import API for an updated list of accepted params
Returns:

Note

The sync table job is asynchronous, so you should take care of the progression, by calling the carto.resources.AsyncResource.refresh() method and check the import job state attribute. See carto.datasets.DatasetManager.create() for a unified method to import files into CARTO

run_at¶: Field to store datetimes in resources

service_item_id¶: Convenient class to make explicit that an attribute will store chars

service_name¶: Convenient class to make explicit that an attribute will store chars

state¶: Convenient class to make explicit that an attribute will store chars

success¶: Convenient class to make explicit that an attribute will store booleans

synchronization_id¶: Convenient class to make explicit that an attribute will store chars

type_guessing¶: Convenient class to make explicit that an attribute will store booleans

updated_at¶: Field to store datetimes in resources

url¶: Convenient class to make explicit that an attribute will store chars

user_id¶: Convenient class to make explicit that an attribute will store chars

visualization_id¶: Convenient class to make explicit that an attribute will store chars

class carto.sync_tables.SyncTableJobManager(auth_client)¶

Bases: carto.resources.Manager

Manager for the SyncTableJob class

create(url, interval, **kwargs)¶

Create a sync table on the server

Parameters:	url (str) – URL can be a pointer to a remote location or a path to a local file interval (int) – Sync interval in seconds kwargs (kwargs) – Attributes (field names and values) of the new resource
Returns:	SyncTableJob

json_collection_attribute = 'synchronizations'¶

paginator_class¶: alias of carto.paginators.CartoPaginator

resource_class¶: alias of SyncTableJob

carto.tables module¶

Module for working with tables

class carto.tables.Table(auth_client, **kwargs)¶

Bases: carto.resources.WarnResource

Represents a table in CARTO. This is an internal data type. Both Table and TableManager are not meant to be used outside the SDK

If you are looking to work with datasets / tables from outside the SDK, please look into the datasets.py file.

Warning

Non-public API. It may change with no previous notice

class Meta¶

collection_endpoint = 'api/v1/tables/'¶

id_field = 'id'¶

json_data = True¶

name_field = 'name'¶

parse_json = True¶

dependent_visualizations = None¶

description¶: Convenient class to make explicit that an attribute will store chars

fields = ['rows_counted', 'map_id', 'description', 'permission', 'geometry_types', 'updated_at', 'synchronization', 'table_size', 'id', 'size', 'name', 'privacy', 'row_count', 'table_visualization', 'schema']¶

geometry_types¶: Convenient class to make explicit that an attribute will store chars

id¶: Convenient class to make explicit that an attribute will store chars

map_id¶: Convenient class to make explicit that an attribute will store chars

name¶: Convenient class to make explicit that an attribute will store chars

non_dependent_visualizations = None¶

permission¶: carto.permissions.Permission

privacy¶: Convenient class to make explicit that an attribute will store chars

row_count¶: Convenient class to make explicit that an attribute will store integers

rows_counted¶: Convenient class to make explicit that an attribute will store integers

schema¶: Convenient class to make explicit that an attribute will store chars

size¶: Convenient class to make explicit that an attribute will store integers

synchronization¶: carto.synchronizations.Synchronization

table_size¶: Convenient class to make explicit that an attribute will store integers

table_visualization¶: carto.visualizations.Visualization

updated_at¶: Field to store datetimes in resources

class carto.tables.TableManager(auth_client)¶

Bases: carto.resources.Manager

Manager for the Table class.

Warning

Non-public API. It may change with no previous notice

paginator_class¶: alias of carto.paginators.CartoPaginator

resource_class¶: alias of Table

carto.users module¶

Module for working with users

class carto.users.User(auth_client)¶

Bases: carto.resources.WarnResource

Represents an enterprise CARTO user, i.e. a user that belongs to an organization

Currently, CARTO’s user API only supports enterprise users.

Warning

Non-public API. It may change with no previous notice

class Meta¶

collection_endpoint = None¶

id_field = 'username'¶

json_data = True¶

name_field = 'username'¶

parse_json = True¶

all_visualization_count¶: Convenient class to make explicit that an attribute will store integers

available_for_hire¶: Convenient class to make explicit that an attribute will store booleans

avatar_url¶: Convenient class to make explicit that an attribute will store chars

base_url¶: Convenient class to make explicit that an attribute will store chars

db_size_in_bytes¶: Convenient class to make explicit that an attribute will store integers

description¶: Convenient class to make explicit that an attribute will store chars

disqus_shortname¶: Convenient class to make explicit that an attribute will store chars

email¶: Convenient class to make explicit that an attribute will store chars

fields = ['website', 'username', 'last_name', 'remove_logo', 'avatar_url', 'viewer', 'quota_in_bytes', 'org_admin', 'twitter_username', 'all_visualization_count', 'available_for_hire', 'password', 'db_size_in_bytes', 'description', 'disqus_shortname', 'name', 'org_user', 'google_maps_query_string', 'public_visualization_count', 'base_url', 'table_count', 'location', 'soft_geocoding_limit', 'email']¶

get_collection_endpoint()¶

get_resource_endpoint()¶

google_maps_query_string¶: Convenient class to make explicit that an attribute will store chars

last_name¶: Convenient class to make explicit that an attribute will store chars

location¶: Convenient class to make explicit that an attribute will store chars

name¶: Convenient class to make explicit that an attribute will store chars

org_admin¶: Convenient class to make explicit that an attribute will store booleans

org_user¶: Convenient class to make explicit that an attribute will store booleans

password¶: Convenient class to make explicit that an attribute will store chars

public_visualization_count¶: Convenient class to make explicit that an attribute will store integers

quota_in_bytes¶: Convenient class to make explicit that an attribute will store integers

remove_logo¶: Convenient class to make explicit that an attribute will store booleans

soft_geocoding_limit¶: Convenient class to make explicit that an attribute will store integers

table_count¶: Convenient class to make explicit that an attribute will store integers

twitter_username¶: Convenient class to make explicit that an attribute will store chars

username¶: Convenient class to make explicit that an attribute will store chars

viewer¶: Convenient class to make explicit that an attribute will store booleans

website¶: Convenient class to make explicit that an attribute will store chars

class carto.users.UserManager(auth_client)¶

Bases: carto.resources.Manager

Manager for the User class.

Warning

Non-public API. It may change with no previous notice

filter(**search_args)¶: Should get all the current users from CARTO, but this is currently not supported by the API

get_collection_endpoint()¶

get_resource_endpoint(resource_id)¶

paginator_class¶: alias of carto.paginators.CartoPaginator

resource_class¶: alias of User

carto.visualizations module¶

Module for working with map visualizations

class carto.visualizations.Visualization(auth_client, **kwargs)¶

Bases: carto.resources.WarnResource

Represents a map visualization in CARTO.

Warning

Non-public API. It may change with no previous notice

class Meta¶

collection_endpoint = 'api/v1/viz/'¶

id_field = 'id'¶

json_data = True¶

name_field = 'name'¶

parse_json = True¶

active_child¶: Convenient class to make explicit that an attribute will store chars

active_layer_id¶: Convenient class to make explicit that an attribute will store chars

attributions¶: Convenient class to make explicit that an attribute will store chars

auth_tokens¶: Convenient class to make explicit that an attribute will store chars

children¶: Convenient class to make explicit that an attribute will store chars

created_at¶: Field to store datetimes in resources

description¶: Convenient class to make explicit that an attribute will store chars

display_name¶: Convenient class to make explicit that an attribute will store chars

export()¶

Make the actual request to the Import API (exporting is part of the Import API) to export a map visualization as a .carto file

Returns:	A URL pointing to the .carto file
Return type:	str
Raise:	CartoException

Warning

Non-public API. It may change with no previous notice

Note

The export is asynchronous, but this method waits for the export to complete. See MAX_NUMBER_OF_RETRIES and INTERVAL_BETWEEN_RETRIES_S

external_source¶: Convenient class to make explicit that an attribute will store a dictionary

fields = ['liked', 'prev_id', 'likes', 'active_layer_id', 'table', 'children', 'display_name', 'privacy', 'permission', 'id', 'parent_id', 'version', 'next_id', 'type', 'external_source', 'map_id', 'description', 'tags', 'updated_at', 'attributions', 'synchronization', 'stats', 'kind', 'locked', 'name', 'license', 'url', 'active_child', 'created_at', 'uses_builder_features', 'transition_options', 'related_tables', 'source', 'auth_tokens', 'title']¶

id¶: Convenient class to make explicit that an attribute will store chars

kind¶: Convenient class to make explicit that an attribute will store chars

license¶: Convenient class to make explicit that an attribute will store chars

liked¶: Convenient class to make explicit that an attribute will store booleans

likes¶: Convenient class to make explicit that an attribute will store integers

locked¶: Convenient class to make explicit that an attribute will store booleans

map_id¶: Convenient class to make explicit that an attribute will store chars

name¶: Convenient class to make explicit that an attribute will store chars

next_id¶: Convenient class to make explicit that an attribute will store chars

parent_id¶: Convenient class to make explicit that an attribute will store chars

permission¶: carto.permissions.Permission

prev_id¶: Convenient class to make explicit that an attribute will store chars

privacy¶: Convenient class to make explicit that an attribute will store chars

related_tables¶: carto.tables.Table

source¶: Convenient class to make explicit that an attribute will store chars

stats¶: Convenient class to make explicit that an attribute will store a dictionary

synchronization¶: carto.synchronizations.Synchronization

table¶: carto.tables.Table

tags¶: Convenient class to make explicit that an attribute will store chars

title¶: Convenient class to make explicit that an attribute will store chars

transition_options¶: Convenient class to make explicit that an attribute will store a dictionary

type¶: Convenient class to make explicit that an attribute will store chars

updated_at¶: Field to store datetimes in resources

url¶: Convenient class to make explicit that an attribute will store chars

uses_builder_features¶: Convenient class to make explicit that an attribute will store booleans

version¶: Convenient class to make explicit that an attribute will store integers

class carto.visualizations.VisualizationManager(auth_client)¶

Bases: carto.resources.Manager

Manager for the Visualization class.

Warning

Non-public API. It may change with no previous notice

create(**kwargs)¶: Creating visualizations is better done by using the Maps API (named maps) or directly from your front end app if dealing with public datasets

json_collection_attribute = 'visualizations'¶

paginator_class¶: alias of carto.paginators.CartoPaginator

resource_class¶: alias of Visualization

send(url, http_method, **client_args)¶

Sends API request, taking into account that visualizations are only a subset of the resources available at the visualization endpoint

Parameters:	url (str) – Endpoint URL http_method (str) – The method used to make the request to the API client_args (kwargs) – Arguments to be sent to the auth client
Returns:
Raise:	CartoException