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

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 cause group2 to overlap group1 in case of intersection; intersection of all other groups will cause a z-index fight. If the listed group is not in the groups 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 icon
• bottomCenter - under the icon
• leftCenter - left side of the icon
• rightCenter - 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 is 0) - top and bottom margin in pixels.
• leftRight (number, default value is 0) - 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, the get 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 the actual value matches one of the expected_n values;
• fallback - result to return if the actual value doesn't match any value from the expected_n arrays;
• InputType - type of the input value, must be string, number or boolean;
• 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']][('in', 'd', ['global', 'foo'])][ // returns true // 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 the base parameter (a number from 0 to 2, 1 by default).
• zoom_n - map zoom level.
• output_n - value corresponding to zoom_n.
• OutputType - type of value, can be number or color.

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 value
• zoom_n - map zoom level
• output_n - value to be returned after comparison
• OutputType - 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",
  ]
}