Uploads API

The Mapbox Uploads API transforms geographic data into tilesets that can be used with maps and geographic applications. Given a wide variety of geospatial formats, it normalizes projections and generates tiles at multiple zoom levels to make data viewable on the web.

The upload workflow follows these steps:

1. Request temporary S3 credentials that allow you to stage the file. Jump to the Retrieve S3 credentials section.
2. Use an S3 client to upload the file to Mapbox's S3 staging bucket using these credentials. Learn more about this process in the Upload to Mapbox using cURL tutorial.
3. Create an upload using the staged file's URL. Jump to the Create an upload section.
4. Retrieve the upload's status as it is being processed into a tileset. Jump to the Retrieve upload status section.

Note: This documentation discusses how to interact with the Mapbox Uploads API programmatically. For a step-by-step guide on how to use the Uploads API to stage a file to Amazon S3 and create an upload, use the Upload to Mapbox using cURL tutorial.

Retrieve S3 credentials

Mapbox provides an Amazon S3 bucket to stage your file while your upload is processed. This endpoint allows you to retrieve temporary S3 credentials to use during the staging process.

Note: This step is necessary before you can stage a file in the Amazon S3 bucket provided by Mapbox. All uploads must be staged in this Amazon S3 bucket before being uploaded to your Mapbox account. To learn more about how to stage an upload to Amazon S3, read the Upload to Mapbox using cURL tutorial.

Example request: Retrieve S3 credentials

$ curl -X POST "https://api.mapbox.com/uploads/v1/{username}/credentials?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with uploads:write scope.
"

Example AWS CLI usage

$ export AWS_ACCESS_KEY_ID={accessKeyId}
$ export AWS_SECRET_ACCESS_KEY={secretAccessKey}
$ export AWS_SESSION_TOKEN={sessionToken}
$ aws s3 cp /path/to/file s3://{bucket}/{key} --region us-east-1

Response: Retrieve S3 credentials

The response body is a JSON object that contains the following properties:

Use these credentials to store your data in the provided bucket with the provided key using the AWS CLI or AWS SDK of your choice. The bucket is located in AWS region us-east-1.

Example response: Retrieve S3 credentials

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

Supported libraries: Retrieve S3 credentials

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

• Mapbox Python CLI
• Mapbox JavaScript SDK

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Create an upload

Uploads can be created from a file staged on Mapbox's S3 bucket, or from an existing Mapbox dataset.

After you have used the temporary S3 credentials to transfer your file to Mapbox's staging bucket, you can trigger the generation of a tileset using the file's URL and a destination tileset ID.

Uploaded files must be in the bucket provided by Mapbox. Requests for resources from other S3 buckets or URLs will fail.

Note: You can only replace existing tilesets created with the Uploads API with this endpoint. You cannot replace a tileset created with Mapbox Tiling Service (MTS) with a tileset created with the Uploads API.

The request body must be a JSON object that contains the following properties:

Example request: Create an upload from a file staged on S3

$ curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
  "url": "https://{bucket}.s3.amazonaws.com/{key}",
  "tileset": "{username}.{tileset-name}"
}' 'https://api.mapbox.com/uploads/v1/{username}?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with uploads:write scope.'

Example request: Create an upload from a Mapbox dataset

$ curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
  "tileset": "{username}.mytileset",
  "url": "mapbox://datasets/{username}/{dataset}",
  "name": "example-dataset"
}' 'https://api.mapbox.com/uploads/v1/{username}?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with uploads:write scope.'

Response: Create an upload

The response body is a JSON object that contains the following properties:

Example response: Create an upload

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

Supported libraries: Create an upload

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

• Mapbox JavaScript SDK

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Retrieve upload status

Once an upload is created, you can track its status. Uploads have a progress property that start at 0 and end at 1 when an upload is complete. If there's an error processing an upload, the error property will include an error message.

Example request: Retrieve upload status

$ curl "https://api.mapbox.com/uploads/v1/{username}/{upload_id}?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with uploads:read scope.
"

Response: Retrieve upload status

The response body is a JSON object containing the following properties:

Example response: Retrieve upload status

{
  "complete": true,
  "tileset": "example.markers",
  "error": null,
  "id": "hij456",
  "name": "example-markers",
  "modified": "{timestamp}",
  "created": "{timestamp}",
  "owner": "{username}",
  "progress": 1
}

Supported libraries: Retrieve upload status

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

• Mapbox JavaScript SDK

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Retrieve recent upload statuses

Retrieve multiple upload statuses at the same time, sorted by the most recently created.

This endpoint supports pagination so that you can list many uploads.

The results from this endpoint can be further modified with the following optional parameters:

Example request: Retrieve recent upload statuses

$ curl "https://api.mapbox.com/uploads/v1/{username}?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with uploads:list scope.
"

# Return at most 10 upload statuses, in chronological order

$ curl "https://api.mapbox.com/uploads/v1/{username}?reverse=true&limit=10&access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with uploads:list scope.
"

Response: Retrieve recent upload statuses

This request returns the same information as an individual upload status request does, but for all an account's recent uploads. The list is limited to one MB of JSON.

Example response: Retrieve recent upload statuses

[{
  "complete": true,
  "tileset": "example.mbtiles",
  "error": null,
  "id": "abc123",
  "name": null,
  "modified": "2014-11-21T19:41:10.000Z",
  "created": "2014-11-21T19:41:10.000Z",
  "owner": "example",
  "progress": 1
}, {
  "complete": false,
  "tileset": "example.foo",
  "error": null,
  "id": "xyz789",
  "name": "foo",
  "modified": "2014-11-21T19:41:10.000Z",
  "created": "2014-11-21T19:41:10.000Z",
  "owner": "example",
  "progress": 0
}]

Supported libraries: Retrieve recent upload statuses

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

• Mapbox JavaScript SDK

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Remove an upload status

Remove the status of a completed upload from the upload listing.

Uploads are only statuses, so removing an upload from the listing doesn't delete the associated tileset. Tilesets can only be deleted from within Mapbox Studio. An upload status cannot be removed from the upload listing until after it has completed.

Example request: Remove an upload status

$ curl -X DELETE "https://api.mapbox.com/uploads/v1/{username}/{upload_id}?access_token=
YOUR_MAPBOX_ACCESS_TOKEN
This endpoint requires a token with uploads:write scope.
"

Response: Remove an upload status

HTTP 204 No content

Supported libraries: Remove an upload status

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

• Mapbox JavaScript SDK

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Uploads API restrictions and limits

• Tileset names are limited to 64-characters.
• The default rate limit for the Mapbox Uploads API endpoint is 60 requests per minute. If you require a higher rate limit, contact us.
• If you exceed the rate limit, you will receive an HTTP 429 Too Many Requests response. For information on rate limit headers, see the Rate limit headers section.
• The Uploads API supports different file sizes for various file types:

Uploads API errors

To see a list of possible upload errors, visit the Uploads errors page.

Pricing

When you use the Uploads API, you will see two different line items: tileset processing and tileset hosting. The cost of each will depend on the area of your tiled data and the precision level of your tileset.

Uploads API tileset processing

Each time you create an upload using the Uploads API, you will see a one-time tileset processing charge. A tileset processing cost includes both the cost of generating a tileset as well as the transfer costs associated with putting all tiles in that tileset onto Mapbox servers. (For example, if you upload MBTiles using the Uploads API, even though the tileset does not need to be generated, you will still see a tileset processing cost that reflects the transfer costs for moving the tileset to a Mapbox server.) The total cost of tileset processing depends on two factors:

• Precision level at which the Uploads API chooses to tile your data. Precision approximately describes the range of accuracy of tiled data relative to the real world.
• Area tiled, in square kilometers (km²), of your tiled data. This area is the total area of all tiles that contact features from your data at the precision level chosen by the Uploads API. See the How area is calculated troubleshooting guide for more details on how this value is determined.

To see details on the precision level and area tiled for a specific tileset, go to your Tilesets page and click on the tileset's name to visit the Tileset explorer. The Tileset explorer provides a link to the pricing calculator in the Billing metrics section, where you can input the square kilometers of your tiled data for a pricing estimate.

There are four possible line items related to tileset processing, each associated with a different precision level and pricing. The Uploads API supports four precision levels: 10 meter, 1 meter, 30 centimeter, and 1 centimeter.

The line item you see on your invoice depends on the tileset's maxzoom value, which is determined automatically by the Uploads API. If you want more control over the precision level used for your vector tilesets, and ultimately the price you pay for them, use Mapbox Tiling Service.

To learn more about how to optimize your tilesets to reduce tileset processing costs, see our guide on managing your tileset processing and tileset hosting costs.

Uploads API tileset hosting

After you create an upload using the Uploads API, you will begin to see a recurring tileset hosting charge for every day your tileset is hosted on Mapbox's servers. This charge covers the cost of storing your tiled and processed data on Mapbox servers, and will depend on three factors:

• Precision level at which the Uploads API chooses to tile your data. Precision approximately describes the range of accuracy of tiled data relative to the real world.
• Square kilometer days is equal to the area tiled multiplied by the number of days hosted. The maximum possible value for a tileset's square kilometer days is the area of the tileset multiplied by the number of total days in the billing period.
• Area tiled, in square kilometers (km²), of your tiled data. This area is the total area of all tiles that contact features from your data at the precision level chosen by the Uploads API. See the How area is calculated troubleshooting guide for more details on how this value is determined.
• Days hosted in your account in a given month-long billing period.

There are four possible line items related to tileset hosting, each associated with a different precision level and pricing. The Uploads API supports four precision levels: 10 meter, 1 meter, 30 centimeter, and 1 centimeter. The line item you see on your invoice depends on the tileset's maxzoom value, which is determined automatically by the Uploads API.

Manage tileset hosting costs

The most expensive tilesets to host are those that both cover a large area, like the entire world, and will require high precision, for example a global road network. You can lower your costs by deleting any tilesets you're no longer using, which you can do using Mapbox Tiling Service (MTS) or Mapbox Studio. To learn more about how to optimize your tilesets to reduce tileset hosting costs, see our guide on managing your tileset processing and tileset hosting costs.