Mapbox Upload API

We just put the finishing touches on the Mapbox Upload API and are taking it out of preview. The API is ready for production and available on every Mapbox plan!

Developers can use the Upload API to integrate Mapbox’s powerful data upload pipeline into their applications. We provide temporary credentials to stage a spatial file on S3, and then process it into raster tiles or Mapbox Vector Tiles readable by Mapbox GL and Mapbox.js.

The API supports a wide range of spatial file types: GeoJSON, KML, GPX, Shapefiles, CSV, GeoTIFF, and MBTiles – and we’re constantly adding support for more types and larger files.

People are already building amazing things with this API:

To get you started, we’ve added Upload API support to the new Mapbox JavaScript SDK with support for the ruby and Python SDKs coming soon.

Here’s a example of uploading from a Node.js app using the Mapbox SDK and AWS SDK for JavaScript:

var path = '/path/of/file/to/upload';
var tilesetId = 'myaccount.mytileset';
var MapboxClient = require('mapbox');
var mapboxClient = new MapboxClient('ACCESSTOKEN');
var AWS = require('aws-sdk');

mapboxClient.createUploadCredentials(function(err, credentials) {
  if (err) throw err;

  // Use aws-sdk and the provided credentials to stage the file on Amazon S3
  var s3 = new AWS.S3({
    accessKeyId: credentials.accessKeyId,
    secretAccessKey: credentials.secretAccessKey,
    sessionToken: credentials.sessionToken,
    region: 'us-east-1'

    Bucket: credentials.bucket,
    Key: credentials.key,
    Body: fs.createReadStream(path)
  }, function(err, resp) {
    if (err) throw err;

    // Create an upload to submit the file for processing
     tileset: tilesetId,
     url: credentials.url
    }, function(err, upload) {
      if (err) throw err;
      console.log('upload created with id:',;


You can also use mapbox-upload, a command-line tool for uploading files from anywhere. Here’s an example:

$ npm install --global mapbox-upload
$ export MapboxAccessToken=<access token with uploads:write scope enabled>
$ mapbox-upload username.dataid /path/to/file

This is the first in a series of API improvements coming soon: we’re working on OAuth2 authentication support, read/write APIs for tilesets and projects, and powerful new ways to interact with raw data.

We hope you build awesome things with the Upload API. Start with the API documentation, and email us at if you have any questions or feedback.