Import API v1

Quickstart

For this example (and the rest of the ones illustrated here) we will be using a command-line tool known as cURL. For more info about this tool see this blog post or type man curl in bash.

Uploading a Local File

Suppose you have a CARTO account whose username is documentation, and you want to upload a local file named prism_tour.csv (located in the Documents folder). This requires that you execute the following command on a Terminal window:

Call

1
2
curl -v -F file=@/home/documentation/Documents/prism_tour.csv
"https://documentation.carto.com/api/v1/imports/?api_key=3102343c42da0f1ffe6014594acea8b1c4e7fd64"

Note that the api_key element has an alphanumeric value that is exclusive to the documentation CARTO account.

The response to this request appears in the following format, where a successful value indicates that the import process is enqueued:

Response

1
2
3
4
{
  "item_queue_id": "efa9925c-31dd-11e4-a95e-0edbca4b5057",
  "success": true
}

The item_queue_id value is a unique identifier that references the import process. Once this process has started, its information can be obtained doing a request to the imports endpoint as explained in the “Check the status of an import process section.

Uploading from a Remote URL

Suppose you have a server at the hostname examplehost.com, with a csv named sample.csv already uploaded. Creating a table from the URL requires that you execute the following command on a Terminal window:

Call

1
2
curl -v -H "Content-Type: application/json" -d '{"url":"https://examplehost.com/sample.csv"}'
"https://documentation.carto.com/api/v1/imports/?api_key=3102343c42da0f1ffe6014594acea8b1c4e7fd64"

The response to this request returns the following format, returning a success value if the import process is correctly enqueued:

Response

1
2
3
4
{
  "item_queue_id": "efa9925c-31dd-11e4-a95e-0edbca4b5057",
  "success": true
}

Connecting to a Database

Suppose you have an external MySQL database named mydb that you want to connect to. For the purpose of this example, you will access a server with the address of mydbserver.com. Your username is myuser, and your password is mypass. Connect a CARTO dataset to a remote table, named mytable, by executing the following command on a Terminal window:

Call

1
2
3
4
5
6
7
8
9
10
11
12
curl -v -H "Content-Type: application/json" -d '{
  "connector": {
    "provider": "mysql",
    "connection": {
      "server":"mydatabaserver.com",
      "database":"mydb",
      "username":"myuser,
      "password":"mypass"
    },
    "table": "mytable"
  }
}' "https://documentation.carto.com/api/v1/imports/?api_key=3102343c42da0f1ffe6014594acea8b1c4e7fd64"

Response

1
2
3
4
{
  "item_queue_id": "tyf9925c-32dd-11f4-a95f-0fdbca4b5058",
  "success": true
}