Skip to main content

Datasets

You can use the Mapbox Studio dataset editor to import, create, and edit point, line, and polygon features and their properties. A collection of these features in Mapbox is called a dataset. Datasets can either be downloaded as GeoJSON or exported to tilesets for use in Mapbox styles (see the Guides for more information).

Mapbox Studio topics covered in this section:

with the dataset editor

Upload

with the dataset editor

Dataset

by exporting your dataset

Tileset

on the styles page

Template style

in the style editor

Custom style

containing your tileset in the style editor

Add data to style

in the style editor

Style data

in the style editor

Publish

What is a dataset?

A dataset is an editable collection of GeoJSON features. Datasets are distinct from tilesets in that datasets can be edited on a feature-by-feature basis, but cannot be used directly in Mapbox Studio style.

Any dataset you create can be exported to a tileset, which can be then added as a layer in the Mapbox Studio style editor.

Downloading and exporting datasets

Once you've created a dataset, you can export it to a tileset for use in a Mapbox map (see Style editor for more information), download it as a GeoJSON FeatureCollection, or use it with the Datasets API. Datasets can also be edited after export. To learn how to download and export datasets, see below.

Dataset editor

In addition to managing datasets, Mapbox Studio provides an in-browser editor for creating and modifying dataset features.

Change dataset name

Export to tileset

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu
A diagram of the Mapbox Studio dataset editor.

Manage features

Map canvas

Toolbar

Export to tileset

To add your data to a style in the Mapbox Studio style editor, you need to export your dataset to a tileset.

  • Save. After you have finished editing your dataset, click Save to review the changes you have made.

  • Export. Click Export to export your dataset to a vector tileset. A vector tileset is a collection of data broken up into a uniform grid of square tiles at up to 22 preset zoom levels. Your tilesets are stored on the Tilesets page in your Mapbox account, and tilesets created through dataset export have a reference back to the original dataset. See the Uploads section for more information on using tilesets.

If you need to make further changes to your data, you can change a dataset after you have exported to a tileset and re-export to have those changes reflected in the tileset. If you update a connected tileset, any styles that reference that tileset will also be updated automatically.

Manage features

Features are individual points, lines, or polygons in your dataset. In the dataset editor you can add, change, and delete features in your dataset.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu
Illustrates how to draw new features using the draw tools, add new data properties to features by clicking the feature on the map and using the '+ Add property' button, and change the map style below your data to a satellite map using the 'Background style' button.

Add new features: You can add new features to an existing dataset by either importing them from a data file or drawing them directly in the editor. Adding new features to a dataset does not overwrite existing features. If you import a data file that contains a feature that already exists in the dataset, this will duplicate the feature.

  • plus Import. You can import data into your dataset from a GeoJSON or CSV file. If using a CSV, make sure that the data is already geocoded and represents point features.
  • Draw tools. Use the draw tools to draw features directly on the map. You can change the geometry, placement, and properties of existing features with the dataset editor's draw tools:
    • marker Draw a point
    • line Draw a line
    • polygon Draw a polygon
  • search Search places. You can search places in the toolbar. When you search for a country, region, postcode, place, locality, neighborhood, or address you will have the option to Save to dataset. This option is not available when searching POIs.

Edit feature properties: You can add, edit, and delete feature properties using tools in the panel on the left side of the dataset editor. You can also view feature properties in GeoJSON form by clicking the GeoJSON tab.

book
Replacing features in a dataset
  • Neither the Mapbox Studio dataset editor nor the Mapbox Datasets API supports the ability to replace all data in a dataset. To replace features in an existing dataset you can use either the Datasets API or the Mapbox Studio dataset editor to update individual features, or delete every feature individually and then insert new features.
edit properties dataset editor

Map canvas

You can interact directly with the features in your dataset on the map to draw, change or delete features.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu
Illustrates how to edit the geometry and properties for one feature on the map.
  1. Geometry. Change the geometry by clicking on the feature, then clicking and dragging the points.
  2. Placement. Hover over the feature until you see position, then click and drag to move the feature.
  3. Properties. To change the properties of a feature, click on the feature and edit properties in the panel on the left side of the editor.

You can delete a feature by selecting the feature and clicking trash. You can select and delete multiple features at once using Shift + click + drag.

Toolbar

The toolbar in the upper right will help you navigate the dataset editor.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu
Clicks through the toolbar, revealing options for searching the dataset, changing the background style, adding a reference tileset, viewing a history of your edits, and keyboard shortcuts.

search Search places

search Search places search bar allows you to search for locations on the map. You can find this button on the top right. Type in what you're looking for and select the result and search will take you to the exact location. This search is powered by the Mapbox Geocoding API.

search-places-dataset

search Search dataset

You can use search Search dataset to search your dataset by a property value. The search will return all features that contain that property value. Click on the thumbnail to jump to the feature on the map.

search-within-dataset

paint Background style

Use the paint Background button to switch between background styles. These include the default dataset editor style, Mapbox Satellite, Mapbox Satellite Streets, and an empty canvas.

change-backgrounds-dataset

tileset Reference tileset

In addition to the pre-loaded background layers, you can display a custom raster tilesets (such as your own custom satellite imagery, for example) between the basemap and your data as a reference for drawing new GeoJSON features. Click tileset Reference tileset and select the tileset you would like to add. Note that this must be a raster tileset uploaded to your account. You can remove the raster tileset by clicking Deselect close or by clicking on the active tileset.

history History

View your history by clicking the history History button. The dataset keeps a history of all changes you made since the beginning of your current session. You can revert your changes in the current session, but your history will reset once you exit the dataset editor.

question Help

question Help button includes the option to see a guided walkthrough of the dataset editor. As you scroll through this panel, you will see a list of keyboard shortcuts. At the top of the help panel, there are links to Mapbox Help and our contact page.

Dataset information page

For each dataset, there is a dataset information page where you can review the tilesets that are connected to that dataset and do the same tasks that you can in the menu on the Datasets page.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu
Screenshot of the page in Mapbox Studio that lists detailed information about one dataset including any connected tilesets, the dataset ID, the size, the feature count, and the bounds.

Connected tilesets

The center of the dataset information page contains a list of all connected tilesets, which can be added to your styles as new custom layers.

The same items that exist in the menu for each dataset on the Datasets page are listed on the right side of the dataset information page. See the menu section for more details.

Dataset characteristics

In the lower right side of the dataset information page, there are several characteristics that are listed for each dataset.

  • Size. Size of the dataset.
  • Feature count. The number of features included in the dataset.
  • Bounds. The coordinate bounds the dataset resides within, which are both listed and displayed on a satellite map.

Edit dataset

Click pencil Edit to open the dataset editor and make changes to the dataset.

You can use the Mapbox Studio dataset editor to import, create, and edit point, line, and polygon features and their properties. A collection of these features in Mapbox is called a dataset. Datasets can either be downloaded as GeoJSON or exported to tilesets for use in Mapbox styles (see the Guides for more information).

Mapbox Studio topics covered in this section:

with the dataset editor

Upload

with the dataset editor

Dataset

by exporting your dataset

Tileset

on the styles page

Template style

in the style editor

Custom style

containing your tileset in the style editor

Add data to style

in the style editor

Style data

in the style editor

Publish

What is a dataset?

A dataset is an editable collection of GeoJSON features. Datasets are distinct from tilesets in that datasets can be edited on a feature-by-feature basis, but cannot be used directly in Mapbox Studio style.

Any dataset you create can be exported to a tileset, which can be then added as a layer in the Mapbox Studio style editor.

Downloading and exporting datasets

Once you've created a dataset, you can export it to a tileset for use in a Mapbox map (see Style editor for more information), download it as a GeoJSON FeatureCollection, or use it with the Datasets API. Datasets can also be edited after export. To learn how to download and export datasets, see below.

Manage datasets

Your Datasets page in Mapbox Studio provides a list of your existing datasets as well as a link to create a new dataset.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu
Screenshot of the page in Mapbox Studio that lists all the datasets in your account.

Search datasets

Use the search Search bar to filter or reorder your list of datasets. You can search for datasets by name or dataset ID and sort by name or date modified.

Create a dataset

To create a new dataset, click the New dataset button at the top of the page. You can either start with a blank dataset or upload data as a starting point for your dataset.

If you start with a blank dataset, see the manage features section of this guide to learn how to add, change, and delete features in your dataset.

If you upload data to create a new dataset, it must be in one of the accepted data formats. The dataset upload process in Studio assigns a new id to each feature in your source data file. See the Datasets API documentation for more information on how the feature object is formatted. If your workflow relies on features in your dataset having specific IDs, we recommend that you add a new field to the feature's properties object in your source file rather than setting it in the feature's id field, since this field will be overwritten when your file is uploaded as a dataset in Studio.

Once your dataset is created, it opens in the dataset editor for editing.

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu
animated gif showing how to upload a dataset in Mapbox Studio
book
Datasets restrictions and limits
  • When you are uploading data to a dataset, that data must be in one of the accepted data formats.
  • You can upload an unlimited number of files to any dataset in the Mapbox Studio dataset editor, but these files must be loaded 5 MB at a time.
  • While datasets do not have a size limit, the Mapbox Studio dataset editor cannot display datasets larger than 20 MB. Datasets larger than 20 MB can still be downloaded from your Datasets page and accessed through the Mapbox Datasets API.

Once a dataset is created, it will appear in the list on your Datasets page. There are several actions you can take with each dataset.

share View details

Open the dataset information page for this data to see more details.

tileset Export to tileset

Once exported, the tilesets can be added as a new custom layer to a Mapbox map in the Mapbox Studio style editor. You can also add a tileset directly to a web map by using Mapbox GL JS like in this example.

arrow-down Download

Once created, you can download your data as a GeoJSON file to use with Mapbox GL JS or other web mapping applications.

trash Delete

Tileset deletion cannot be undone. Any tilesets that were derived from this dataset will stay intact, but you will no longer be able to update the data associated with those tilesets in the dataset editor.

clipboard Dataset ID

Each dataset has a unique ID. Use this ID when interacting with your dataset using the Mapbox Datasets API.