Mapbox Tiling Service

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"}}

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.