Upload a tileset to Mapbox with the Uploads API | Help

Prerequisite

Familiarity with cURL.

In this tutorial, you will use the Mapbox Uploads API to upload a sample file to Mapbox as a raster tileset. You will use the command line with cURL to access the Uploads API. The sample file you are uploading in this tutorial is a TIFF with satellite imagery.

Uploading raster data vs. vector data

When you are working with raster data, use the Uploads API, or Mapbox Studio if you prefer a point-and-click interface. When you are working with vector data, consider using the Mapbox Tiling Service (MTS) instead. The Uploads API is an opinionated tool that makes configuration decisions for you based on the uploaded data, while MTS has several endpoints that you can use to tile vector data using custom configuration rules.

Getting started

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

Mapbox account. Sign up for a free account on Mapbox.
Secret access token. Create a new secret access token with the map:write, uploads:write, uploads:read, and uploads:list scopes enabled.
AWS CLI. Install the AWS CLI. This process requires Python and pip.
cURL. You should have experience using the command line with cURL.
Data. In this tutorial, you will upload a TIFF file that contains a satellite image of the Grand Traverse Bay region of Lake Michigan. Download the file using the button below and save it to your project folder for this tutorial.

arrow-downDownload TIFF

Uploads API pricing

The sample file you will upload to Mapbox in this tutorial falls within the Uploads API's free tier for tileset processing and hosting. When you use the Uploads API with your own data, your costs may exceed the free tier. See the Uploads API pricing documentation for more details on how we charge for this service.

Stage the 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.

Retrieve temporary credentials

To stage the sample file on S3, you need to retrieve temporary credentials from the Uploads API's credentials endpoint. Use the following cURL command, replacing YOUR_MAPBOX_USERNAME with your Mapbox username, and replacing YOUR MAPBOX ACCESS TOKEN with the secret access token you created in the Getting started section.

Note: your access token needs to have the token scope of uploads: write to use this API.


$curl -X POST "https://api.mapbox.com/uploads/v1/YOUR_MAPBOX_USERNAME/credentials?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

If your request URL is valid, you will 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 steps.

Set environment variables

Next, set environment variables that allow you to upload your data to S3. Paste the following into your terminal, replacing the {accessKeyId}, {secretAccessKey}, and {sessionToken} placeholders with the information returned by your cURL command in the last step:


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

Stage your data

Next, stage the sample file traverse-bay.tiff, which you downloaded in the Getting started section, on S3. From the same project folder in which you saved the sample file, run the following in your terminal, replacing the {bucket} and {key} placeholders with the information returned in the Retrieve temporary credentials step:


$aws s3 cp traverse-bay.tiff s3://{bucket}/{key} --region us-east-1

You should see a response that looks like:


upload: ./traverse-bay.tiff 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 the file itself, 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 to the Uploads API's Create an upload endpoint. Replace the {bucket} and {key} placeholders in the "url" value with the information returned in the Retrieve temporary credentials step. 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": "YOUR_MAPBOX_USERNAME.traverse-bay",
  "name": "Traverse Bay"
}' 'https://api.mapbox.com/uploads/v1/YOUR_MAPBOX_USERNAME?access_token=YOUR_MAPBOX_ACCESS_TOKEN'

The "tileset" value contains both your Mapbox username and the name that you want to call your data when it gets to Mapbox, like bike-trails, airports, or in this case traverse-bay. If you use the name of an existing tileset, it will be overwritten. The format for this value will always be {username}.{tileset-name}.

Once a successful POST request has completed, you will receive an HTTP 201 response and a confirmation that your upload has started. The confirmation response will look like:


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

The {upload-id} in this response refers to the upload's unique identifier. If you want, you can use this identifier to retrieve the upload status later. This value will be a number between 0, which means the upload has started, and 1, which means that the upload is complete.

See your new tileset in Studio

Once you have started the upload process, it may be a few minutes before your upload has finished processing and is complete. Since the sample file is small, the process will usually not take long, but larger and more complex data will take longer. If your upload fails, see our uploads troubleshooting guide for more information.

Go to your Tilesets page in Mapbox Studio and scroll down to the Custom tilesets section. Your new raster tileset will be at the top of the list. Click the menu (the options icon to the right of the tileset) to find the tileset ID, the tileset's unique identifier. The menu also has ways to replace the tileset, make the tileset public, and delete the tileset. For more details about the tileset, you can also click on its name to open the Tileset explorer.

Next steps

The new tileset is now available for you to use! You can request the tileset directly using the Raster Tiles API, or you can add it to a new or existing map style. To explore using raster tileset in a Mapbox map, see the following examples: