Create new data

Datasets and tilesets are two different formats that you can create when uploading data to your Mapbox account. Datasets are editable and tilesets are styleable.

Datasets

A dataset is an editable collection of GeoJSON features. Datasets provide access to feature geometries (points, lines, and polygons) and properties (attributes).

What are datasets used for?

Consider using a dataset if you are working with less complex data that needs to be updated often. It is important to note that once your dataset has been created, it will need to be published into a tileset before you can add it to a style in the Mapbox Studio style editor. With datasets, you can continue to make changes to your data as needed, publish each update to the connected tileset, and see those changes reflected in any styles that contain that tileset.

How datasets work

Unlike tilesets, datasets can be edited on a feature-by-feature basis. Datasets cannot be used directly in a Mapbox Studio style, but can be exported as a tileset or rendered with Mapbox GL JS. Any dataset exported to a tileset can be added as a layer in the Mapbox Studio style editor. To see a diagram of that workflow, see the sample workflow section of the Mapbox Studio Manual.

Mapbox stores dataset features as collections of GeoJSON features. Features are individual (or in some cases groups of) points, lines, or polygons. The Mapbox Datasets API does not support GeometryCollections or null geometries. Each feature is defined by its geometry and properties:

• Geometry: This describes the shape and the location of each feature. You can specify Points, LineStrings, Polygons. The location and the exact shape of each feature is determined by the coordinates that are specified.
• Properties: This can contain any JSON object. Some examples of common properties that are applied to Mapbox datasets include title and description to include in popups in a web application.

Datasets can be uploaded to Mapbox using the following formats:

Dataset format

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": "marker-iv1qi3x10",
        "title": "Burnham Park",
        "description": "A lakefront park on Chicago's south side.",
        "marker-size": "medium",
        "marker-color": "#1087bf",
        "marker-symbol": "marker-blue"
      },
      "geometry": {
        "coordinates": [
          -87.603735,
          41.829985
        ],
        "type": "Point"
      },
      "id": "0de616c939ce2f31676ff0294c78321b"
    },
    {
      "type": "Feature",
      "properties": {
        "id": "marker-iv1r2v427",
        "title": "Jackson Park",
        "description": "A lakeside park that was the site of the 1893 World's Fair",
        "marker-size": "medium",
        "marker-color": "#1087bf",
        "marker-symbol": "marker-orange"
      },
      "geometry": {
        "coordinates": [
          -87.580389,
          41.783185
        ],
        "type": "Point"
      },
      "id": "207437833677b4c5af354906d54fda84"
    },
    {
      "type": "Feature",
      "properties": {
        "id": "marker-iv1qkj6v1",
        "title": "Calumet Park",
        "description": "A park on the Illinois-Indiana border featuring a historic fieldhouse.",
        "marker-size": "medium",
        "marker-color": "#1087bf",
        "marker-symbol": "marker-green"
      },
      "geometry": {
        "coordinates": [
          -87.530221,
          41.715515
        ],
        "type": "Point"
      },
      "id": "268b9f0edfdc3a8a2a021f019164eaef"
    },
    {
      "type": "Feature",
      "properties": {
        "id": "marker-iv1qs0u84",
        "title": "Garfield Park",
        "description": "Home of the Garfield Park Conservatory.",
        "marker-size": "medium",
        "marker-color": "#1087bf",
        "marker-symbol": "marker-blue"
      },
      "geometry": {
        "coordinates": [
          -87.716002,
          41.882102
        ],
        "type": "Point"
      },
      "id": "451e1a14ee747776c48d459c52905cac"
    },
    {
      "type": "Feature",
      "properties": {
        "id": "marker-iv1qq1kl3",
        "title": "Douglas Park",
        "description": "A large park near in Chicago's North Lawndale neighborhood",
        "marker-size": "medium",
        "marker-color": "#1087bf",
        "marker-symbol": "marker-orange"
      },
      "geometry": {
        "coordinates": [
          -87.699329,
          41.860092
        ],
        "type": "Point"
      },
      "id": "4aaa9df412c62b53eeab4b16ec0ea825"
    },
    {
      "type": "Feature",
      "properties": {
        "id": "marker-iv1r4bs18",
        "title": "Lincoln Park",
        "description": "A northside park that is home to the Lincoln Park Zoo",
        "marker-size": "medium",
        "marker-color": "#1087bf",
        "marker-symbol": "marker-blue"
      },
      "geometry": {
        "coordinates": [
          -87.637596,
          41.940403
        ],
        "type": "Point"
      },
      "id": "7459e13bb6d8ecd1c797e2c168a6ad91"
    },
    {
      "type": "Feature",
      "properties": {
        "id": "marker-iv1qnmnw2",
        "title": "Columbus Park",
        "description": "A large park in Chicago's Austin neighborhood",
        "marker-size": "medium",
        "marker-color": "#1087bf",
        "marker-symbol": "marker-orange"
      },
      "geometry": {
        "coordinates": [
          -87.769775,
          41.873683
        ],
        "type": "Point"
      },
      "id": "a0a6bbc358a34ccea8687f8fee527964"
    },
    {
      "type": "Feature",
      "properties": {
        "id": "marker-iv1qtkep5",
        "title": "Grant Park",
        "description": "A downtown park that is the site of many of Chicago's favorite festivals and events",
        "marker-size": "medium",
        "marker-color": "#1087bf",
        "marker-symbol": "marker-orange"
      },
      "geometry": {
        "coordinates": [
          -87.619185,
          41.876367
        ],
        "type": "Point"
      },
      "id": "acba288f3abd79014145bc16e83fbc78"
    },
    {
      "type": "Feature",
      "properties": {
        "id": "marker-iv1r12m56",
        "title": "Humboldt Park",
        "description": "A large park on Chicago's northwest side",
        "marker-size": "medium",
        "marker-color": "#1087bf",
        "marker-symbol": "marker-green"
      },
      "geometry": {
        "coordinates": [
          -87.70199,
          41.905423
        ],
        "type": "Point"
      },
      "id": "be73854ebca0a6397ce0b63e06852b50"
    },
    {
      "type": "Feature",
      "properties": {
        "id": "marker-iv1r541d9",
        "title": "Millennium Park",
        "description": "A downtown park known for it's art installations and unique architecture",
        "marker-size": "medium",
        "marker-color": "#1087bf",
        "marker-symbol": "marker-green"
      },
      "geometry": {
        "coordinates": [
          -87.622554,
          41.882534
        ],
        "type": "Point"
      },
      "id": "f919f7ec1e3bf88e776772311af3b151"
    }
  ]
}

In this example, you can see a visual representation of a dataset inside the Mapbox Studio dataset editor on the left and the actual contents of the dataset, a GeoJSON FeatureCollection, on the right. The contents of the dataset include geometry and properties for each point that you can see on the left, but does not contain any style information. For more details on how to style the points (for example, specify the symbols, colors, and the font for labels), see the Upload data guide, which covers converting datasets to tilesets.

Downloading datasets

Once you’ve created a dataset, you can export it to a tileset for use in a Mapbox map (see the How map design works guide for more information), download it as a GeoJSON FeatureCollection, or access it with the Mapbox Datasets API. Datasets can still be edited after export, but you will need to make sure to sync your downloaded version with your new edits if you would like your local copy to reflect any changes you've made.

To learn how to download and export datasets, see the manage datasets section of the Mapbox Studio Manual.

Dataset to tileset process

You cannot add datasets directly to styles in the Mapbox Studio style editor. But you can export your dataset as a tileset and add it to your style in the Mapbox Studio style editor or Mapbox GL JS. When you export your dataset to a tileset, it is processed in the same way an upload would be processed.

To learn how to convert a dataset to a tileset using the Mapbox Studio dataset editor, see the dataset editor section of the Mapbox Studio Manual.

Tilesets

Tilesets are lightweight collections of map data that are optimized for rendering and are not editable but can be styled in the Mapbox Studio style editor.

What are tilesets used for?

Consider uploading your data as a tileset if your data is large and doesn't need to be updated often.

If you created a vector tileset by uploading geospatial data that contains attributes, the resulting vector tileset will inherit the attributes contained in your raw data source. Here are a few examples of what you can do with the attributes belonging to features in a vector tileset:

• Use Mapbox Studio to customize the color of a state based on its population density.
• Use Mapbox GL JS to highlight counties that share a similar name.

How tilesets work

When you upload data as a tileset or export a dataset as a tileset, Mapbox breaks it up into a uniform grid of square tiles at preset zoom levels. It must undergo many processing steps to load quickly and be lightweight.

When you use either the Uploads API or Mapbox Studio (which uses the Uploads API behind the scenes) to turn data into a tileset, two things happen:

1. Simplification: The Mapbox Uploads API analyzes your data for complexity and automatically removes unnecessary vertices at variable rates depending on zoom level. This process is called simplification, and it helps make sure your maps load quickly, especially at lower zoom levels where additional complexity would not be visible.
2. Determining the zoom extent. The Mapbox Uploads API keeps your tilesets light by examining your data's extent (the geographic area covered by your data) and complexity and only creates vector tiles for zoom levels that are likely to be required — a zoom extent is defined. For datasets with small zoom extents or complex features, this usually means low zoom levels (zoomed out) will be discarded. For large features that are not complex, this usually means higher zoom levels (zoomed in) will be discarded. If you need your tileset to be visible at a different zoom extent, you can adjust this manually, but it is important to note the following:

• Minimum zoom levels can be increased, but not decreased past the assigned minimum zoom level.
• Maximum zoom levels can be decreased and increased, since data can be overzoomed and visualized to zoom 22.

If you use Mapbox Tiling Service to turn data into a tileset, you will set the simplification level and the zoom extent in the tileset recipe.

You can create tilesets by uploading data in any of the following formats:

Raster and vector tilesets

Tilesets can be created with raster or vector data.

If you upload raster data (such as a GeoTIFF), the resulting raster tilesets will only contain raster data, a pixel-based data format that all digital photographs conform to.

If you upload vector data, this will create a vector tileset containing vector data, which consists of mathematically calculated points, lines, and polygons as coordinate pairs. Mapbox GL takes advantage of vector tilesets by calculating and rendering vector data directly in your browser.