Skip to main content

Vector Recipe

Additional Developer Resources

Current version: 1

A vector recipe is a JSON document containing configuration options that tell Mapbox Tiling Service (MTS) how to turn tileset source data into vector tiles.

Recipes must be constructed according to the rules in this recipe reference.

Recipe top-level fields​

A recipe is a JSON object that must contain the following top-level fields:

Required fieldsDescriptionData type
version The version of the Mapbox Tiling Service recipe reference that the recipe uses.Integer
layers The names of the layers and their configuration options.Object<String, LayerObject>

The recipe can contain the following top-level optional field:

Optional fieldsDescriptionData type
fillzoom The zoom level from which to generate overzoomed tiles, if there are no tiles at the maximum zoom level.Integer
{
  "version": 1,
  "fillzoom": 7,
  "layers": { layername: LayerObject, ... }
}

Recipe version​

The recipe version indicates the version of the Mapbox Tiling Service recipe reference that the recipe uses. The current version is 1. Using any version other than the current version or a previous version will result in an error.

Fillzoom​

Fillzoom defines a level from which to generate overzoomed tiles. Normally, MTS generates overzoomed tiles from tiles at the maximum zoom level. If you specify fillzoom and MTS cannot find tiles at the maximum zoom level, it generates overzoomed tiles from the fillzoom level.

For example, in a recipe with a maximum zoom level 10 and fillzoom level 7 specified, a request for a z11 tile will use z10 parent tiles to generate the new, overzoomed z11 tile. If there are no tiles at z10, a request for a z11 tile will use the z7 tiles instead.

Note
If a feature is subject to a zoom filter in the recipe and has a maxzoom attribute in the tileset source determining the highest zoom level at which the feature can appear, it will not appear at zoom levels higher than the maxzoom. But, if fillzoom is specified in the recipe, the feature may still appear at higher zoom levels if the tile it belongs to contains no other features. This is a rare but expected case. For an example of using a maximum zoom filter, see the Feature filters section.

Layers​

The recipe layers object contains key-value pairs associating the names of tile layers with their configuration. For each key-value pair, the key is the name of the layer, and the value is a LayerObject containing the configuration and options for the layer.

Each layer must have a name (for example "trees", "parks", and "paths" in the example below). This is the unique identifier for the layer of data in your final tileset. In any tileset, each layer name must be unique. The layer name must be a string with only underscores (_) and alphanumeric characters.

The corresponding LayerObject for each layer name describes how that vector tile layer should be created. It specifies where to retrieve source data, the precision of the data through zoom levels, and how to transform features and render them into tiles.

Layer example​

The simplest example tileset recipe includes a layer name, a tileset source ID, a minimum zoom value, and a maximum zoom.

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

Multilayer recipes​

Recipes can also contain definitions for multiple layers. This format can be used to create multilayer tilesets. Recipes can have a maximum of 20 layers defined.

{
  "version": 1,
  "layers": {
    "trees": { ... },
    "parks": { ... },
    "paths": { ... }
  }
}

Although you can refer to multiple tilesets from the same style, a single multilayer tileset can contain more layers and can be accessed more quickly over the network than a composite of multiple single-layer tilesets.

Layer configuration​

These are the required top-level fields for each layer:

Required fieldsDescriptionData type
source The source data to use for this layer. For more information about this field, see the Tileset source section.String
minzoom The lowest zoom level for the tileset. For more information about this field, see the Zoom levels section.Integer
maxzoom The highest zoom level for the tileset. For more information about this field, see the Zoom levels section.Integer

Tileset source​

The features that make up each layer come from a tileset source, which is a collection of geographic data stored as line-delimited GeoJSON on Mapbox.com. Tileset sources can be created using MTS's Create a tileset source endpoint.

Zoom levels​

Each tileset layer contains tiles at one or more zoom levels that will be visible at different times as the user zooms in and out of the map.

The minzoom and maxzoom configurations control the zoom levels at which your data will be tiled. They are required for a recipe. These values must be integers. The minzoom must be less than or equal to maxzoom, and both must be between the values of 0 and 16.

Note
maxzoom does not limit the zoom level your maps can be viewed at, as long as your layers all have the same maxzoom. Your map will still zoom past the max zoom in your recipe because of overzooming. If you do have a different maxzoom in different layers, only the layers with the highest maxzoom will be overzoomed.

The minimum and maximum zoom levels you choose directly impact the time it takes MTS to finish processing your data. Each additional zoom level increases the amount of data in the resulting tileset exponentially. So it’s important to first consider the use cases your map is trying to solve for when choosing your minzoom and maxzoom zoom levels so that you don't incur any performance costs unnecessarily.

The following table will help you decide the appropriate minzoom and maxzoom based on your data precision:

Zoom levelPrecision in feetPrecision in metersUse CaseExample
032000 ft10000 m
116000 ft5000 m
28000 ft2500 m
34000 ft1250 m
42000 ft600 m
51000 ft300 m
6500 ft150 m
7250 ft80 m
8125 ft40 m
964 ft20 m
1032 ft10 mlow-resolution administrative boundaries (for example, countries and state boundaries)
1116 ft5 m
128 ft2 m
134 ft1 m
142 ft0.5 mhigh-resolution administrative boundaries (such as neighborhoods, census tracts, and towns), national park polygon data, national land use, and land cover polygon data
151 ft0.25 m
160.5 ft0.125 mbuilding/parcel polygon data, road polygon or line data, points of interest (such as hotels, restaurants, and venues)

Zoom levels greater than 16, which are applicable for use-cases like lane-level navigation maps or high-definition indoor maps, are not possible by default. If you have a use case that requires a zoom level greater than 16, reach out to us and let us know.

Additional layer options​

You can further refine the resulting tileset with the following optional fields:

Optional fieldsDescriptionData type
features Specifies the output on a per feature basis. For more information about this field, see the Feature configuration section.Object
tiles Specifies the output on a per tile basis. For more information about this field, see the Tile configuration section.Object

Layer configuration summary​

The following describes every available field for a LayerObject and the JSON type for that field.

{
  "source": String,
  "minzoom": Integer,
  "maxzoom": Integer,
  "features": {
    "id": Expression,
    "bbox": [ Number, Number, Number, Number ],
    "attributes": {
      "zoom_element": Array<String>,
      "set": Object<String, Expression>,
      "allowed_output": Array<String>
    },
    "filter": Expression<Boolean>,
    "simplification": Expression<Number>,
    "simplification": {
      "distance": Expression<Number>,
      "outward_only": Expression<Boolean>
    }
  },
  "tiles": {
    "bbox": [ Number, Number, Number, Number ],
    "extent": Expression<Number>,
    "buffer_size": Expression<Number>,
    "limit": [
      [ String, Expression<Boolean>, Integer, String ], ...
    ],
    "union": [
      {
        "where": Expression<Boolean>,
        "group_by": Array<String>,
        "aggregate": Object<String, String>,
        "maintain_direction": Boolean,
        "simplification": Expression<Number>,
        "simplification": {
          "distance": Expression<Number>,
          "outward_only": Expression<Boolean>
        }
      }, ...
    ],
    "filter": Expression<Boolean>,
    "attributes": {
      "set": Object<String, Expression>
    },
    "order": String,
    "remove_filled": Expression<Boolean>,
    "id": Expression,
    "layer_size": Integer
  }
}

Expressions​

When writing rules in a recipe document, you can use "expressions" to base them on the properties in your data. Example rules that you might specify in a recipe document could include:

  • Tile uploaded tornado data from zooms 5 through 16.
  • Only tile the most populated cities within a dataset at zooms less than 7, then from zooms 8 through 16, only tile the top 20 most populated cities or towns per tile.
  • Only tile the top 5 flood-affected regions by area from the uploaded dataset until zoom 10, at zoom levels greater than 10, only show flooded regions with an area greater than 8 pixels.

The expressions used to control recipe features are from the expression language described in the Expressions reference section, and are closely related to the expressions used in Mapbox GL styles.

Plain numbers, strings, true, false, and null are all valid expressions, so you don't need to learn all the details of the expression language to start using MTS.

Feature configuration​

The features configuration object is used to describe how features are individually processed into vector tiles. This field contains the following elements, which are applied in the order indicated in the list below:

Optional fieldsDescriptionData type
id Sets the ID of each feature. For more information about this field, see the ID expression section.Expression
bbox Clips each feature to the specified bounding box. For more information about this field, see the Bounding box section.Array<Number>
attributes Adds, removes, and modifies feature attributes. For more information about this field, see the Feature attributes section.FeaturesAttributesObject
filter Removes features that do not match a pattern. For more information about this field, see the Feature filters section.Expression<Boolean>
simplification Controls simplification of the feature geometry. For more information about this field, see the Feature simplification section.Expression<Number> or SimplificationObject

ID expression​

Each feature that is tiled by MTS must have a numeric or string ID that uniquely identifies it, which by default comes from the id field of the GeoJSON Feature object in the source. If no ID is present for a feature in the GeoJSON source, or if the provided ID is not a string or number, an ID will be randomly assigned by MTS.

If you want to use a value from a feature attribute (or some other calculation) for your feature's ID, you can use an expression to retrieve that attribute. For example, if you have an attribute called source_identifier, you can use it for the feature ID by specifying:

{
  "features": {
    "id": [ "get", "source_identifier" ]
  }
}

If you do not want your features to have an ID in the output tiles, or if you want to make additional changes to the ID, you can do this later in the recipe, in the Tiles section.

Read more about feature IDs and their custom operators in the "Identification" section.

Bounding box​

If you want to clip your features to a bounding box instead of creating tiles for the full geographic extent of your source data, you can specify the bounding box with bbox. It must contain an array of four numbers in this order: the minimum longitude, minimum latitude, maximum longitude, and maximum latitude. For example, if you wanted to clip all your features to the bounds of the state of Wyoming, you could specify:

{
  "features": {
    "bbox": [ -111, 41, -104, 45 ]
  }
}
PLAYGROUND
Location Helper

To experiment with bounding box values for your code, try our Location Helper.

Feature attributes​

The attributes configuration allows for manipulation of attribute data, generation of new attributes, and removal of attributes. The available options in the FeaturesAttributesObject are described below, and performed in the order they are listed:

Optional fieldDescriptionData type
zoom_element A list of attributes whose values vary by zoom level. For more information about this option, see the Zoom element section.Array<String>
set Adds feature attributes or changes the value of attributes. For more information about this option, see the Set attributes section.Object<String, Expression>
allowed_output A list of attributes that will appear in the final tileset. For more information about this option, see the Allowed output section.Array<String>

Zoom element​

You may want certain attributes to vary by zoom level. For example, you might want to provide abbreviated street names at low zoom levels and the full names at high zoom levels. You can specify which attributes are provided per zoom level in the source data by providing a zoom_element array in the attributes object.

For each attribute listed in the zoom_element, the final output attribute at zoom level N will be the Nth element in the array in the source data. If no zoom_element is defined, no attributes are altered. If the zoom level is greater than or equal to the number of elements in the array, the last element is used.

For example, the following recipe would specify that name should be treated as a zoom_element attribute:

{
  "features": {
    "attributes": {
      "zoom_element": [ "name" ]
    }
  }
}

The name attribute in individual GeoJSON features would then be expected to contain an array of possible name values by zoom level, like this:

{
  "type": "Feature",
  "geometry": { ... },
  "properties": { "name": [ null, null, "Main", "Main St.", "Main Street" ] }
}

Using the attributes from the GeoJSON above, this feature would have no name attribute at zoom levels 0 and 1, and would have "Main" at zoom level 2, "Main St." at zoom level 3, and "Main Street" at zoom levels 4 and above.

Set attributes​

You can add attributes or change the values of attributes by evaluating expressions in a set specification.

The set object contains key-value pairs where each key is the name of an attribute and each value is an expression that should be evaluated to provide the new value for that attribute.

Consider the following attributes for a single GeoJSON feature:

{
  "type": "Feature",
  "geometry": { ... },
  "properties": { "area": 12345, "population": 123, "name": "Smallville" }
}

If you wanted to add a new attribute, density, that is calculated from the population per area, and also to change the value of the name attribute to convert it to all capitals, you could use this recipe:

{
  "features": {
    "attributes": {
      "set": {
        "density": [ "/", [ "get", "population" ], [ "get", "area" ] ],
        "name": [ "upcase", [ "get", "name" ] ]
      }
    }
  }
}

If you specify multiple set operations, the order in which they will happen is not defined.

Allowed output​

If an allowed_output array is provided, only the attributes specified in the array will be saved to the tileset. This does not prevent the attributes that are not listed in the allowed_output from being used in filter expressions and other steps throughout the publish job; the other attributes are removed in the final step of processing.

In this example, features in the resulting tileset will only have two attributes, name_en and name_es:

{
  "features": {
    "attributes": {
      "allowed_output": [ "name_en", "name_es" ]
    }
  }
}

Feature filters​

The filter configuration is a single expression that results in a true or false evaluation. It is common to determine this result by considering the zoom level being created and an attribute of the feature. For example, if a feature has minzoom and maxzoom attributes to determine the zoom levels at which the feature appears, you can compare these attributes to the zoom level being created by specifying:

{
  "features": {
    "filter": [ "all",
      [ ">=", [ "zoom" ], [ "get", "minzoom" ] ],
      [ "<=", [ "zoom" ], [ "get", "maxzoom" ] ]
    ]
  }
}

Or you could exclude residential roads from zoom levels below 12 by specifying:

{
  "features": {
    "filter": [ "any",
      [ "!=", [ "get", "road" ], "residential" ],
      [ ">=", [ "zoom" ], 12 ]
    ]
  }
}

The filter specification is the primary way to control which features are allowed into the final tileset on a per-feature basis. If no filter is provided, by default a value of true is used for all features.

Feature simplification​

MTS normally simplifies the geometry of features so that at each zoom level they correspond to the resolution of the display screen. If you want to preserve additional detail or if you want to reduce tile size by further simplifying the geometry, you can specify a simplification to do that.

The simplification expression or value describes the maximum distance that a point can be from the straight line that connects its two neighbors, and still be considered to be effectively on the line and thus safe to remove. Any point with a distance that is larger than the simplification value is considered to be away from the line, and must be preserved.

As you increase the simplification value, the number of vertices in each feature decreases. The MTS recipe validator will reject any simplification value that is more than 4096 or less than 0. If you do not specify a value for simplification, MTS will use 4, the default value.

The resulting shape depends on the original shape of your feature. For instance, if your original feature is circular and you increase simplification, the result will look more like a polygon. If your original feature is a curved line and you increase simplification, the result will look more like a straight line.

The simplification may be a constant number, or it may be an expression that evaluates to a number. A typical use for an expression for the simplification would be to use a minimal simplification at the layer's maximum zoom level, so it can be overzoomed with high precision, but to use a larger simplification at lower zoom levels that will never be magnified far, as in the example below.

Note: Even if the simplification is specified as 0, complex features will receive additional simplification so that they can be rendered correctly by Mapbox GL. Polygons or MultiPolygons with more than 65535 vertices and LineStrings and polygon rings with more than 6553 points will be simplified to reduce their complexity to these limits.

MTS uses the Ramer–Douglas–Peucker algorithm to simplify features.

This sample recipe uses the normal simplification of 4 at most zoom levels, but reduces the simplification to 1 at the highest zoom level so that overzoomed tiles will look better.

{
  "minzoom": 0,
  "maxzoom": 10,
  "features": {
    "simplification": [ "case",
      [ "==", [ "zoom" ], 10 ], 1,
      4
    ]
  }
}

Simplification objects​

If the simplification is a SimplificationObject, it can contain the following fields:

Optional fieldDescriptionData type
distance Controls simplification of the feature geometry. For more information about this field, see the Simplification distance section.Expression<Number>
outward_only Places limits on polygon simplification to improve union quality. For more information about this field, see the Outward-only simplification section.Expression<Boolean>

This sample recipe simplifies features where type is rowhouse outward, so that MTS can union each block of row houses into a single block feature instead of leaving them as separate features. MTS then performs normal simplification on the row house blocks after it unions them to further reduce the tile size. MTS simplifies other building types normally and does not union them together.

{
  "features": {
    "simplification": {
      "outward_only": [ "==", [ "get", "type" ], "rowhouse" ]
    }
  },
  "tiles": {
    "union": [
      {
        "where": [ "==", [ "get", "type" ], "rowhouse" ],
        "simplification": {
          "outward_only": false
        }
      }
    ]
  }
}

Simplification distance​

The simplification distance is a numeric expression, as described in the Feature simplification section. It describes the maximum distance that a point can be from the straight line that connects its two neighbors, and still be considered to be effectively on the line and thus safe to remove. Any point with a distance that is larger than the simplification value is considered to be away from the line, and must be preserved. Larger values cause the feature geometry to become increasingly coarse.

Outward-only simplification​

If the outward_only expression evaluates to true, then Polygon and MultiPolygon features will be simplified only in ways that slightly increase their area, never in ways that slightly decrease their area, so the borders of adjacent polygons will often overlap slightly instead of sometimes being separated by small gaps. This will increase the quality of polygon unioning if the recipe contains a union rule, at the cost of increased tile size because of reduced opportunity for simplification. (See the "Feature union" section.)

Tile configuration​

The tiles object contains the following elements, which are applied in this order as each tile is being assembled from its component features:

Optional fieldDescriptionData type
bbox Clips each feature to the specified bounding box. For more information about this field, see the Tile bounding box section.Array<Number>
extent Sets the precision of a vector tile. For more information about this field, see the Tile extent section.Expression<Number>
buffer_size Keeps extra data from beyond the edge of each vector tile. For more information about this field, see the Buffer size section.Expression<Number>
limit Limits the number of features of a specified type that can appear in the tile. For more information about this field, see the Limit section.Array<LimitArray>
union Joins features based on whether a defined specified attribute matches. For more information about this field, see the Feature union section.Array<UnionObject>
filter Removes features that do not match a specified pattern. For more information about this field, see the Post-union filter section.Expression<Boolean>
attributes Adds attributes or changes the values of attributes. For more information about this field, see the Post-union attributes section.TilesAttributesObject
order Specifies the order of a sequence of features in the final output tile. For more information about this field, see the Order section.String
remove_filled Removes features that cover the entire tile. For more information about this field, see the Remove filled section.Expression<Boolean>
id Controls the ID of features in the final output tileset. For more information about this field, see the Tiles ID section.Expression
layer_size Sets the maximum allowed size (in KiB) of the tile layer. For more information about this field, see the Layer size section.Integer

Tile bounding box​

If you want to generate tiles for only a geographic subset of your data, so you can test a recipe without the time and expense of generating all the tiles, you can specify a bounding box with bbox. It must contain an array of four numbers in this order: the minimum longitude, minimum latitude, maximum longitude, and maximum latitude. Only the tiles that intersect this bounding box will be generated.

For example, if you wanted to generate only those tiles that include part of the state of Wyoming, you could specify:

{
  "tiles": {
    "bbox": [ -111, 41, -104, 45 ]
  }
}

Note that the tiles bounding box is only useful for testing, not for final tilesets. Because the sizes of tiles are different in each zoom level, different areas will come into view as you zoom in and out. To clip features consistently in every zoom level, use the features bounding box.

The reason to use the tiles bounding box instead of the features bounding box for testing is that with the tiles bounding box, exactly the same set of features appear in each tile as in the full tileset, so you your union and limit rules will have the same set of features to work with as in the final tiles. With the features bounding box, some of the features will already have been removed from consideration before the union and limit happen, so you may see different results from these than with the full tileset.

Tile extent​

You can change the geometric precision within each vector tile by setting the extent.

The extent is a precision control for vector tiles, and by default is 4096. In most situations, changing this value is not recommended. If you set this value, it must be a power of 2 between 256 and 8192. You may also set this number using an expression.

Buffer size​

Sets the size of the buffer that will be created around the edges of your vector tiles. buffer_size is a percentage of the size of a tile. The default buffer size is 0.5. Note that the value of this attribute cannot be larger than 100. An expression can also be used in buffer_size, but must still return a number between 0 and 100. Buffers are particularly helpful for label point layers to avoid cutting labels off at tile boundaries.

Limit​

A limitation rule that reduces the number of features for the specified type to a specific number, choosing the lowest or highest-numbered features according to some attribute.

The limit field must be an array of limitation rules, each of which is evaluated in sequence to potentially limit the total number of features to be included in the final tile. There are two ways in which data is limited using the limit field, where and where_in_distance.

The where style limits the total number of features in the tile and its buffer. Only the first number of features that match a filter-expression are kept and the rest are dropped from the tile. The sorting of these is based on attribute which is the key to a feature's attribute and either sorted lowest to highest or highest to lowest.

The format for a where style limit are the following syntaxes:

  • [ "lowest_where", filter-expression, number, attribute ]
  • [ "highest_where", filter-expression, number, attribute ]

The where_in_distance is the second style of limit and subdivides a tile into a grid of regions. Within each region only one feature is kept from the features selected by the filter-expression for the limit. The number of regions contained within a single tile is controlled by region_count. This should always be a value equal to 4 to a power in size (in other words, 1, 4, 16, 64, 256, 1024, 4096, or 16384). If the region_count is not equal to one of these numbers it will be rounded to the nearest one of these numbers in processing. The feature that is selected in each region is the one that has the highest or lowest value for the attribute named in the attribute field.

The format for a where_in_distance style limit are the following syntaxes:

  • [ "lowest_where_in_distance", filter-expression, region_count , attribute ]
  • [ "highest_where_in_distance", filter-expression, region_count , attribute ]

The only valid values for region_count are 1, 4, 16, 64, 256, 1024, 4096, or 16384.

These where_in_distance limit forms also cause the tile buffer for the limited features to be rounded down to a multiple of the buffer size corresponding to the region_count:

region_countassociated buffer size
1100
450
1625
6412.5
2566.25
10243.125
40961.5625
163840.78125

Feature union​

You can union features together if a specified set of their attributes match. The simplest case unions all features that have exactly the same attributes:

"tiles": { "union": [ { } ] }

The union specification object UnionObject can contain an expression to union only features that match the specified expression as well as having matching attributes:

Optional fieldDescriptionData type
where Selects which features are considered for this union.Expression<Boolean>
group_by Unions features where all the specified attributes are the same in each feature.Array<String>
aggregate Specifies how to handle other attributes that are not specified in group_by when features are unioned.Object<String, String>
maintain_direction Permits LineStrings to be reversed if it helps to connect them.Boolean
simplification Specifies how features will be resimplified after unioning, as described in the Feature simplification section.Number or SimplificationObject

Union where​

You can specify which features a union rule applies to by providing a where expression that selects a subset of features. For example, if your layer contains some building footprints that you want to union if they have the same height, and some parks that you want to union if they have the same maintainer, you could do this:

"tiles": {
  "union": [
    {
      "where": [ "==", [ "get", "type" ], "building" ],
      "group_by": [ "height" ]
    },
    {
      "where": [ "==", [ "get", "type" ], "park" ],
      "group_by": [ "maintainer" ]
    }
  ]
}

Union group_by​

Within a set of features that are union candidates, you can specify which of them should become part of the same union by listing the attributes that must be the same in all features of the union. For example, if you want to union all buildings that have the same height and construction_type together, you could specify:

"tiles": {
  "union": [
    {
      "group_by": [ "height", "construction_type" ]
    }
  ]
}

All attributes that are not part of the group_by and that do not have an aggregate rule specified will be removed at the end of unioning.

If you do not specify a group_by, then all feature attributes must be the same for features to be unioned together.

If you specify an empty group_by list, then all features will be unioned together regardless of their attributes.

Union aggregate​

You can specify which attributes MTS should keep that are not part of a union's group_by and how it should handle them by specifying aggregate rules for them.

Each key of the object is the name of an attribute. Each value is a string listed below that indicates how the named attribute should be aggregated from the source features. Attributes that are not specified in either group_by or aggregate will be removed.

These strings are the available aggregation methods:

  • sum: add numbers
  • product: multiply numbers
  • min: choose the lowest number
  • max: choose the highest number
  • mean: take the average of numbers
  • comma: concatenate with a comma
  • concat: concatenate the attribute data without a delimiter
  • arbitrary: take the attribute from one of the source features
  • arbitrary-non-null: take the attribute from one of the source features where the attribute is not null

Union maintain_direction​

Use maintain_direction: false to make more compact unions of LineStrings for which directionality doesn't matter. This reverses some of the LineStrings if that helps to connect them.

Defaults to maintain_direction: true

Union simplification​

For polygon unions, it is often useful to specify outward_only: true in the main simplification section, so the source features will slightly overlap and be merged into a single geometry. Then you can specify outward_only: false in the union's post-unioning simplification section, so additional simplification will be applied to the polygon after unioning has already taken their overlap into account.

Union example​

For example, you could specify the following to union only features where highway=motorway, and keep the average of their speed_limit attributes:

"tiles": {
  "union": [
    {
      "where": [ "==", [ "get", "highway" ], "motorway" ],
      "maintain_direction": true,
      "aggregate": { "speed_limit": "mean" }
    }
  ]
}

This example uses maintain_direction: true (the default) because motorway roads are generally mapped as pairs of roadways whose direction indicates their one-way direction.

For a more elaborate union example, see the Census Blocks recipe example.

Using union with zoom based properties
You can use union on zoom-element properties. If you are using union with a zoom-element property, the union will occur after the feature has been assigned the value based on the zoom level.

Post-union filter​

You can further limit the set of features in a tile after unioning by specifying a filter rule.

For instance, if your union rule was unioning street segments together, summing their length attribute, you could use filter here to remove the unioned streets whose combined length still did not reach a minimum visible threshold, as in this example:

"tiles": {
  "union": [
    {
      "aggregate": { "length": "sum" }
    }
  ],
  "filter": [ ">=", [ "get", "length" ], 200 ]
}

Post-union attributes​

You can add or change feature attributes after unioning by specifying an attributes.set rule.

For instance, if your union rule was unioning census blocks together, summing their population and area attributes, you could calculate the density of each unioned feature afterward, as in this example:

"tiles": {
  "union": [
    {
      "group_by": [ "tract" ]
      "aggregate": { "population": "sum", "area": sum }
    }
  ],
  "attributes": {
    "set": {
      "density": [ "/", [ "get", "population" ], [ "get", area ] ]
    }
  }
}

Order​

You can order the sequence of features in the final output tile by a specified attribute. The attribute values must be comparable (all strings or all numbers).

This example orders the features by the sequence attribute:

"tiles": { "order": "sequence" }

Renderers, including Mapbox GL, draw or place features in the order they appear in the tile. LineString and Polygon features that are drawn early in the sequence may be covered by overlapping features drawn later in the sequence. Conversely, labels that are placed early in the sequence will prevent labels of features later in the sequence from being placed nearby.

You can follow these general guidelines:

  • The most important LineStrings and Polygons should have the highest values for their order attribute, so they are not covered by overlapping features.
  • The most important labels should have the lowest values for their order attribute, so they are placed first.

Read more about how label visibility is affected by the order of features in the Optimize map label placement guide.

If no order attribute is specified, the features will appear in an unpredictable order.

Remove filled​

During tile creation it is possible for polygons to completely cover a tile and its surrounding buffer area. These are called "filled features". If all features within a tile are filled features, it may be useful in some tilesets not to create these tiles at all and to expect that clients will look to lower zoom levels instead.

The common situation that this applies to are large areas of water, where if the water polygon covers the entire tile, it is more efficient to overzoom the water from a lower zoom level rather than creating duplicate high-zoom tiles for an entire ocean.

To do this, you can use the remove_filled recipe option. The syntax utilizes a filter-expression to allow control over what features exactly should be removed.

"tiles": {
  "remove_filled": expression
}

No tile will be created if:

  • All features within the tile are considered filled features
  • All features are matched by the filter-expression provided in remove_filled

The following example removes all tiles that contain only filled features:

"tiles": {
  "remove_filled": true
}

The following example removes all tiles that contain only filled features after zoom level 5:

"tiles": {
  "remove_filled": [">", [ "zoom" ], 5]
}

Tiles ID​

You can change the final output ID of features by specifying an id expression. For instance, you might want all the features that have the same road name to have the same ID, so that if one of them is selected, they are all selected, even though the source features had to have different IDs because in earlier stages of processing, IDs are required to be distinct. So you could set a new ID at the end of processing, like this:

"tiles": {
  "id": [ "hash", [ "get", "road-name" ] ]
}

Within the id expression you can refer to the ID assigned earlier with [ "id" ], so you can make conditional expressions that leave the ID unchanged in some circumstances or use it in calculations, like this example, which replaces the ID if there is a special_id attribute, or otherwise multiplies the existing ID by 2:

"tiles": {
  "id": [ "case",
    [ "has", "special_id" ], [ "get", "special_id" ],
    [ "*", [ "id" ], 2 ]
  ]
}

If you do not want your features to have an ID in the final output tiles, set the ID to null:

"tiles": {
  "id": null
}

Allowed output​

In the features.attributes section of the recipe, you can specify a list of attributes in allowed_output that will appear in the final tile. The removal of other attributes happens at this point, at the end of tiles processing. As a result, in limit, union, or id processing you can continue to refer to attributes that will not appear in the final output features because they do not appear in allowed_output.

Layer size​

MTS limits the size (in bytes) of tile layers for the sake of network speed and rendering time. When the size of a layer's data in a single tile exceeds the layer_size, the features that came last in the specified order will be dropped from that tile to stay within the layer_size limit.

The normal limit is 1250, for 1250 kilobytes. You can further limit the layer size by specifying a lower layer_size number, or raise the limit to as high as 2500 by specifying a higher layer_size number.

If you are receiving warnings about dropped features due to exceeding layer_size, you may want to consider a few options:

  • Reduce the number of total attributes per feature. If you don't plan on using all your properties for styling or in your map, you can drop specific features using the attributes option.
  • Reduce the size of attributes in your features. Some property types, especially strings, can take up a lot of unused space in a tile. Consider dropping long form text from your data.
  • Filter your features at low zooms (z0 - z6) based on specific attributes. You can use the feature filter or the tile limit options to remove features at specific zoom levels, but keep the most important based on specific attributes.
  • Lastly, you can consider spreading your data across different layers or tilesets to stay within the layer size limit. Be aware this can have cost implications by creating more than one layer or tileset.

If you want to exclude specific features, it is generally better to use a limit specification instead. Setting layer_size is more useful for holding yourself to a performance budget than as a general feature limiting mechanism.

Identification​

You can configure the identification of features in both "Features" and "Tiles". Both follow the same patterns and have the same options. In general, features.id is used for defining or generating input IDs, while tiles.id is used for defining or generating output IDs in the final vector tiles.

{
  "features": {
    "id": [ <Expression> ]
  },
  "tiles": {
    "id": [ <Expression> ]
  }
}

All IDs encoded in the final vector tiles will be integers, as defined by the vector tile specification. If you provide a string value to tiles.id the value will be automatically hashed to an integer between 0 and 2^53 - 1.

Order of operations​

The following describes the order of operations and type conversions applied when using the features.id and tiles.id options. Remember the Mapbox Vector Tile specification requires all IDs to be encoded as positive integers between 0 and 2^53 - 1.

  • In general ID value in either features.id or tiles.id will be converted to an Integer or Float if possible and will otherwise return a string or Null value.
  • If features.id is not defined, the top-level id of the GeoJSON feature will be used.
    • If there is no top-level id from the GeoJSON feature, a random integer will be generated.
    • If the value is set to null, no feature ID is set.
  • If features.id is defined, the result of the expression will be converted to an Integer or Float if possible and will otherwise return a string.
    • If the expression returns a null value, a random integer will be generated. If you are trying to prevent feature IDs in your final tile, set tiles.id to null.
  • If tiles.id is not defined, the resulting value from features.id will be used.
  • If tiles.id is defined, the value of the resulting expression replaces whatever value was defined in features.id.
  • If the result of the tiles.id expression is a...
    • string, it is hashed to an integer.
    • string representation of an integer, it will be converted to the absolute value of that number and fit within 0 to 2^53 - 1.
    • empty string, it will be treated as null and not encoded.
    • negative number, the absolute value will be used.
    • floating point number, it will be rounded down and fit within 0 to 2^53 - 1.
    • boolean, it will be treated as null and not encoded.

If you don't want to encode any IDs in your final vector tile you can pass null to tiles.id as your value instead of an expression array.

Duplicate IDs​

While ID collision for unidentified features is unlikely, unique IDs aren't guaranteed since feature parsing occurs in a distributed environment. To guarantee unique identifiers, bring your own IDs. Duplicate feature IDs can cause unexpected behavior in tilesets and should be avoided.

Expressions reference​

Instead of applying a static value in a recipe operation, some recipe operations allow you to set values dynamically on a per feature or per zoom level basis. This dynamic value setting is possible with Mapbox expressions.

An expression defines a formula for computing the value of a property using the operators described below. The set of expression operators provided by MTS includes:

  • Mathematical operators for performing arithmetic and other operations on numeric values
  • Logical operators for manipulating boolean values and making conditional decisions
  • String operators for manipulating strings
  • Data operators that provide access to the properties of features in your tileset source

Expressions are represented as JSON arrays. The first element of an expression array is a string naming the expression operator, for example "*" or "case". Elements that follow (if any) are the arguments to the expression. Each argument is either a literal value (a string, number, boolean, or null), or another expression array.

[expression_name, argument_0, argument_1, ...]

Expressions allow you to dynamically set values in the recipe and optimize your output tileset. The LayerObject houses all the available recipe options and denotes which fields accept expressions by listing a Expression value.

Evaluating expressions​

A data expression is any expression that accesses data in your tileset source — that is, any expression that uses one of the data operators: get, has, id, geometry-type, or properties. The syntax of the expression and its arguments are checked when a recipe is validated, while the evaluation of the expression checked when a tileset is being processed. All expressions will be evaluated against a specific feature or zoom level, depending on logic of the recipe configurations.

Types​

Mapbox expressions run on a series of primitive types.

  • null: A null value.
  • number: An integer or floating point number.
  • string: Any series of UTF-8 characters.
  • boolean: True or False.
  • array: An array of values, optionally may specify the type of values in the array, for example, array<boolean>.
  • object: A map of key and value pairs.

It is also possible to see a value type in the documentation and error responses. This is a variable type that will not be a known primitive type until the expression is evaluated.

Errors​

Errors in your expression can occur in two different ways, during recipe validation or during the evaluation of that recipe within MTS. If an expression in a recipe has a syntax error, such as an invalid input type, the recipe will fail validation and will not be allowed within MTS. If an expression experiences an error during the evaluation of an expression, the recipe operation determines the proper error handling and the processing a job or feature may continue. For example, if a filter recipe operation experiences an evaluation error, the recipe expression will error and filter will consider the feature to be false. The default behavior of an expression evaluation error varies on the specific recipe operation.

Type expressions​

The expressions in this section are for testing for and converting between different data types like strings, numbers, and boolean values.

Often, such tests and conversions are unnecessary, but they are helpful if a feature's data type is ambiguous or inconsistent. For example, you could use to-number to make sure that values like "1.5" (instead of 1.5) are treated as numeric values. Another helpful use case is to convert values to their commonly represented types like using to-boolean to convert a 1 to true.

array

["array", value]: array
["array", type: "string" | "number" | "boolean", value]: array<type>
["array",
    type: "string" | "number" | "boolean",
    N: number (literal),
    value
]: array<type, N>
Example
 {
  "version": 1,
  "layers": {
    "countries": {
      "source": "mapbox://tileset-source/{username}/{id}",
      "minzoom": 0,
      "maxzoom": 10,
      "features": {
        "filter": [
          "all",
          [">=", ["length", ["array", ["get", "LANGUAGES"]]], 1]
        ],
        "attributes": {
          "set": {"num_official_languages": ["length", ["get", "LANGUAGES"]]}
        }
      }
    }
  }
}

boolean

["boolean", value]: boolean
["boolean", value, fallback: value, fallback: value, ...]: boolean
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 12,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/building-data",
      "features": {
        "filter": [
          "any",
          ["==", ["boolean", ["get", "commercial"], false], true]
        ]
      }
    }
  }
}

literal

["literal", [...] (JSON array literal)]: array<T, N>
["literal", {...} (JSON object literal)]: object
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/roads",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "attributes": {
          "set": {
            "road_type": [
              "get",
              ["get", "MTFCC"],
              [
                "literal",
                {
                  "S1100": "Primary Road",
                  "S1200": "Secondary Road",
                  "S1400": "Local Street",
                  "S1720": "Stairway",
                  "S1730": "Alley",
                  "S1829": "Bike Path or Trail"
                }
              ]
            ]
          }
        }
      }
    }
  }
}

number

["number", value]: number
["number", value, fallback: value, fallback: value, ...]: number
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 12,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/building-data",
      "features": {
        "filter": [
          "any",
          ["<", ["number", ["get", "construction-date"], 2020], 1900]
        ]
      }
    }
  }
}

object

["object", value]: object
["object", value, fallback: value, fallback: value, ...]: object
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/building-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "set": {
          "attributes": {
            "project-lead": [
              "get",
              "project-lead",
              ["object", ["get", "employees"], {}]
            ]
          }
        }
      }
    }
  }
}

string

["string", value]: string
["string", value, fallback: value, fallback: value, ...]: string
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 12,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/{id}",
      "features": {
        "filter": ["any", ["==", ["string", ["get", "state"]], "New York"]]
      }
    }
  }
}

to-boolean

["to-boolean", value]: boolean
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "minzoom": 0,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/natural-earth-roads",
      "features": {
        "attributes": {"set": {"tollRequired": ["to-boolean", ["get", "toll"]]}}
      }
    }
  }
}

to-number

["to-number", value, fallback: value, fallback: value, ...]: number
Example
 {
  "version": 1,
  "layers": {
    "buildings": {
      "source": "mapbox://tileset-source/{username}/building-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "attributes": {
          "set": {
            "building_age": [
              "-",
              2021,
              ["to-number", ["get", "construction-date"], 2021]
            ]
          }
        }
      }
    }
  }
}

to-string

["to-string", value]: string
Example
 {
  "version": 1,
  "layers": {
    "buildings": {
      "minzoom": 0,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/populated-places",
      "features": {
        "attributes": {
          "set": {
            "elevationDigitID": [
              "concat",
              ["length", ["to-string", ["get", "ELEVATION"]]],
              ["get", "NAME"]
            ]
          }
        }
      }
    }
  }
}

typeof

["typeof", value]: string
Example
 {
  "version": 1,
  "layers": {
    "placeName": {
      "source": "mapbox://tileset-source/{username}/populated-places",
      "minzoom": 0,
      "maxzoom": 10,
      "features": {
        "attributes": {
          "set": {
            "placeName": [
              "case",
              ["==", ["typeof", ["get", "NAME"]], "number"],
              "INVALIDNUM",
              ["==", ["typeof", ["get", "NAME"]], "boolean"],
              "INVALIDBOOL",
              ["get", "NAME"]
            ]
          }
        }
      }
    }
  }
}

Feature data​

The feature, geometry-type, properties, and id operators are used to retrieve information about the properties contained in the GeoJSON specification. Feature expressions are often used as inputs to other expressions, enabling you to build chains of logic around your data. Common use cases for feature expressions include:

  • Applying transformations to specific geometry types.
  • Filtering out features that have (or lack) specific properties.

geometry-type

["geometry-type"]: string
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/building-data",
      "minzoom": 0,
      "maxzoom": 10,
      "features": {
        "simplification": [
          "case",
          ["==", ["geometry-type"], "LineString"],
          0,
          10
        ]
      }
    }
  }
}

id

["id"]: value
Example
 {
  "version": 1,
  "layers": {
    "poi": {
      "source": "mapbox://{username}/places-of-interest",
      "minzoom": 0,
      "maxzoom": 10,
      "features": {
        "filter": [
          "case",
          ["<=", ["zoom"], 4],
          ["==", ["%", ["id"], 2], 0],
          true
        ]
      }
    }
  }
}

properties

["properties"]: object
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://{username}/roads",
      "minzoom": 0,
      "maxzoom": 10,
      "features": {
        "attributes": {"set": {"old_attributes": ["to-string", ["properties"]]}}
      },
      "tiles": {
        "attributes": {
          "set": {"streetname": ["concat", ["get", "streetname"], " street"]}
        }
      }
    }
  }
}

Lookup​

The at, get, has, in, index-of, length, and slice operators are for retrieving information about feature properties contained in the GeoJSON specification. They access or test for properties, arrays, or strings, and the results can be used as inputs for other expressions. For example, the Census blocks - unioning census geographies example uses get to retrieve existing properties and concatenates them into a single attribute based on zoom level. Another example is the Roads - unioning features based on shared attributes example, which uses get to retrieve properties and filter them by comparing against other values.

at

["at", number, array]: ItemType
Example
 {
  "version": 1,
  "layers": {
    "bakeries": {
      "source": "mapbox://tileset-source/{username}/dc-bakeries",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "attributes": {
          "set": {
            "cheapest-menu-item": ["at", 0, ["get", "sorted-item-prices"]]
          }
        }
      }
    }
  }
}

get

["get", string]: value
["get", string, object]: value
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/roads",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "attributes": {
          "set": {
            "road_type": [
              "get",
              ["get", "MTFCC"],
              [
                "literal",
                {
                  "S1100": "Primary Road",
                  "S1200": "Secondary Road",
                  "S1400": "Local Street",
                  "S1720": "Stairway",
                  "S1730": "Alley",
                  "S1829": "Bike Path or Trail"
                }
              ]
            ]
          }
        }
      }
    }
  }
}

has

["has", string]: boolean
["has", string, object]: boolean
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/road-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {"filter": ["has", "quality"]}
    }
  }
}

in

["in",
    keyword: InputType (boolean, string, or number),
    input: InputType (array or string)
]: boolean
Example
 {
  "version": 1,
  "layers": {
    "countries": {
      "source": "mapbox://tileset-source/{username}/{id}",
      "minzoom": 0,
      "maxzoom": 10,
      "features": {
        "attributes": {
          "set": {"spanish_speaking": ["in", "Spanish", ["get", "LANGUAGES"]]}
        }
      }
    }
  }
}

index-of

["index-of",
    keyword: InputType (boolean, string, or number),
    input: InputType (array or string)
]: number
["index-of",
    keyword: InputType (boolean, string, or number),
    input: InputType (array or string),
    index: number
]: number
Example
 {
  "version": 1,
  "layers": {
    "streets": {
      "minzoom": 0,
      "maxzoom": 13,
      "source": "mapbox://sample-source/tiger-roads",
      "features": {
        "attributes": {
          "set": {
            "FULLNAME": [
              "let",
              "name",
              ["coalesce", ["get", "FULLNAME"], ""],
              [
                "let",
                "index_of_st",
                ["index-of", " St", ["var", "name"]],
                "length_minus_3",
                ["-", ["length", ["var", "name"]], 3],
                [
                  "case",
                  [
                    "all",
                    [">=", ["var", "index_of_st"], 0],
                    ["==", ["var", "index_of_st"], ["var", "length_minus_3"]]
                  ],
                  [
                    "concat",
                    ["slice", ["var", "name"], 0, ["var", "index_of_st"]],
                    " Street"
                  ],
                  ["get", "FULLNAME"]
                ]
              ]
            ]
          }
        }
      }
    }
  }
}

length

["length", string | array | value]: number
Example
 {
  "version": 1,
  "layers": {
    "countries": {
      "source": "mapbox://tileset-source/{username}/{id}",
      "minzoom": 0,
      "maxzoom": 10,
      "features": {
        "attributes": {
          "set": {"num_official_languages": ["length", ["get", "LANGUAGES"]]}
        }
      }
    }
  }
}

slice

["slice",
    input: InputType (array or string),
    startIndex: number
]: OutputType (ItemType or string)
["slice",
    input: InputType (array or string),
    startIndex: number,
    endIndex: number
]: OutputType (ItemType or string)
Example
 {
  "version": 1,
  "layers": {
    "bakeries": {
      "source": "mapbox://tileset-source/{username}/dc-bakeries",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "attributes": {
          "set": {"abbreviated-title": ["slice", ["get", "title"], 0, 3]}
        }
      }
    }
  }
}

Decision​

The expressions in this section can be used to add conditional logic to your recipe. For example, the 'case' operator provides if/then/else logic, and the 'match' operator allows you to map specific values of an input expression to different output expressions.

Decision logic could be used to filter a feature based on its property value compared against the current zoom. Decision logic could also be used to simplify a feature's geometry conditionally, based on a feature property value.

The Roads - ranking and simplifying linestrings example includes a few examples of decision logic, including the <= and match operators.

!

["!", boolean]: boolean
Example
 {
  "version": 1,
  "layers": {
    "airport-buildings": {
      "source": "mapbox://tileset-source/{username}/airport-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "filter": [
          "!",
          [
            "any",
            ["==", ["get", "type"], "runway"],
            ["==", ["get", "type"], "taxiway"],
            ["==", ["get", "type"], "apron"]
          ]
        ]
      }
    }
  }
}

!=

["!=", value, value]: boolean
Example
 {
  "version": 1,
  "layers": {
    "trails": {
      "source": "mapbox://tileset-source/{username}/trails-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {"filter": ["!=", ["get", "right_of_way"], "private"]}
    }
  }
}

<

["<", value, value]: boolean
Example
 {
  "version": 1,
  "layers": {
    "airport": {
      "source": "mapbox://tileset-source/{username}/airport-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {"filter": ["<", ["get", "runways"], 3]}
    }
  }
}

<=

["<=", value, value]: boolean
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/road-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {"filter": ["<=", ["get", "quality"], 10]}
    }
  }
}

==

["==", value, value]: boolean
Example
 {
  "version": 1,
  "layers": {
    "trails": {
      "source": "mapbox://tileset-source/{username}/trails-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {"filter": ["==", ["get", "right_of_way"], "public"]}
    }
  }
}

>

[">", value, value]: boolean
Example
 {
  "version": 1,
  "layers": {
    "trip": {
      "source": "mapbox://tileset-source/{username}/trip-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {"filter": [">", ["get", "length_m"], 999]}
    }
  }
}

>=

[">=", value, value]: boolean
Example
 {
  "version": 1,
  "layers": {
    "trip": {
      "source": "mapbox://tileset-source/{username}/trip-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {"filter": [">=", ["get", "length_m"], 1000]}
    }
  }
}

all

["all", boolean, boolean]: boolean
["all", boolean, boolean, ...]: boolean
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/road-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "filter": [
          "all",
          [">=", ["get", "length_km"], 100],
          ["==", ["get", "type"], "Primary Highway"]
        ]
      }
    }
  }
}

any

["any", boolean, boolean]: boolean
["any", boolean, boolean, ...]: boolean
Example
 {
  "version": 1,
  "layers": {
    "surfaces": {
      "source": "mapbox://tileset-source/{username}/airport-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "filter": [
          "any",
          ["==", ["get", "type"], "runway"],
          ["==", ["get", "type"], "taxiway"],
          ["==", ["get", "type"], "apron"]
        ]
      }
    }
  }
}

case

["case",
    condition: boolean, output: OutputType,
    condition: boolean, output: OutputType,
    ...,
    fallback: OutputType
]: OutputType
Example
 {
  "version": 1,
  "layers": {
    "countries": {
      "source": "mapbox://tileset-source/{username}/{id}",
      "minzoom": 0,
      "maxzoom": 10,
      "features": {
        "simplification": 10,
        "attributes": {
          "set": {
            "num_official_languages": [
              "case",
              ["==", ["get", "LANGUAGES"], null],
              0,
              ["==", ["typeof", ["get", "LANGUAGES"]], "string"],
              1,
              ["length", ["get", "LANGUAGES"]]
            ]
          }
        }
      }
    }
  }
}

coalesce

["coalesce", OutputType, OutputType, ...]: OutputType
Example
 {
  "version": 1,
  "layers": {
    "streets": {
      "minzoom": 0,
      "maxzoom": 13,
      "source": "mapbox://sample-source/tiger-roads",
      "features": {
        "attributes": {
          "allowed_output": ["name"],
          "set": {
            "name": [
              "coalesce",
              ["get", "FULLNAME"],
              [
                "concat",
                "ZIP code ",
                ["coalesce", ["get", "ZIPL"], ["get", "ZIPR"], "unknown"]
              ]
            ]
          }
        }
      }
    }
  }
}

match

["match",
    input: InputType (number or string),
    label: InputType | [InputType, InputType, ...], output: OutputType,
    label: InputType | [InputType, InputType, ...], output: OutputType,
    ...,
    fallback: OutputType
]: OutputType
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/road-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "attributes": {
          "set": {
            "quality": [
              "match",
              ["get", "type"],
              "Ferry Route",
              0,
              ["Major Highway", "Primary Highway"],
              1,
              "Secondary Highway",
              2,
              3
            ]
          }
        }
      }
    }
  }
}

Scales​

The expressions in this section provide transformation operations between a numerical input and an output. Scale expressions are most commonly used to generate varying "simplification" values by "zoom" level, but they can also be used to generate new attributes based on existing properties of the source data.

interpolate

["interpolate",
    interpolation: ["linear"] | ["exponential", base] | ["cubic-bezier", x1, y1, x2, y2],
    input: number,
    stop_input_1: number, stop_output_1: OutputType,
    ...,
    stop_input_n: number, stop_output_n: OutputType
]: OutputType (number, array<number>)
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/building-data",
      "minzoom": 0,
      "maxzoom": 12,
      "features": {
        "simplification": ["interpolate", ["linear"], ["zoom"], 0, 10, 10, 0]
      }
    }
  }
}

step

["step",
    input: number,
    stop_output_0: OutputType,
    stop_input_1: number, stop_output_1: OutputType,
    stop_input_n: number, stop_output_n: OutputType, ...
]: OutputType
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/building-data",
      "minzoom": 0,
      "maxzoom": 12,
      "features": {"simplification": ["step", ["zoom"], 10, 3, 2, 7, 1, 10, 0]}
    }
  }
}

Variable binding​

The let and var expressions allow you to calculate and give a name to one or more values that can then be used repeatedly within a single expression.

In most cases, recipes will instead use the set recipe field to create a new feature attribute, but because the order of set operations is undefined, a set expression cannot refer to the output of a different set expression. So if an expression needs to refer repeatedly to a previously-calculated value, it must instead use let to calculate that value and var to refer to the result of the calculation.

See let below for a more detailed example of how let and var are used together.

let

["let",
    string (alphanumeric literal), any, string (alphanumeric literal), any, ...,
    OutputType
]: OutputType
Example
 {
  "version": 1,
  "layers": {
    "cities": {
      "minzoom": 0,
      "maxzoom": 7,
      "source": "mapbox://tileset-source/{username}/populated-places",
      "features": {
        "attributes": {
          "allowed_output": ["NAME", "POP_OTHER"],
          "set": {
            "POP_OTHER": [
              "let",
              "divisor",
              [
                "case",
                ["<", ["zoom"], 1],
                100000,
                ["<", ["zoom"], 2],
                50000,
                ["<", ["zoom"], 3],
                25000,
                ["<", ["zoom"], 4],
                10000,
                ["<", ["zoom"], 5],
                5000,
                ["<", ["zoom"], 6],
                2000,
                1000
              ],
              [
                "case",
                ["has", "POP_OTHER"],
                [
                  "*",
                  ["var", "divisor"],
                  ["round", ["/", ["get", "POP_OTHER"], ["var", "divisor"]]]
                ],
                ["get", "POP_OTHER"]
              ]
            ]
          }
        }
      }
    }
  }
}

var

["var", previously bound variable name]: the type of the bound expression

String​

The expressions in this section are for manipulating string values. Supported expressions are concat, downcase, and upcase. The Census blocks - unioning census geographies example demonstrates the concat string expression used in combination with the case expression to conditionally concatenate a string to an attribute.

The slice expression (in the Lookup section) can also be used to manipulate strings, although it can also be used for array slicing.

concat

["concat", value, value, ...]: string
Example
 {
  "version": 1,
  "layers": {
    "buildings": {
      "source": "mapbox://tileset-source/{username}/building-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "attributes": {
          "set": {
            "building_description": [
              "concat",
              ["get", "construction-date"],
              ":",
              [
                "get",
                ["get", "building_group"],
                [
                  "literal",
                  {"R": "residential property", "C": "commercial property"}
                ]
              ]
            ]
          }
        }
      }
    }
  }
}

downcase

["downcase", string]: string
Example
 {
  "version": 1,
  "layers": {
    "roads": {
      "source": "mapbox://tileset-source/{username}/roads",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "attributes": {"set": {"lowercase-name": ["downcase", ["get", "name"]]}}
      }
    }
  }
}

upcase

["upcase", string]: string
Example
 {
  "version": 1,
  "layers": {
    "streets": {
      "minzoom": 0,
      "maxzoom": 12,
      "source": "mapbox://sample-source/tiger-roads",
      "features": {
        "attributes": {
          "set": {
            "FULLNAME": [
              "case",
              ["==", ["typeof", ["get", "FULLNAME"]], "string"],
              ["upcase", ["get", "FULLNAME"]],
              ["get", "FULLNAME"]
            ]
          }
        }
      }
    }
  }
}

Math​

The -, *, /, %, ^, +, abs, acos, asin, atan, ceil, cos, e, floor, hash, ln, ln2, log10, log2, max, min, pi, random, round, sin, sqrt, and tan operators are for applying mathematical operations.

-

["-", number, number]: number
["-", number]: number
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 0,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/building-data",
      "features": {
        "filter": [
          "any",
          [
            ">",
            ["-", ["get", "current-value"], ["get", "value-last-year"]],
            10000
          ]
        ]
      }
    }
  }
}

*

["*", number, number, ...]: number
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 0,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/building-data",
      "features": {
        "filter": [
          "any",
          [">", ["*", ["get", "sqft"], ["get", "cost-per-sqft"]], 100000]
        ]
      }
    }
  }
}

/

["/", number, number]: number
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 0,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/building-data",
      "features": {"filter": ["any", [">", ["/", ["get", "capacity"], 12], 10]]}
    }
  }
}

%

["%", number, number]: number
Example
 {
  "version": 1,
  "layers": {
    "cities": {
      "minzoom": 0,
      "maxzoom": 5,
      "source": "mapbox://sample-source/populated-places",
      "features": {
        "filter": ["==", 0, ["%", ["random"], ["^", 2, ["-", 5, ["zoom"]]]]]
      }
    }
  }
}

^

["^", number, number]: number
Example
 {
  "version": 1,
  "layers": {
    "cities": {
      "minzoom": 0,
      "maxzoom": 5,
      "source": "mapbox://sample-source/populated-places",
      "features": {
        "filter": ["==", 0, ["%", ["random"], ["^", 2, ["-", 5, ["zoom"]]]]]
      }
    }
  }
}

+

["+", number, number, ...]: number
Example
 {
  "version": 1,
  "layers": {
    "buildings": {
      "minzoom": 0,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/building-data",
      "features": {
        "filter": [
          "any",
          [">", ["+", ["get", "altitude"], ["get", "building-height"]], 10000]
        ]
      }
    }
  }
}

abs

["abs", number]: number
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 0,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/building-data",
      "features": {
        "filter": ["any", ["<", ["abs", ["get", "latitude"]], 23.43652]]
      }
    }
  }
}

acos

["acos", number]: number

asin

["asin", number]: number

atan

["atan", number]: number

ceil

["ceil", number]: number

cos

["cos", number]: number

e

["e"]: number

floor

["floor", number]: number
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "source": "mapbox://tileset-source/{username}/populated-places",
      "minzoom": 0,
      "maxzoom": 10,
      "features": {"filter": ["all", [">=", ["floor", ["get", "min_zoom"]], 7]]}
    }
  }
}

hash

["hash", string]: number
Example
 {
  "version": 1,
  "layers": {
    "traffic": {
      "source": "mapbox://{username}/traffic",
      "minzoom": 0,
      "maxzoom": 10,
      "tiles": {
        "id": ["hash", ["concat", ["get", "roadname"], ["get", "hour"]]]
      }
    }
  }
}

ln

["ln", number]: number

ln2

["ln2"]: number

log10

["log10", number]: number

log2

["log2", number]: number

max

["max", number, number, ...]: number
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 0,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/building-data",
      "features": {
        "filter": [
          "any",
          ["<", ["max", ["get", "year-build"], ["get", "year-sold"]], 2010]
        ]
      }
    }
  }
}

min

["min", number, number, ...]: number
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 0,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/counties",
      "features": {
        "filter": [
          "any",
          [
            "<",
            [
              "min",
              ["at", 0, ["get", "population-history"]],
              ["at", 1, ["get", "population-history"]],
              ["at", 2, ["get", "population-history"]],
              ["at", 3, ["get", "population-history"]],
              ["at", 4, ["get", "population-history"]]
            ],
            1000
          ]
        ]
      }
    }
  }
}

pi

["pi"]: number
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 0,
      "maxzoom": 15,
      "source": "mapbox://tileset-source/{username}/building-data",
      "features": {
        "filter": [
          "any",
          [">", ["*", ["pi"], ["^", ["get", "signal-range"], 2]], 500]
        ]
      }
    }
  }
}

random

["random"]: number
Example
 {
  "version": 1,
  "layers": {
    "cities": {
      "minzoom": 0,
      "maxzoom": 5,
      "source": "mapbox://sample-source/populated-places",
      "features": {
        "filter": ["==", 0, ["%", ["random"], ["^", 2, ["-", 5, ["zoom"]]]]]
      }
    }
  }
}

round

["round", number]: number
Example
 {
  "version": 1,
  "dessert": {
    "shops": {
      "source": "mapbox://tileset-source/{username}/dessert-data",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "attributes": {
          "set": {
            "icecream_pints_per_capita": [
              "round",
              ["/", ["get", "icecream_pints"], ["get", "population"]]
            ]
          }
        }
      }
    }
  }
}

sin

["sin", number]: number

sqrt

["sqrt", number]: number

tan

["tan", number]: number

Zoom​

The expression in this section is for performing zoom-specific operations with your data. This is often used to simplify or filter data based on the tile's zoom level. For example, you can write an expression include less detailed information at lower zooms and include full detail at higher zooms. This provides a faster and more usable map. The Roads - ranking and simplifying linestrings example demonstrates this.

zoom

["zoom"]: number
Example
 {
  "version": 1,
  "layers": {
    "places": {
      "minzoom": 0,
      "maxzoom": 14,
      "source": "mapbox://tileset-source/{username}/{id}",
      "features": {
        "filter": [
          "any",
          [">=", ["zoom"], 12],
          ["!=", ["get", "type"], "residential"]
        ]
      }
    }
  }
}

More resources​

Additional Developer Resources
Was this page helpful?