Upload new data | Help

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 source data portal, data that you drew in a GIS application, or aerial imagery taken by a drone.

book

Creating new data

If you need to create data from scratch, we recommend checking out:

Mapbox Studio's Dataset editor, which is good for drawing a collection of points for adding markers to a map or drawing simple lines or polygons.
QGIS, an open source GIS application, which is good for creating more complex data and performing spatial operations.After you've created your data, jump back into this guide to learn how to upload it to Mapbox!

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.

book

Converting projections

If you need to reproject your data or change its coordinate system, consider using third-party tools like GDAL's ogr2ogr or QGIS

Choose a format

To determine which Mapbox tool you should use to upload your custom data, you need to decide whether to upload the data as a tileset or a dataset.

book

Learn about datasets and tilesets

For more background information about tilesets and datasets and how they work, see our Create new data getting started guide.

Your decision depends on a few considerations:

Considerations for uploading data	Tileset	Dataset
Styleability: Do you need to style your data on a map?
Editability: Do you need to be able to edit your data after you have uploaded it?
Data stability: Once it's uploaded, will your data need to be updated frequently?

Once you have chosen either tileset or dataset as the format for your data upload, you can choose a tool to help you upload your data.

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:

You want to...	Mapbox Studio	Mapbox Tiling Service	Uploads API
Upload your vector or raster data to create a tileset using a drag-and-drop user interface
Upload your raster data to create a tileset programmatically
Upload your vector data to create a tileset and need to control details like zoom level and simplification
Upload your vector data to create a tileset programmatically

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.


Pros	No coding necessary Drag-and-drop interface Accepts many common geospatial file types Can be used to upload raster or vector tilesets
Cons	Does not provide you with control over how your data is uploaded Smaller upload limit than exists with Mapbox Tiling Service or the Uploads API (300 MB and 20 uploads per month, versus 1 GB and unlimited uploads)
Recommended for	Small-to-medium data sets (less than 300 MB)
Use cases	Getting started quickly Rapid prototyping (if you discover that you need more upload control after you begin using your data, consider uploading it with Mapbox Tiling Service) Data visualization Designing custom map styles based on your data
Examples	Create a choropleth map Style a heatmap layer
Documentation	Tutorial: Make a choropleth map Part 1 Mapbox Studio Manual

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.


Pros	Fine-tuned control over how data is transformed into vector tilesets Can create multi-layer tilesets Ability to remove extraneous areas and properties Ability to union features together on matched attributes
Cons	May be too many options for rapid prototyping or uncomplicated use-cases
Recommended for	Production-ready applications Performance and cost optimization
Use cases	Visualize activity data, like runs or hikes, on a map Create multi-layer tilesets Add real estate or hotel properties and their attributes to a map
Examples	Recipe basics - creating an unfiltered tileset Country boundaries - limiting geographic area Roads - ranking and simplifying linestrings
Documentation	How to use MTS Tutorial: Get started using Mapbox Tiling Service and the Tilesets CLI MTS documentation
Pricing	MTS use is billed by tileset processing and tileset hosting. The cost of each of these line items depends on the area of your tiled data and the precision level of your tileset. For details, see the MTS pricing page.

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.


Pros	Accepts many common geospatial file types Normalizes projections Generates tiles at multiple zoom levels
Cons	No options to control how your data is uploaded Cannot optimize tilesets for performance or cost
Recommended for	Programmatically uploading raster data to create tilesets
Use cases	Aerial and satellite imagery pipelines Weather, insurance, and first responder applications
Documentation	Tutorial: Upload to Mapbox using cURL Uploads API reference
Pricing	Use of the Uploads API is billed by tileset processing and tileset hosting. The cost of each of these line items depends on the area of your tiled data and the precision level of your tileset. For details, see the Uploads API pricing page.

book

Note

While you can create vector tilesets using the Uploads API as well, Mapbox Tiling Service (MTS) is a much better tool to use for the task. For more information about using MTS to upload tilesets, see the MTS section of this guide.

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).


Pros	No coding necessary Drag-and-drop interface Accepts GeoJSON, JSON, and CSV files Convert to a tileset in the same interface
Cons	Smaller upload limit than exists with the Datasets API (20 uploads per month, versus unlimited uploads)
Recommended for	Small-to-medium data sets (the dataset editor can only display datasets of 20 MB or smaller, though larger datasets can be downloaded and accessed through the Datasets API)
Use cases	Getting started quickly
Documentation	Tutorial: Add points to a web map Part 1 Mapbox Studio Manual

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.


Pros	Fine-grained control over dataset features
Cons	Two-step process (first creating an empty dataset, then uploading data to it) To convert your dataset to a tileset, you must switch tools to use either Studio or the Uploads API
Recommended for	Programmatically uploading data to create datasets
Use cases	Automated pipeline for uploading and updating your datasets
Documentation	Datasets API documentation

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!