Map Style Specification
Purpose
Map style is written in JSON format. It specifies how to:
- Style the symbols, lines, polygons, background, hills' shades, heatmap points, raster tiles, circles, and extruded polygons.
- Which of them should be drawn.
- The order in which to draw them.
Root Properties
Root level properties define Default values, tile sources, and the map's layers.
Properties
Name | Required | Default value | Description |
---|---|---|---|
string | no | none | Name of the style. |
number | yes | none | Version of the style specification. Value: |
number | no | none | Default zoom level. Only applies if the map has not been positioned by any other means (e.g., user interaction). |
number (degrees) | no | 0 | Default bearing. For instance, 90o sets east as the up direction. Only applies if the map has not been positioned by any other means (e.g., user interaction). |
array of numbers | no | none | Default map center. The array shall consist of two values: longitude and latitude. They can be either integer or floating point numbers. Only applies if the map has not been positioned by any other means (e.g., user interaction). |
number (degrees) | no | 0 | Default pitch. The view is straight down at the map when the value is 0. Greater values set the view towards the horizon. Only applies if the map has not be positioned by any other means (e.g., user interaction). |
object | yes | none | Data source. Properties of the |
object | no | none | Light source. Properties of the |
object | no / | none | The URL must contain the scheme, authority, path, and the {fontstack} and {range} tokens. The property will be used to load glyphs in PBF format. |
object | no | none | Defines the default transition to use across the style. Properties of
the |
array of objects | yes | none | The array of layers. Layers will be drawn in the same order as they appear in this property. |
string | no / | none | The URL must contain a scheme, authority, and path. The property is used to load the sprite image. The file extension for the sprite image (.png) and metadata (.json) will be added automatically. |
Source Properties
A source provides data that is displayed on the map.
- The
source
object needs to have a property namedtype
. - There are several types of source:
vector
,raster
,raster-dem
(Web SDK only),geojson
,image
,video
(Web SDK Only). - Each of them have different properties which are described below.
Vector Properties
Name | Required | Default value | Description |
---|---|---|---|
string | no | none | URL to a resource. |
array of strings | no | none | An array of the URLs to a resource. This property can contain one or more URLs. |
string | no | none | Attribution that is shown when the map is displayed. |
string | no | xyz | Scheme of the data. |
array of numbers | no |
| An array of the longitude and latitude pairs containing southwest and northeast corners. No tiles will be requested outside of those bounds. |
number | no | 0 | Minimum zoom level the tiles are available for. |
number | no | 22 | Maximum zoom level the tiles are available for. |
Raster Properties
Name | Required | Default value | Description |
---|---|---|---|
string | no | none | URL to a resource. |
array of strings | no | none | An array of the URLs to a resource. This property can contain one or more URLs. |
string | no | none | Attribution that is shown when the map is displayed. |
string | no | xyz | Scheme of the data. Values:
|
array of numbers | no |
| An array of the longitude and latitude pairs containing southwest and northeast corners. No tiles will be requested outside of those bounds. |
number | no | 0 | Minimum zoom level the tiles are available for. |
number | no | 22 | Maximum zoom level the tiles are available for. |
number (pixels) | no | 512 | Minimum size to display tiles. |
Raster-Dem Properties
Name | Required | Default value | Description |
---|---|---|---|
string | no | none | URL to a resource. |
array of strings | no | none | An array of the URLs to a resource. This property can contain one or more URLs. |
string | no | none | Attribution that is shown when the map is displayed. |
string | no | mapbox | Encoding used by source. Values:
|
array of numbers | no |
| An array of the longitude and latitude pairs containing southwest and northeast corners. No tiles will be requested outside of those bounds. |
number | no | 0 | Minimum zoom level the tiles are available for. |
number | no | 22 | Maximum zoom level the tiles are available for. |
number (pixels) | no | 512 | Minimum size to display tiles. |
GeoJSON Properties
Name | Required | Default value | Description |
---|---|---|---|
string | yes | none | URL to a GeoJSON resource or inline GeoJSON. |
number | no | 128 | Size of the tile buffer.
|
string | no | none | Attribution that is shown when the map is displayed. |
number | no | 0.375 | Tolerance of Douglas-Peucker simplification. Lower values result in more detailed geometries and slower performance. |
boolean | no | false | If
|
number | no | 50 | Radius to group points into clusters. Number must be equal to or greater
than |
number | no |
| Maximum zoom level to group points into clusters. |
object | no | none | Allows the definition of custom properties for generated clusters, combining values from clustered points. Syntax:
|
number | no | 18 | Maximum zoom level to create the tiles. |
boolean | no | false |
|
boolean | no | false |
|
Image Properties
Name | Required | Default value | Description |
---|---|---|---|
string | yes | none | URL to an image resource. |
array of arrays of numbers | yes | none | Corners of an image specified in
|
Video Properties
Name | Required | Default value | Description |
---|---|---|---|
array of strings | yes | none | URLs to video resources. |
array of arrays of numbers | yes | none | Corners of a video specified in
|
SDK Support
Source Type | Web SDK | Mobile SDK |
---|---|---|
| ✔ | ✔ |
| ✔ | ✔ |
| ✔ | ✘ |
| ✔ | ✔ |
| ✔ | ✔ |
| ✔ | ✘ |
Sprite property
The sprite property provides the URL to load images used in the rendering process. Properties which use sprite are:
icon-image
fill-extrusion-pattern
line-pattern
fill-pattern
background-pattern
A sprite source must contain index and image files.
Index file
The Index file must be written in JSON format and contain a JSON object. The keys of the root object are identifiers to be used in style properties.
1{2 "145": {3 "width": 24,4 "height": 24,5 "x": 697,6 "y": 600,7 "pixelRatio": 18 }9}
Name | Description |
---|---|
number | Width of the image. |
number | Height of the image. |
number | Horizontal location of the image. |
number | Vertical location of the image. |
array of numbers | Pixel ratio of the image. |
Sprite file
The Sprite file contains PNG images.
Glyphs Property
The URL template is used to load glyphs in PBF format.
Example
http://localhost:6001/glyphs/{fontstack}/{range}.pbf
Token Name | Description |
---|---|
| The token is replaced with requested glyphs from the text-font layout property. |
| The token is replaced with Unicode code points. Ranges are calculated at runtime. |
Transition Properties
Defines timing for the interpolation between the style's property values. It can be set globally for the style, but also configured per layer.
Properties
Name | Required | Default value | Description |
---|---|---|---|
*number (milliseconds)* | no | 300 | Time needed to complete transitions. Value needs to be equal to or greater than 0. |
*number (milliseconds)* | no | 0 | Time before a transition starts. |
SDK Support
Property Name | Web SDK | Mobile SDK |
---|---|---|
| ✔ | ✔ |
| ✔ | ✔ |
Light Properties
Defines the light source for the style.
Properties
Name | Required | Default value | Description |
---|---|---|---|
string | no | viewport | Anchor of the source light. Values:
|
number | no | 0.5 | Intensity of the lighting. Value must be between |
color | no | #ffffff | Color of the light source for extruded geometries. |
array of numbers | no |
| Position of the light source which is relative to extruded geometries.
|
SDK Support
Property Name | Web SDK | Mobile SDK |
---|---|---|
| ✔ | ✔ |
| ✔ | ✔ |
| ✔ | ✔ |
| ✔ | ✔ |
Layer Properties
Layer defines how specific features retrieved from a source are rendered on the map. The renderer decides how to draw a feature based on its properties and the style of the layer that describes it. Only the background type layer does not need a source property.
Properties
Name | Required | Default value | Description |
---|---|---|---|
string | yes | none | ID of the layer. Must be unique. |
string | yes | none | Type of the layer. Values:
|
object | no | none | Attributes that do not affect rendering. |
string | no / yes (if | none | Name of a source to be used. |
string | no / yes (if | none | A layer to use from vector source. |
number | no | none | The minimum zoom level to draw the layer. Number must be between
|
number | no | none | The maximum zoom level to draw the layer. Number must be between
|
*array (filter)* | no | none | If the feature does not match the condition, then it is not drawn on the map. |
object | no | none | Layout properties. Properties of the |
object | no | none | Paint properties. Properties of the |
Layout Properties
Background Properties
Name | Required | Default value | Description |
---|---|---|---|
string | no | visible | Visibility of the layer. Values:
|
SDK Support
Property Name | Web SDK supported / expression | Mobile SDK supported / expression |
---|---|---|
string | ✔ / ✖ | ✔ / ✖ |
Fill Properties
Name | Required | Default value | Description |
---|---|---|---|
string | no | visible | Visibility of the layer. Values:
|
SDK Support
Property Name | Web SDK supported / expression | Mobile SDK supported / expression |
---|---|---|
string | ✔ / ✖ | ✔ / ✖ |
Line Properties
Name | Required | Default value | Description |
---|---|---|---|
string | no | visible | Visibility of the layer. Values:
|
string | no | butt | Type of the line's endings. Values:
|
string | no | miter | Type of the line's join. Values:
|
number | no | 2 | Used to convert miter joins to bevel ones for sharp angles. |
number | no | 1.05 | Used to convert round joins to miter ones for shallow angles. |
SDK Support
Property Name | Web SDK supported / expression | Mobile SDK supported / expression |
---|---|---|
string | ✔ / ✖ | ✔ / ✖ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✔ | ✔ / ✔ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✖ | ✔ / ✖ |
Symbol Properties
Name | Required | Default value | Description |
---|---|---|---|
string | no | visible | Visibility of the layer. Values:
|
number | no | none | Used to sort features. Features are drawn in ascending order. |
string | no | auto | Type of sorting features. Affects the order of overlapping features within the same layer are being rendered. Values:
|
string | no | point | Placement of the label. Values:
|
*number (pixels)* | no | 250 | Distance between symbol anchors. |
boolean | no | false | The symbol will not be drawn when it crosses tile edge if this property
is set to |
boolean | no | false | The icon will be drawn even if a collision is detected with other
already drawn icons. |
boolean | no | false | Other symbols will be visible even if a collision is detected with the
icon. |
boolean | no | false | Only text will be drawn if the icon collides with other symbols. |
string | no | auto | Sets icon rotation alignment. Values:
|
number | no | 1 | Scales the icon image size by multiplying its original size by this
property. |
string | no | none | Scales the icon to fit the text. Values:
|
array of numbers | no |
| Padding around the area defined by
|
string | no | none | Name of an image in the sprite config file. |
*number (degrees)* | no | 0 | Icon is rotated clockwise by this property. |
*number (pixels)* | no | 2 | Extra area surrounding an icon to detect collisions with other symbols.
|
boolean | no | false | Prevents an icon from being rendered upside-down.
|
*array of numbers (pixels)* | no |
| An icon's distance from its anchor. Each element of the array is
multiplied by the value of
|
string | no | center | Sets which part of the icon is closest to the anchor.
Values:
|
string | no | auto | Orientation of the icon when a map is pitched. Values:
|
string | no | auto | Orientation of the text when a map is pitched. Values:
|
string | no | auto | Sets text rotation alignment. Values:
|
string | no | none | Text to be displayed as a symbol label. |
array of strings | no |
| Font to be used to display text. |
*number (pixels)* | no | 16 | Text size. |
*number (ems)* | no | 10 | Maximum width of the text. |
*number (ems)* | no | 1.2 | Text leading value for multi-line text. |
*number (ems)* | no | 0 | Sets spacing between letters. |
string | no | center | Justifies the text. Values:
|
*number (ems)* | no | 0 | Radial offset of the text in the direction of the symbol's anchor.
|
array of strings | no | none | Sets the position of the text. The render will try to place the label
using the values provided in the array.
|
string | no | center | Sets the position of the text. The render will try to place the label
using the values provided in the array. Values:
|
*number (degrees)* | no | 45 | Maximum angle change between adjacent characters.
|
*number (degrees)* | no | 0 | Rotates the text clockwise. |
*number (pixels)* | no | 2 | Extra area surrounding text for detecting collisions with other symbols.
|
boolean | no | true | Prevents text from being rendered upside-down. |
string | no | none | Capitalizes text. Values:
|
*array of numbers (ems)* | no |
| Text distance from its anchor.
|
boolean | no | false | The text will be drawn even if a collision is detected with other
already drawn icons. |
boolean | no | false | Other symbols will be visible even if a collision is detected with the
text. |
boolean | no | false | Only an icon will be drawn if the text collides with other symbols.
|
SDK Support
Property Name | Web SDK supported / expression | Mobile SDK supported / expression |
---|---|---|
string | ✔ / ✖ | ✔ / ✖ |
| ✔ / ✔ | ✔ / ✔ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✔ | ✔ / ✔ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✖ | ✔ / ✖ |
| ✔ / ✔ | ✔ / ✔ |
| ✔ / ✔ | ✔ / ✔ |
| ✔ / ✖ |