Upload new data

If you want to upload your own custom data to Mapbox so that you can use it with Mapbox tools, you've come to the right place! This guide will help you choose which Mapbox upload tool is right for you, based on the kind of data you need to upload and what you want to do with it.

This guide focuses on the process of taking geographic data that already exists and transforming it into a format that can be used on an interactive web or mobile map. This could be data that you downloaded from an open data portal, data that you drew in a GIS application, or aerial imagery taken by a drone.

In this guide, you'll learn:

• Whether you need to upload your data to use it with Mapbox
• Whether you should upload your data as a tileset or a dataset
• Which Mapbox tool you should use to upload your custom data, depending on whether you need a tileset or a dataset

Key terms

It can be helpful to understand key terms related to data and data uploads:

• dataset: an editable feature collection format that can be exported to a tileset
• editable: having changeable content, like locations, shapes, or properties
• feature: a point, line, or polygon that represents an entity in the real world
• GeoJSON: a file format used for representing spatial data
• raster data: pixel-based data like digital photos or satellite imagery
• styleable: having a changeable appearance, like color or opacity
• tileset: a stylable feature collection format optimized for rendering
• vector data: represents geographic features as points, lines, or polygons and assigns them attributes

Do I need to upload my data?

Uploading your data to Mapbox isn't always necessary. In some cases, uploading data adds an unnecessary step to your development workflow. Consider loading your data at runtime instead of uploading it if:

• You are working with sample data during prototyping
• You need live data and data updates
• You want to work with third-party data sources

Loading your data at runtime could mean linking to an external GeoJSON file, using a non-Mapbox API that returns geographic data, or even referencing inline GeoJSON while you are in your development phase.

Projections and coordinate systems

The Mapbox Tiling Service and Mapbox SDKs for mobile and web can accept GeoJSON that follows the GeoJSON standard for a geographic coordinate reference system equivalent to OGC:CRS84, using the WGS84 datum, decimal degrees, and longitude and latitude units (in that order). The Mapbox Uploads API can accept data in a variety of formats and projections. While there is some variation in support for coordinate systems for data inputs, all Mapbox tools transform those input coordinates for display using the popular Web Mercator projection.

Tilesets versus Datasets

Datasets and tilesets are two different types of resources that you can create when uploading data to your Mapbox account.

Tilesets are lightweight collections of vector data that are optimized for rendering and are not editable but are ready for styling in the Mapbox Studio style editor, our Mobile Maps SDKs, or Mapbox GL JS.

Datasets provide access to feature geometries (points, lines, and polygons) and properties (attributes), both of which can be edited in the Mapbox Studio dataset editor or through the Mapbox Datasets API. Uploading your data as a dataset gives you more control over editing and managing the data, but requires an additional step to convert it into a tileset for rendering on a Map.

Your decision depends on a few considerations:

Once you have chosen whether to upload your data as a tileset or a dataset, you can choose a tool to help you upload your data.

Accepted file types and transfer limits

The accepted file types and transfer limits for dataset and tileset uploads include:

Tools for uploading tilesets

Mapbox offers three products that can be used to upload data as a tileset:

• Mapbox Studio
• Uploads API
• Mapbox Tiling Service (MTS)

To decide which tool you should use, choose the scenario that most closely describes your use-case:

Mapbox Studio

If you want to upload your vector or raster data to create a tileset using a drag-and-drop interface, use Mapbox Studio. You can create tilesets using either the Mapbox Studio Tilesets page or the Style editor.

This upload method is right for you if you need to upload and style your tilesets, but do not need fine-tuned control over details like zoom levels or simplification.

Behind the scenes, Mapbox Studio uses the Mapbox Uploads API, an opinionated tool that automatically makes decisions about certain presentation details like minimum zoom and maximum zoom based on the data you are uploading.

Mapbox Tiling Service

If you want to upload your vector data to create a tileset and need to control details like zoom level or simplification, use Mapbox Tiling Service (MTS).

This upload method is right for you if you need precise control over how your geospatial data is transformed into vector tilesets. For example, you may want to specify a minimum zoom and a maximum zoom at which the data in your tileset will be available.

MTS is the same service Mapbox uses internally to create our global, daily-updating basemap Mapbox Streets.

Uploads API

If you want to programmatically upload your raster data to create a tileset, use the Uploads API.

This upload method is right for you if you need to programmatically create raster tilesets. The Uploads API is an opinionated tool that automatically makes decisions about certain presentation details like minimum and maximum zoom levels and simplification, based on the data you are uploading.

Tools for uploading datasets

Mapbox offers two products that can be used to upload data as a dataset:

• If you want to upload your data to create a dataset using a drag-and-drop interface, use the Mapbox Studio dataset editor.
• If you want to upload your data to create a dataset programmatically, use the Datasets API.

Mapbox Studio Dataset editor

If you want to upload your data to create a dataset using a drag-and-drop interface, use the Mapbox Studio Dataset editor.

This upload method is right for you if you need to upload datasets, but do not need the ability to manage them programmatically. Remember that to visualize the data in your dataset, you need to convert it to a tileset, which you can also do in Mapbox Studio.

The Mapbox Studio Dataset editor uses the Datasets API behind the scenes, but it has a smaller upload limit than exists with the Datasets API (20 uploads per month, versus unlimited uploads).

Datasets API

If you want to programmatically upload your data to create a dataset, use the Datasets API.

This upload method is right for you if you need to programmatically upload data to create datasets. Unlike the Mapbox Studio Dataset editor, you can't upload a file directly through the Datasets API. Instead, the process of using the Datasets API to create a new dataset involves two steps: creating an empty dataset, then adding features to that dataset as the body of a POST request.

Next steps

Once you have uploaded your custom data to a dataset or tileset, you are ready to continue building with Mapbox. You may want to add your data to a map and style it, do spatial analysis, or enable users to interact with your data in an application.

These guides and tutorials can help you choose your next steps:

• Use a tool like Turf.js to do spatial analysis tasks with your new data. Learn more in the Spatial analysis getting started guide.
• Add the tileset to a map style in Mapbox Studio and apply a custom style. Learn more about how to use Studio in our Studio Manual.
• Use the Tilequery API to retrieve data about specific features from a vector tileset. Use the Healthy food finder tutorial as inspiration!