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.
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.
If you need to reproject your data or change its coordinate system, consider using third-party tools like GDAL's ogr2ogr or QGIS
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.
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 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:
File type | Datasets | Tilesets | Transfer limits |
---|---|---|---|
CSV | 5 MB for datasets 1 GB for tilesets | ||
GeoJSONOGC:CRS84 | 5 MB for datasets 1 GB for tilesets | ||
GeoTIFF | 10 GB | ||
GPX | 260 MB | ||
KML | 260 MB with 15 layers or fewer | ||
MBTiles | 25 GB | ||
Shapefile | 260 MB (combined uncompressed size of .shp and .dbf files). You must upload shapefiles as a compressed (.zip ) file. |
An extra note on dataset uploads: Multiple files can be uploaded to the same dataset without limit — they need to be loaded 5 MB at a time in the Mapbox Studio dataset editor. The size of a dataset is unlimited, but the Mapbox Studio dataset editor can only display datasets of 20 MB or smaller. Datasets that exceed 20 MB can still be downloaded from Mapbox Studio and accessed through the Mapbox Datasets API.
When uploading raster MBTiles to Mapbox Studio, be sure to use 512x512 tiles.
Tools for uploading tilesets
Mapbox offers three products that can be used to upload data as a tileset:
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 |
|
Cons |
|
Recommended for |
|
Use cases |
|
Examples | |
Documentation |
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 |
|
Cons |
|
Recommended for |
|
Use cases |
|
Examples | |
Documentation | |
Pricing |
|
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 |
|
Cons |
|
Recommended for |
|
Use cases |
|
Documentation | |
Pricing |
|
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 |
|
Cons |
|
Recommended for |
|
Use cases |
|
Documentation |
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 |
|
Cons |
|
Recommended for |
|
Use cases |
|
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!