Upload files to your CARTO account and manipulate them by using a set of HTTP commands.
This component is still under support but it will not be further developed. We don’t recommend starting new projects with it as it will eventually become deprecated. Instead, learn more about our new APIs here
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.
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}"}'
| 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. |
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 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"}%
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.