(GDAL/OGR >= 1.11)

This driver can connect to the services implementing the Carto API. GDAL/OGR must be built with Curl support in order for the Carto driver to be compiled.

The driver supports read and write operations.

Dataset name syntax

The minimal syntax to open a Carto datasource is :

For single-user accounts, connection name is the account name. For multi-user accounts, connection_name must be the user name, not the account name. Additional optional parameters can be specified after the ':' sign. Currently the following one is supported :

If several parameters are specified, they must be separated by a space.

Configuration options

The following configuration options are available :


Most operations, in particular write operations, require an authenticated access. The only exception is read-only access to public tables.

Authenticated access is obtained by specifying the API key given in the management interface of the Carto service. It is specified with the CARTO_API_KEY configuration option.


The OGR driver will report as many geometry fields as available in the layer (except the 'the_geom_webmercator' field), following RFC 41.


The driver will forward any spatial filter set with SetSpatialFilter() to the server. It also makes the same for attribute filters set with SetAttributeFilter().


Features are retrieved from the server by chunks of 500 by default. This number can be altered with the CARTO_PAGE_SIZE configuration option.

Write support

Table creation and deletion is possible.

Write support is only enabled when the datasource is opened in update mode.

The mapping between the operations of the Carto service and the OGR concepts is the following :

When inserting a new feature with CreateFeature(), and if the command is successful, OGR will fetch the returned rowid and use it as the OGR FID.

The above operations are by default issued to the server synchronously with the OGR API call. This however can cause performance penalties when issuing a lot of commands due to many client/server exchanges.

So, on a newly created layer, the INSERT of CreateFeature() operations are grouped together in chunks until they reach 15 MB (can be changed with the CARTO_MAX_CHUNK_SIZE configuration option, with a value in MB), at which point they are transferred to the server. By setting CARTO_MAX_CHUNK_SIZE to 0, immediate transfer occurs.


SQL commands provided to the OGRDataSource::ExecuteSQL() call are executed on the server side, unless the OGRSQL dialect is specified. You can use the full power of PostgreSQL + PostGIS SQL capabilities.

Open options

Starting with GDAL 2.0, the following open options are available:

Layer creation options

The following layer creation options are available:


  • Acceccing data from a public table:
    ogrinfo -ro "Carto:gdalautotest2 tables=tm_world_borders_simpl_0_3"

  • Creating and populating a table from a shapefile:
    ogr2ogr --config CARTO_API_KEY abcdefghijklmnopqrstuvw -f Carto "Carto:myaccount" myshapefile.shp

    See Also