advanced
cURL
Upload to Mapbox using cURL
Prerequisite
Familiarity with cURL.

This guide illustrates how you can use the Mapbox Uploads API via the command line with cURL. If you would like to upload your data through a point-and-click interface, you can do so with Mapbox Studio.

Getting started

There are a few resources you’ll need before getting started:

Stage your file on Amazon S3

Mapbox provides an Amazon 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 account. To stage a file on S3, you’ll need to retrieve temporary credentials from the Uploads API’s credentials endpoint:

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

In the above command, secret_access_token is your secret access token and username is your Mapbox account username.

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

{
  "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 upload your data to S3:

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

To stage your data on S3, run the following in your terminal:

$ 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}

Begin the upload process

Once your file is staged on Amazon S3, you need to create an upload that defines where the Mapbox Uploads API should look for your staged data. The upload is not actually the file, but an object that tells Mapbox’s servers how to find your staged file and where to put it. You give Mapbox instructions by sending a POST request with this information. 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}.{tileset-name}"
}' 'https://api.mapbox.com/uploads/v1/user123?access_token=secret_access_token'

Note: The {username} is always your Mapbox username. The {tileset-name} parameter is what you would like to call your data when it gets to Mapbox, such as bike-trails or airports. If you use the name of an existing tileset, it will be overwritten.

Once a successful POST request has completed, you will receive an HTTP 201 response and a confirmation that your upload has started, which will look similar to this:

{
  "complete": false,
  "tileset": "{username}.{tileset-name}",
  "error": null,
  "id": "{upload-id}",
  "name": "{username}-{tileset-name}",
  "modified": "{timestamp}",
  "created": "{timestamp}",
  "owner": "{username}",
  "progress": 0
}

Note: The {upload-id} refers to the upload’s unique identifier. This can be used to retrieve the upload status later.

Finished product

Once you have started the upload process, it may be a few minutes before your upload has finished processing and is complete. This is dependent on the size and complexity of your data. If your upload fails, see our uploads troubleshooting guide for more information.

If the upload is successful, your new tileset will be listed on your tilesets page. At this point, your tileset is now available to use in custom map styles!