Upload files to your CARTO account and manipulate them by using a set of HTTP commands.

CARTO Map Visualizations

The Export map option enables you to download a map, and the connected dataset, as a .carto file. This is useful for downloading complete CARTO visualizations that you can share or import.

Note: The Import API export visualization command only works for maps created from your dashboard.

A cURL POST request allows you to export the visualization, which you will have to poll with a GET command until the state is complete.

Export a CARTO Visualization

Call

1
curl -H 'Content-Type: application/json' https://{username}.carto.com/api/v3/visualization_exports\?api_key\={api_key} -X POST --data '{"visualization_id":"{visualization_id}"}'
Params
Param Description
api_key The target CARTO account API key.
visualization_id A unique identifier for the map created in the export process. Only applies if create_visualization is set to true when the map was created.

Response

1
{"id":"b94c26f3-fa16-4f13-b672-45ebbd5a9c95","visualization_id":"ace62506-brc8-6570-2p91-8vf3af3ftc44","user_id":"42b78090-6a11-475a-8060-0a90322752af2","state":"pending","url":null,"created_at":"2016-05-05T09:36:09+00:00","updated_at":"2016-05-05T09:36:09+00:00"}

After making the POST request to create the export, it is expected that the request will take some time. You must poll the server by making a GET request, until state becomes complete. For example:

1
curl -v -H 'Content-Type: application/json' https://{username}.carto.com/api/v3/visualization_exports/{visualization_export_id}\?api_key\={api_key} -X GET

Once completed, the response status changes to complete and displays the upload url location of the .carto visualization file:

1
{"id":"b94c26f3-fa16-4f13-b672-45ebbd5a9c95","visualization_id":"{visualization_id}","user_id":"42b78090-6a11-475a-8060-0a90322752af2","state":"complete","url":"/uploads/6a2b6fbd86e2c750160a/ace62506-brc8-6570-2p91-8vf3af3ftc44.carto","created_at":"2016-05-05T09:36:09+00:00","updated_at":"2016-05-05T09:36:13+00:00"}%

The response includes:

Attributes Description
id A unique identifier for the export process. It is the same as the export id provided in the request.
vizualization_id A unique identifier for the map created in the export process. Only applies if create_visualization is set to true when the map was created.
user_id A unique alphanumeric element that identifies the CARTO account user in the internal database.
state A string value indicating the current state of the export process. It can have any of the following values: enqueued, pending, uploading, unpacking, importing, guessing, complete, or failure.
url The public URL address where the file to be exported is located.
created_at The date time at which the visualization was created in the CARTO database.
updated_at The date time at which the visualization had its contents modified.
Example

Example POST request:

1
2
curl -v -H 'Content-Type: application/json' https://{username}.carto.com/api/v3/visualization_exports\?api_key\={api_key} -X POST --data '{"visualization_id":"9a0f4384-afe3-412a-8b09-136b7d9a4013"}'
{"id":"72e488a6-cf0e-404d-bc7e-de9c9840aadf","visualization_id":"9a0f4384-afe3-412a-8b09-136b7d9a4013","user_id":"d80fe0f5-0465-4c4a-a2fe-1f14a93f3c5b","state":"pending","url":null,"created_at":"2016-05-20T07:01:38+00:00","updated_at":"2016-05-20T07:01:38+00:00"}%

Example completed response:

1
2
curl -H 'Content-Type: application/json' https://{username}.carto.com/api/v3/visualization_exports/72e488a6-cf0e-404d-bc7e-de9c9840aadf\?api_key\=04039a13c1bdda65df8bd825b3b8e8117444c950 -X GET
{"id":"72e488a6-cf0e-404d-bc7e-de9c9840aadf","visualization_id":"9a0f4384-afe3-412a-8b09-136b7d9a4013","user_id":"d80fe0f5-0465-4c4a-a2fe-1f14a93f3c5b","state":"complete","url":"http://s3.amazonaws.com/com.cartodb.imports.production/9d149e72331bf074e35f/9a0f4384-afe3-412a-8b09-136b7d9a4013.carto?AWSAccessKeyId=AKIAJK5S64CVBE35QTKA&Expires=1463734900&Signature=b4cwrdoB%2B0FlTelIzNOAgslUDXY%3D","created_at":"2016-05-20T07:01:38+00:00","updated_at":"2016-05-20T07:01:40+00:00"}%

Import a CARTO Visualization

To import a .carto visualization, you can use the standard Import API procedure for uploading a local file.

See the import errors list on Support section to troubleshoot any importing errors.