Upload to Mapbox using cURL

This guide covers uploading data to Mapbox using the Mapbox Uploads API with cURL directly in the command line.

There are a few ways to upload data via the Mapbox Uploads API, including through the Uploads page, with the mapbox-upload CLI, and via the command line, which this guide covers.


Step 0: Make sure you have cURL installed

Open up your command line or Terminal and enter which curl. If you see something like /usr/bin/curl, you have cURL installed. If not, install cURL.

Step 1: Stage your file on Amazon S3

Mapbox provides an S3 bucket to stage your file while your upload is processed. All uploads must be staged in this bucket before being uploaded to your Mapbox.com account. You can retrieve temporary credentials from this endpoint.

1.1 Use the following command to request temporary credentials:

curl -X POST https://api.mapbox.com/uploads/v1/<username>/credentials?access_token=<secret access token>

If your request URL is correct, you should receive a response that looks something like:

  "accessKeyId": "{accessKeyId}",
  "bucket": "{bucket}",
  "key": "{key}",
  "secretAccessKey": "{secretAccessKey}",
  "sessionToken": "{sessionToken}",
  "url": "{url}"

These credentials give you permission to stage your data on Amazon’s servers and are crucial to the next step. Enter the following into your terminal to set the correct environment variables that allow you to send your data to S3:

$ export AWS_ACCESS_KEY_ID={accessKeyId}
$ export AWS_SECRET_ACCESS_KEY={secretAccessKey}
$ export AWS_SESSION_TOKEN={sessionToken}

To upload your data to S3, run the following:

$ aws s3 cp /path/to/file s3://{bucket}/{key} --region us-east-1

You should see a response that looks like:

upload: ./{file name} to s3://{bucket}/{key}

Step 2: Create a new upload

Once your file is staged on S3, you need to create an upload on Mapbox.com and tell it where to look for the data. The upload is not actually the file, but an object that tells Mapbox’s servers how to find your file and where to put it. You give Mapbox instructions by sending a POST request. Using cURL, your request will look like:

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
  "url": "http://{bucket}.s3.amazonaws.com/{key}",
  "tileset": "<username>.<name you would like to give your data>"
}' 'https://api.mapbox.com/uploads/v1/<username>?access_token=<secret access token>'

Note: The tileset parameter is what you would like to call your data when it gets to Mapbox. The first part (before the .) is always your Mapbox username. The second part can be anything. If you use the name of an existing tileset, it will be overwritten.

Once the upload has finished, you will receive an HTTP 201 response and the new tileset will be listed on your Data page. Your data is now available as a source!

Next article:

Upload data to Mapbox

Additional questions? Ask our support team or learn more about How Mapbox Works.