Style format specification
2GIS style is a document that defines the appearance of the map: what data to draw, how to draw it, and in what order.
Specification versions
1.0.0
First public release of the specification.
Style object
Styles are objects in JSON format. The root of the object contains general information about the style and an array of map layers with their display settings.
{
"version": 1,
"name": "2GIS Night",
"background": {
"color": "#ffffff"
},
"labelingGroups": {...},
"layers": [...]
}
version
number
(required)
Major version number of the format. Changes only on breaking changes. For now, it should always be 1
.
"version": 1
name
string
(optional)
Style name (a human-readable string).
"name": "Snowy"
metadata
object
(optional)
Custom data that can be stored alongside the style object. Does not affect the appearance of the map.
background
object
(required)
Background of the map.
Must contain the following fields:
- color (
color
) - color of the background
labelingGroups
object
(optional)
Labeling groups and their interaction.
Can contain the following fields:
- groups (
array of string
, default value is["default"]
) - names of the labeling groups. - overlay (
array of array of string
) - groups that will overlap each other. For example,[["group1", "group2"]]
will causegroup2
to overlapgroup1
in case of intersection; intersection of all other groups will cause a z-index fight. If the listed group is not in thegroups
array, it will be ignored.
layers
array
of Layer
(required)
Layers that set the appearance of Geo Objects on the map.
Each layer type has its own set of parameters. Currently, the following layer types are supported:
polygon
- a polygon with a fill and an outline;line
- a line with a width;dashedLine
- a dashed line with a width and dash properties;point
- an icon, a label, or a labeled icon;raster
- a bitmap image;heatmap
- a heatmap.
Layers are drawn on top of each other in the same order they are specified in the array (objects of the last layer will be at the top). Objects on the same layer will be drawn based on their order in the data source.
Example:
"layers": [
{
"id": "water",
"type": "polygon",
"style": {
"color": "#0000ff"
}
}
]
Caution!
In MapGL JS API, it is advised to use only the layers and properties presented in this specification. There are additional types of layers available in style editor, but their specification is still at the draft stage and may change in the future.
Layer
Each layer regardless of its type contains a number of basic fields:
id
string
(required)
Layer identifier. Must be unique, otherwise the rendering may not work correctly.
type
enum (point, line, dashedLine, polygon)
(required)
Layer type.
filter
Expression<boolean>
(required)
(Does not support step
and interpolate
expressions.)
Filter that selects objects for the layer.
For example, the following filter will select all objects whose layer
attribute is either private
or beach
:
{
"filter": ["match", ["get", "layer"], ["private", "beach"], true, false]
}
This filter will select all objects for which 3 conditions are met:
"filter": [
"all",
["match", ["get", "class"], ["road"], true, false],
["match", ["get", "type"], ["main"], true, false],
["match", ["global", "navigatorOn"], [true], true, false]
]
In this case, the filter will select all objects from the data source with the sourceAttr
attribute value equal to data_source_1
or data_source_2
:
{
"filter": ["match", ["sourceAttr", "name"], ["data_source_1", "data_source_2"], true, false]
}
In this case, the filter will select all objects with the value equal to featureState_attr_value
from user-setted object attribute:
{
"filter": ["match", ["featureState", "name"], ["featureState_attr_value"], true, false]
}
minzoom
number
(optional)
(0 to 20)
Minimum map zoom level for the layer. Layer objects will be displayed only if the zoom level is greater or equal to this value.
maxzoom
number
(optional)
(0 to 20)
Maximum map zoom level for the layer. Layer objects will be displayed only if the zoom level is less than this value.
style
object
(optional)
A set of style properties for the layer. Depends on the layer type.
style for «polygon»
color
color
or Expression<color>
(optional)
(Default value is "#000000"
. Does not support the following extractor expressions: get
, sourceAttr
, featureState
, global
.)
Fill color.
strokeColor
color
or Expression<color>
(optional)
(Default value is "#000000"
. Does not support the following extractor expressions: get
, sourceAttr
, featureState
, global
.)
Stroke color.
strokeWidth
number
or Expression<number>
(optional)
(Default value is 1
.)
Stroke width in pixels.
visibility
enum (visible, none)
(optional)
(Default value is visible
.)
Determines whether the layer objects will be drawn on the map (visible
- yes, none
- no).
style for «line»
color
color
or Expression<color>
(optional)
(Default value is "#000000"
. Does not support the following extractor expressions: get
, sourceAttr
, featureState
, global
.)
Line color.
width
number
or Expression<number>
(optional)
(Default value is 1
.)
Line width in pixels.
visibility
enum (visible, none)
(optional)
(Default value is visible
.)
Determines whether the layer objects will be drawn on the map (visible
- yes, none
- no).
style for «dashedLine»
color
color
or Expression<color>
(optional)
(Default value is "#000000"
. Does not support the following extractor expressions: get
, sourceAttr
, featureState
, global
.)
Color of the main line segments.
width
number
or Expression<number>
(optional)
(Default value is 1
.)
Line width in pixels.
dashLength
number
or Expression<number>
(optional)
(Default value is 1
.)
Length of the main line segments in pixels.
gapLength
number
or Expression<number>
(optional)
(Default value is 1
.)
Length of the additional line segments (gaps) in pixels.
gapColor
color
or Expression<color>
(optional)
(Default value is "rgba(0, 0, 0, 0)"
. Does not support the following extractor expressions: get
, sourceAttr
, featureState
, global
.)
Color of the additional line segments (gaps).
visibility
enum (visible, none)
(optional)
(Default value is visible
.)
Determines whether the layer objects will be drawn on the map (visible
- yes, none
- no).
style for «point»
iconImage
string
or Expression<string>
(optional)
(Does not support the following extractor expressions: get
, sourceAttr
, featureState
, global
.)
Name of the icon. If omitted, icon will not be drawn.
Only squared icons should be used, because any icon will be scaled to square (aspect ratio = 1).
iconWidth
number
or Expression<number>
(optional)
(0 to 512. Default value is 16
. Does not support the following extractor expressions: get
, sourceAttr
, featureState
, global
.)
Icon width in pixels.
iconAnchor
array of number
(optional)
(Default value is [0.5, 0.5]
.)
Sets the position of the anchor point of the icon. Specified as an array of two relative coordinates X and Y.
For example:
[0, 0]
- upper left corner of the icon;[0.5, 0.5]
- center of the icon;[1, 1]
- lower right corner of the icon;[-1, -1]
- the anchor is outside the icon, the icon will be drawn with an offset from its position on the map.
iconOffset
array of number
(optional)
(Default value is [0, 0]
.)
Sets an offset of iconAnchor
point. Specified as an array of two numbers [offsetX, offsetY], where offsetX is the horizontal offset in pixels, and offsetY is the vertical offset.
For example:
[10, 20]
— offset to the right by 10 pixels and down by 20;[-15, -5]
— offset to the left by 15 pixels and up by 5;[10, -5]
— offset to the right by 10 pixels and up by 5.
textField
string
or Expression<string>
(optional)
(Default value is ["get", "db_label"]
.)
Label text.
textFont
string
or Expression<string>
(optional)
(Does not support the following extractor expressions: get
, sourceAttr
, featureState
, global
.)
Label font. If not set, label will not be drawn.
textColor
color
or Expression<color>
(optional)
(Default value is "#000000"
. Does not support the following extractor expressions: get
, sourceAttr
, featureState
, global
.)
Label color.
textFontSize
number
or Expression<number>
(optional)
(0 to 512. Default value is 16
. Does not support the following extractor expressions: get
, sourceAttr
, featureState
, global
.)
Label font size in pixels.
textLineHeight
number
(optional)
(Default value is 1.2
.)
Label line spacing in relative units.
textLetterSpacing
number
(optional)
(Default value is 0
.)
Label letter spacing in relative units.
textPlacement
enum (topCenter, rightCenter, bottomCenter, leftCenter)
or Expression<topCenter | rightCenter | bottomCenter | leftCenter>
(optional)
(Default value is bottomCenter
.)
Label location relative to the icon. If icon is not set, this parameter is not used.
topCenter
- above the iconbottomCenter
- under the iconleftCenter
- left side of the iconrightCenter
- right side of the icon
textOffset
number
or Expression<number>
(optional)
(Default value is 0
.)
Label offset from the icon in pixels.
textHaloColor
color
or Expression<color>
(optional)
(Default value is "rgba(0, 0, 0, 0)"
.)
Label outline color.
textHaloWidth
number
(optional)
(Default value is 0
.)
Label outline width in pixels.
textMaxLengthPerLine
number
(optional)
(Default value is 30
.)
Line length for word wrapping (number of characters). If exceeded, the next word will be wrapped to the next line.
For example, if the value is 3
, "Velikiy Novgorod" will be split into 2 lines:
Velikiy
Novgorod
allowOverlap
boolean
(optional)
(Default value is false
.)
If true, the object will not be part of any labeling group and will always be drawn. iconLabelingGroup
and textLabelingGroup
properties will be ignored.
iconLabelingGroup
string
(optional)
(Default value is "default"
.)
Labeling group for the icon. Must be set to one of the values from the labelingGroups.groups
array.
iconLabelingMargin
LabelingMargin
(optional)
Extra icon margins when used in a labeling group.
iconPriority
number
(optional)
(Non-negative integer. Default value is 0
.)
Icon priority when used in a labeling group.
textLabelingGroup
string
(optional)
(Default value is "default"
.)
Labeling group for the label. Must be set to one of the values from the labelingGroups.groups
array.
textLabelingMargin
LabelingMargin
(optional)
Extra label margins when used in a labeling group.
textPriority
number
(optional)
(Non-negative integer. Default value is 0
.)
Label priority when used in a labeling group. Can not be greater than iconPriority
. Label will be hidden if its icon becomes overlapped.
visibility
enum (visible, none)
(optional)
(Default value is visible
.)
Determines whether the layer objects will be drawn on the map (visible
- yes, none
- no).
style for «raster»
opacity
number
or Expression<number>
(optional)
(A number from 0
to 1
. Default value is 1
.)
Opacity of the image. 0 - the image is fully transparent (invisible), 1 - the image is fully opaque.
style for «heatmap»
color
InterpolateExpression<color>
(optional)
(Default value ['interpolate', ['linear'], ['heatmap-density'], 0, 'rgba(53,136,253,0)', 0.2, 'rgba(53,136,253,0.2)', 0.4, 'rgb(255,201,77)', 0.6, 'rgb(255,202,20)', 0.75, 'rgb(245,0,7)', 1, 'rgb(255,0,0)']
.)
Defines the color of each pixel depending on heatmap intensity
. Intensity is a number from 0 to 1.
radius
number
or Expression<number>
(optional)
(Non-negative integer. Default value is 30
.)
Radius of heatmap points in pixels. Increasing the value makes the heatmap smoother.
opacity
number
or Expression<number>
(optional)
(A number from 0
to 1
. Default value is 1
.)
The opacity of whole heatmap layer. If 0, the layer will be completely transparent, and if 1, it will be opaque.
intensity
number
or Expression<number>
(optional)
(Non-negative number. Default value is 1
.)
Heatmap kernel multiplier. The higher its value, the higher the intensity of the color. It's applied to all heatmap points, unlike the weight
.
weight
number
or Expression<number>
(optional)
(Non-negative number. Default value is 1
.)
A measure of how much an individual point contributes to the heatmap. A value of 10 would be equivalent to having 10 points of weight 1 in the same spot.
downscale
number
(optional)
(Positive number. Default value is 1
.)
Heatmap texture divider. The higher its value, the worse the heatmap quality, but the faster heatmap rendering speed.
Value types (T)
number
A regular JSON number in the range from -2147483
to 2147483
.
Unless otherwise stated, the number may contain a fractional part, but all values will be rounded to the third decimal place.
{
"textFontSize": 16
}
boolean
A regular JSON Boolean value of true
or false
.
{
"allowOverlap": true
}
color
A JSON string in one of the following formats:
{
"color": "#ff0",
"color": "#ffff00",
"color": "#ffff00aa",
"color": "rgb(255, 255, 0)",
"color": "rgba(255, 255, 0, 1)",
"color": "hsl(100, 50%, 50%)",
"color": "hsla(100, 50%, 50%, 1)"
}
string
A regular JSON string.
{
"name": "Snowy style"
}
enum
A set of possible string values.
For example, the visibility
parameter can be only one of two values: "visible"
or "none"
.
{
"visibility": "visible"
}
{
"visibility": "none"
}
array
A regular JSON array.
{
"iconAnchor": [0.5, 0.5]
}
{
"expression": ['interpolate', ['linear'], ['zoom'], 10, 0, 15, 10]
}
object
A regular JSON object.
{
"key1": "SomeValue",
"key2": [0, 1],
"key3": {
"innerKey1": true,
}
}
LabelingMargin
Extra margins for objects. Represented as a JSON object with two fields:
- topBottom (
number
, default value is0
) - top and bottom margin in pixels. - leftRight (
number
, default value is0
) - left and right margin in pixels.
{
"topBottom": 10,
"leftRight": 15,
}
Expressions (Expression<T>)
Expression is a special type of object that can be used instead of a simple value in some properties. Expressions can be viewed as functions that return a value of a specific type (<T>). For example, an expression that can be used instead of a number
value is denoted as Expression<number>
.
Expressions are represented as JSON arrays. The first element of the array is the name of the expression. All subsequent elements are the arguments of the expression. Expressions can be nested, i.e. one expression can use another as an argument.
{
"filter": ["match", ["get", "type"], ["area"], true, false],
}
In the above example, the match
expression, which compares two values and returns a Boolean (or other) result, has 4 arguments:
["get", "type"]
- first value to compare. Here, theget
expression is used to get the value.["area"]
- second value to compare.true
- value to return if the values are equal.false
- value to return otherwise.
There are different types of expressions: extractor, logical, math, and interpolate.
Type expressions
to-boolean
Converts the value to a boolean. Returns false
for empty strings, false
, 0
, null
and NaN
. Otherwise returns true
.
Schema:
["to-boolean", ExpressionOrValue]: boolean
to-color
Converts the string color to the inner color type.
In case of a conversion error, the default color is rgba(0, 0, 0, 0)
Formats:
"#ff0",
"#ffff00", // RGB
"#ffff00aa", // RGBA
"rgb(255, 255, 0)",
"rgba(255, 255, 0, 1)",
"hsl(100, 50%, 50%)",
"hsla(100, 50%, 50%, 1)"
Schema:
["to-color", ExpressionOrValue]: InnerColorType
Example:
["to-color", ["get", "color-from-source"]]
Extractor expressions
Extractor expressions are expressions that can be used to get the value from somewhere else: from object attributes, data source, or global variable.
get
Extract the value of one of the object attributes. Returns null
if the requested property is missing.
Schema:
["get", string]: value
Example:
['get', 'objectAttrName'];
sourceAttr
Extract the value from the data source of the object. Returns null
if the requested property is missing.
Schema:
["sourceAttr", string]: value
Example:
['sourceAttr', 'sourceAttrName'];
featureState
Extract the value of a user-setted object attribute. Returns null
if the requested property is missing.
Expression featureState
works only with defaultSource
objects.
Schema:
["featureState", string]: value
Example:
['featureState', 'featureStateAttrName'];
global
Extract the value of a global style variable. Returns null
if the requested variable is missing.
Reserved global variables are set by the map itself. There are the following reserved variables:
_activeFloorBuildingIds
— array of building IDs with active floor plans;_activeFloorIds
— array of active floor IDs from buildings with active floor plans;_activeFloorIsMetro
- Boolean.true
if active floors plan is a metro schema;trafficOn
- Boolean.true
if traffic display is enabled;parkingOn
- Boolean.true
if parking display is enabled;navigatorOn
- Boolean.true
if navigation mode is enabled;immersiveRoadsOn
- Boolean.true
if immersive roads rendering is enabled;terrainEnabled
- Boolean.true
if 3D terrain is enabled;
where the ID is a 64-bit integer from 2GIS data converted to a string. If there are no active floors, both values will be equal to null
.
Also, global variables can be set by the user by calling the API. We strongly recommend not to name your variables with the first _
symbol, because it may become reserved in the future.
Reserved boolean global variables have false
as their default value.
Schema:
["global", string]: value
Example:
['global', 'globalVariableName'];
Logical expressions
Logical expressions compare multiple values to determine a single output.
!
Returns true
if the passed value is false
, and vice versa. If the value isn't boolean, converts it to a boolean using a to-boolean
expression.
Schema:
["!", ExpressionOrValue]: boolean
==
Returns true
if the passed two values are equal. Otherwise returns false
.
Schema:
["==", InputType, InputType]: boolean
InputType
- values for comparison.
!=
Returns false
if the passed two values are equal. Otherwise returns false
.
Schema:
["!=", InputType, InputType]: boolean
InputType
- values for comparison.
> >= < <=
Compares two values by the corresponding relationship.
Schema:
[">", InputType, InputType]: boolean
[">=", InputType, InputType]: boolean
["<", InputType, InputType]: boolean
["<=", InputType, InputType]: boolean
InputType
- values for comparison.
match
Compares one value with a set of values. Returns one result if the first value matches at least one value in the set, and another result otherwise.
Can also be used to compare one value with several sets of values.
Schema:
["match",
actual: Expression<InputType>,
expected_1: InputType[], output_1: OutputType,
expected_2: InputType[], output_2: OutputType,
//...,
fallback: OutputType
]: OutputType
actual
- expression to get the value for comparison;expected_n
- array of values for comparison;output_n
- result to return if theactual
value matches one of theexpected_n
values;fallback
- result to return if theactual
value doesn't match any value from theexpected_n
arrays;InputType
- type of the input value, must bestring
,number
orboolean
;OutputType
- type of the result value.
Single array example:
{
"filter": [
"match",
// Get the layer attribute of the object
["get", "layer"],
// Return true if the layer attribute matches one of the array values
["private", "beach"], true,
// Return false otherwise
false
]
}
Multiple arrays example:
{
"color": [
"match",
// Get the type attribute of the object
["get", "type"],
// Return black color if the type is "building"
["building"], "#000000",
// Return green color if the type is "area"
["area"], "#00FF00",
// Return white color in other cases
"#FFFFFF"
]
}
You can use any extractor expression to get the value for comparison:
{
"color": [
"match",
// Get the value of the global variable "trafficOn"
["global", "trafficOn"],
// Return red color if the value of "trafficOn" is true
[true], "rgb(255, 0, 0)",
// Return white color otherwise
"#ffffff"
]
}
all
Compares multiple Boolean values. Returns true
if all values are true
. If at least one value is false
, returns false
.
Schema:
["all", BooleanExpression, BooleanExpression, ...]: boolean
BooleanExpression
- expression that returns a Boolean value
For example, the following expression will return true
only if the object is a paid highway:
"filter": [
"all",
// Object type in the data source must be "roads"
["match", ["sourceAttr", "type"], ["roads"], true, false],
// Object category must be "highway"
["match", ["get", "category"], ["highway"], true, false],
// "isPaid" object attribute must be true
["get", "isPaid"],
]
any
Compares multiple Boolean values. Returns true
if at least one value is true
.
Schema:
["any", BooleanExpression, BooleanExpression, ...]: boolean
BooleanExpression
- expression that returns a Boolean value
For example, the following expression will return true
if the object is a highway or an internal road:
"filter": [
"any",
// Check for a highway
["match", ["get", "category"], ["highway"], true, false],
// Check for an internal road
["match", ["get", "category"], ["internal"], true, false],
]
in expression
Checks whether an array includes a certain value. The first argument is the value, the second is the array. Works only with an array of numbers or strings. If the second argument is equal to null
, it will return false
.
Schema:
["in",
item: ItemType,
array: ArrayType,
]: boolean
InputType
— number, string, boolean or extractor expression;ArrayType
— expression that returns data in the form of an array.
Example:
// If a global vairable "foo" is equal to an array ["a", "b", "c"], then:
["in", "a", ["global", "foo"]] // returns true
["in", "d", ["global", "foo"]] // returns false
["in", ["get", "bar"], ["global", "foo"]] // returns true, if the object attribute "bar" is either "a", "b" or "c"
Mathematical expressions
Expressions to perform various mathematical operations.
^
Returns the value of the first input raised to the power specified by the second one.
Schema:
["^", ExpressionOrValue, ExpressionOrValue]: number
log10
Returns the base 10 logarithm of the first input.
Schema:
["log10", ExpressionOrValue]: number
Interpolation expressions
Interpolation expressions return different value A depending on some other value B. Currently, only the zoom level of the map can be used as a value B.
interpolate
Returns an interpolated value between the start value and the end value. For example, if we set the start value to 20
on zoom level 10
, and the end value to 30
on zoom level 15
, an interpolated value on zoom level 12
will be 24
. interpolate
will not return value lower than the start value and higher than the end value.
Additionally, you can specify multiple points for interpolation and change the interpolation formula from linear to exponential. Values must be specified in ascending order.
Interpolation also works for colors.
Schema:
["interpolate",
interpolation: ["linear"] | ["exponential", base],
["zoom"],
zoom_1: number, output_1: OutputType,
zoom_2: number, output_2: OutputType,
//...
]: OutputType
interpolation
- interpolation formula to be used. For "exponential", you can specify thebase
parameter (a number from0
to2
,1
by default).zoom_n
- map zoom level.output_n
- value corresponding tozoom_n
.OutputType
- type of value, can benumber
orcolor
.
For example, you can change width depending on the current zoom level of the map:
{
"width": [
"interpolate", ["linear"], ["zoom"],
// If the zoom level is ≤ 10, return 5
10, 5,
// If the zoom level is between 10 and 15, return an interpolated value from 5 to 8
15, 8,
// If the zoom level is ≥ 15, return 8
]
}
Colors can be interpolated in a similar way:
{
"textColor": [
"interpolate", ["exponential"], ["zoom"],
// Gradually change the color from red at zoom level 14 and less...
14, "#ff0000",
// ...to black at zoom level 17...
17, "#000",
// ...to semi-transparent cyan at zoom level 19 and more
19, "rgba(0, 100, 200, 50%)"
]
}
step
Returns different values depending on whether the current value is greater than the specified values. For example, you can specify a value to be returned when the current map zoom level is less than 10, and another value when it is greater than 10.
Values must be specified in ascending order.
Schema:
["step",
["zoom"],
defaultValue : OutputType,
zoom_1: number, output_1: OutputType,
zoom_2: number, output_2: OutputType,
//...
]: OutputType
defaultValue
- value to be returned if the current map zoom level is less than the first specified valuezoom_n
- map zoom leveloutput_n
- value to be returned after comparisonOutputType
- type of value, can be any of the basic types
For example, to change the font size of a label when the zoom level changes:
{
"fontSize": [
"step", ["zoom"],
// If the zoom level is < 10, return 12
12,
// If the zoom level is between 10 and 15, return 16
10, 16,
// If the zoom level is ≥ 15, return 22
15, 22,
]
}
Since step
works with all basic types of values, you can also use it to change the font of a label:
{
"textFont": [
"step", ["zoom"],
// Use Noto Sans when the zoom level is < 15
"Noto_Sans",
// Use Noto Sans Bold when the zoom level is ≥ 15
15, "Noto_Sans_Bold",
]
}