Skip to main content

Tileset sources

A tileset source is raw geographic data formatted as line-delimited GeoJSON and uploaded to Mapbox. Tileset sources are necessary to use Mapbox Tiling Service (MTS) to create a new vector tileset. A tileset source can be composed of up to 10 files.

A tileset source can be referenced in each layer of a tileset recipe using an ID. This example recipe shows the source field:

"trees": {
"source": "mapbox://tileset-source/{username}/trees-data",
"minzoom": 4,
"maxzoom": 8
}

The same tileset source can be reused across multiple tilesets and multiple layers of tilesets an unlimited number of times. If your data is not changing, then you do not need to upload it every time you want to create a tileset. Instead, you would Publish your tileset..

Line-delimited GeoJSON

MTS requires that you format tileset sources as line-delimited GeoJSON (uncompressed line-delimited sequences of GeoJSON features). Unlike features being collected under a FeatureCollection array, like in GeoJSON, features in line-delimited GeoJSON are separated by newline characters in the file. Putting each feature on its own line makes it faster and easier to process individual features.

For example:

{"type":"Feature","id":1,"geometry":{"type":"Point","coordinates":[115.7,12.2]},"properties":{"name":"cool feature"}}
{"type":"Feature","id":2,"geometry":{"type":"Point","coordinates":[125.7,12.2]},"properties":{"name":"neat feature"}}
{"type":"Feature","id":3,"geometry":{"type":"Point","coordinates":[135.7,12.2]},"properties":{"name":"bad place"}}
{"type":"Feature","id":4,"geometry":{"type":"Point","coordinates":[105.7,12.2]},"properties":{"name":"good place"}}

The values in feature.properties cannot be an object or an array according to the Mapbox vector tile spec. Any non-primitive types included in feature.properties will be dropped when you publish your tileset source to MTS.

Convert GeoJSON to line-delimited GeoJSON

MTS Data Sync and the Tilesets CLI automatically convert GeoJSON to line-delimited GeoJSON:

Convert other data formats to line-delimited GeoJSON

If your source data is in a vector format other than GeoJSON, such as a Shapefile or KML, you need to convert it to line-delimited GeoJSON before using it to create a tileset source. The Fiona CLI tool fio outputs line-delimited GeoJSON by default and is a good option for converting files.

Here is an example converting a Shapefile into a line-delimited sequence of GeoJSON features:

$ fio cat ~/data/countries.shp > countries.ldgeojson.ld

The ogr2ogr utility from GDAL (version 2.4) can also convert many data formats to line-delimited GeoJSON:

$ ogr2ogr -f GeoJSONSeq countries.ldgeojson.ld ~/data/countries.shp

Validate line-delimited GeoJSON

You can use the Tilesets CLI to validate the line-delimited GeoJSON in a tileset source file by using the command:

$ tilesets validate-source path/to/your/data.json

To learn more about this command and other Tilesets CLI functions, see the Tilesets CLI documentation.

GeoJSON coordinate system

Line-delimited GeoJSON must use the OGC:CRS84 coordinate reference system. In other words, it must use longitude and latitude, in that order, decimal degrees, and the WGS84 coordinate system.

Feature IDs in MTS

MTS allows you to define which field in your tileset source to use as the identifier for your features. By default, MTS will use the top-level id field in each GeoJSON feature. You can override this with the rules defined in the Recipe reference section on IDs.

Specifying the IDs for each feature allows you to use feature state, a set of user-defined attributes that can be dynamically assigned to a feature on a map. Feature state relies on each feature in a tileset source having a unique numeric id to work correctly.

Modify a tileset source

After you publish a tileset using a tileset source, the tileset no longer directly references its tileset source. So if an existing tileset source is modified (deleted, replaced, or appended to), this modification will not be reflected in the tilesets that were created using the tileset source.

Delete a tileset source

If you no longer need a tileset source, you should manually delete it after any related tilesets are finished processing using the Delete a tileset source endpoint. Any tilesets that were created using this tileset source will continue working normally. But if you begin a new publish job using the Publish a tileset endpoint using the deleted tileset source, the publish job will fail.

Replace a tileset source

When you replace an existing tileset source with new source data using the Replace a tileset source endpoint, any existing tilesets that were created using the original tileset source will not be modified. To see these changes reflected in a tileset, begin a new publish job using the Publish a tileset endpoint. This will process the modified tileset source according to your tileset recipe, and the updated tileset will reflect the changes to the tileset source.

Append to a tileset source

When you append new source data to a tileset source using the Append to an existing tileset source endpoint, the tileset source will be modified to include the newly uploaded data. But any existing tilesets that were created using this source will not be modified. To see these changes reflected in a tileset, begin a new publish job using the Publish a tileset endpoint. This will process the modified tileset source according to your tileset recipe, and the updated tileset will reflect the changes to the tileset source.

Was this page helpful?