Create new data

A dataset is an editable collection of GeoJSON features. 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.

Mapbox Studio dataset editor

Use the dataset editor to create and manage your data

Dataset

Sample GeoJSON FeatureCollection

{
  "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 is shown 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.

How datasets work

Datasets are a hosted version of your raw data as GeoJSON. You can access and edit your datasets with the dataset editor or the Mapbox Datasets API.

Format

{
    "id": "{feature_id}",
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [0, 0]
    },
    "properties": {
        "name": "null island"
    }
}

Datasets are stored as GeoJSON, a format for encoding a variety of geographic data frequently used by Mapbox web services and APIs. Based on JSON (JavaScript object notation), GeoJSON is native to the JavaScript language and can be parsed in modern software.

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.

Dataset to tileset process

You cannot add datasets directly to styles in the Mapbox Studio style editor. However, 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.

You can read more about how raw data becomes a tileset in the Upload data guide.

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 datasets section of the Mapbox Studio Manual.

Creating datasets

You can create a dataset from scratch in the Mapbox Studio dataset editor or through the Mapbox Datasets API. Note that the process involves two steps in each case: creating an empty dataset, and adding features to that dataset.

Mapbox Studio

In Mapbox Studio, you can use the dataset editor to create a new dataset using a visual interface rather than writing the GeoJSON directly. To create a dataset with the Mapbox Studio dataset editor, you can either create a new empty dataset and add features to it by drawing them in the dataset editor, or you can upload a GeoJSON or CSV file as a dataset and edit, add, and delete features using the dataset editor interface.

You can learn more about how to create datasets using the Mapbox Studio dataset editor in the Mapbox Studio Manual.

Mapbox Datasets API

Using the Mapbox Datasets API, you can add features by making requests to either insert a feature or to batch add features. You cannot upload a file directly through the Datasets API. The Datasets API accepts one Feature at a time. If you would like to add a number of Features from a FeatureCollection, you can do so programmatically.

You can read more about how to programmatically update datasets in the Mapbox Datasets API documentation.