[comment]: # aside:1
[comment]: # ({7bfc83a8-cdacabd4})
# Map object
The following objects are directly related to the `map` API.
[comment]: # ({/7bfc83a8-cdacabd4})
[comment]: # ({8d884944-62f73225})
### Map
The map object has the following properties.
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|sysmapid|ID|ID of the map.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *read-only*
- *required* for update operations|
|height|integer|Height of the map in pixels.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* for create operations|
|name|string|Name of the map.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* for create operations|
|width|integer|Width of the map in pixels.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* for create operations|
|backgroundid|ID|ID of the image used as the background for the map.|
|background\_scale|integer|Whether to enable background image proportional scaling.
Possible values:
0 - disable scaling;
1 - *(default)* enable image scaling.|
|expand\_macros|integer|Whether to expand macros in labels when configuring the map.
Possible values:
0 - *(default)* do not expand macros;
1 - expand macros.|
|expandproblem|integer|Whether the problem trigger will be displayed for elements with a single problem.
Possible values:
0 - always display the number of problems;
1 - *(default)* display the problem trigger if there's only one problem.|
|grid\_align|integer|Whether to enable grid aligning.
Possible values:
0 - disable grid aligning;
1 - *(default)* enable grid aligning.|
|grid\_show|integer|Whether to show the grid on the map.
Possible values:
0 - do not show the grid;
1 - *(default)* show the grid.|
|grid\_size|integer|Size of the map grid in pixels.
Supported values: 20, 40, 50, 75 and 100.
Default: 50.|
|highlight|integer|Whether icon highlighting is enabled.
Possible values:
0 - highlighting disabled;
1 - *(default)* highlighting enabled.|
|iconmapid|ID|ID of the icon map used on the map.|
|label\_format|integer|Whether to enable advanced labels.
Possible values:
0 - *(default)* disable advanced labels;
1 - enable advanced labels.|
|label\_location|integer|Location of the map element label.
Possible values:
0 - *(default)* bottom;
1 - left;
2 - right;
3 - top.|
|label\_string\_host|string|Custom label for host elements.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* if `label_type_host` is set to "custom"|
|label\_string\_hostgroup|string|Custom label for host group elements.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* if `label_type_hostgroup` is set to "custom"|
|label\_string\_image|string|Custom label for image elements.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* if `label_type_image` is set to "custom"|
|label\_string\_map|string|Custom label for map elements.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* if `label_type_map` is set to "custom"|
|label\_string\_trigger|string|Custom label for trigger elements.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* if `label_type_trigger` is set to "custom"|
|label\_type|integer|Map element label type.
Possible values:
0 - label;
1 - IP address;
2 - *(default)* element name;
3 - status only;
4 - nothing.|
|label\_type\_host|integer|Label type for host elements.
Possible values:
0 - label;
1 - IP address;
2 - *(default)* element name;
3 - status only;
4 - nothing;
5 - custom.|
|label\_type\_hostgroup|integer|Label type for host group elements.
Possible values:
0 - label;
2 - *(default)* element name;
3 - status only;
4 - nothing;
5 - custom.|
|label\_type\_image|integer|Label type for host group elements.
Possible values:
0 - label;
2 - *(default)* element name;
4 - nothing;
5 - custom.|
|label\_type\_map|integer|Label type for map elements.
Possible values:
0 - label;
2 - *(default)* element name;
3 - status only;
4 - nothing;
5 - custom.|
|label\_type\_trigger|integer|Label type for trigger elements.
Possible values:
0 - label;
2 - *(default)* element name;
3 - status only;
4 - nothing;
5 - custom.|
|markelements|integer|Whether to highlight map elements that have recently changed their status.
Possible values:
0 - *(default)* do not highlight elements;
1 - highlight elements.|
|severity\_min|integer|Minimum severity of the triggers that will be displayed on the map.
Refer to the [trigger `severity` property](/manual/api/reference/trigger/object#trigger) for a list of supported trigger severities.|
|show\_element\_label|integer|How to display element labels by default.
Possible values:
0 - always display;
1 - *(default)* auto-hide.|
|show\_link\_label|integer|How to display link labels by default.
Possible values:
0 - always display;
1 - *(default)* auto-hide.|
|show\_unack|integer|How problems should be displayed.
Possible values:
0 - *(default)* display the count of all problems;
1 - display only the count of unacknowledged problems;
2 - display the count of acknowledged and unacknowledged problems separately.|
|userid|ID|ID of the user that is the owner of the map.|
|private|integer|Type of map sharing.
Possible values:
0 - public map;
1 - *(default)* private map.|
|show\_suppressed|integer|Whether suppressed problems are shown.
Possible values:
0 - *(default)* hide suppressed problems;
1 - show suppressed problems.|
[comment]: # ({/8d884944-62f73225})
[comment]: # ({39c8847f-c7b92dfc})
### Map element
The map element object defines an object displayed on a map. It has the
following properties.
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|selementid|ID|ID of the map element.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *read-only*|
|elements|array|[Element](#map-element-host) data object.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* if `elementtype` is set to "host", "map", "trigger" or "host group"|
|elementtype|integer|Type of map element.
Possible values:
0 - host;
1 - map;
2 - trigger;
3 - host group;
4 - image.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|iconid\_off|ID|ID of the image used to display the element in default state.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|areatype|integer|How separate host group hosts should be displayed.
Possible values:
0 - *(default)* the host group element will take up the whole map;
1 - the host group element will have a fixed size.|
|elementsubtype|integer|How a host group element should be displayed on a map.
Possible values:
0 - *(default)* display the host group as a single element;
1 - display each host in the group separately.|
|evaltype|integer|Map element tag filtering condition [evaluation method](/manual/config/visualization/maps/map#adding-elements).
Possible values:
0 - *(default)* And/Or;
2 - Or.|
|height|integer|Height of the fixed size host group element in pixels.
Default: 200.|
|iconid\_disabled|ID|ID of the image used to display disabled map elements.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *supported* if `elementtype` is set to "host", "map", "trigger", or "host group"|
|iconid\_maintenance|ID|ID of the image used to display map elements in maintenance.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *supported* if `elementtype` is set to "host", "map", "trigger", or "host group"|
|iconid\_on|ID|ID of the image used to display map elements with problems.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *supported* if `elementtype` is set to "host", "map", "trigger", or "host group"|
|label|string|Label of the element.|
|label\_location|integer|Location of the map element label.
Possible values:
-1 - *(default)* default location;
0 - bottom;
1 - left;
2 - right;
3 - top.|
|permission|integer|Type of permission level.
Possible values:
-1 - none;
2 - read only;
3 - read-write.|
|show\_label|integer|How to display the element label.
Possible values:
-1 - *(default)* map default;
0 - always display;
1 - auto-hide.|
|sysmapid|ID|ID of the map that the element belongs to.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *read-only*|
|urls|array|Map element URLs.
The map element URL object is [described in detail below](object#map-element-url).|
|use\_iconmap|integer|Whether icon mapping must be used for host elements.
Possible values:
0 - do not use icon mapping;
1 - *(default)* use icon mapping.|
|viewtype|integer|Host group element placing algorithm.
Possible values:
0 - *(default)* grid.|
|width|integer|Width of the fixed size host group element in pixels.
Default: 200.|
|x|integer|X-coordinates of the element in pixels.
Default: 0.|
|y|integer|Y-coordinates of the element in pixels.
Default: 0.|
|zindex|integer|Value used to order map elements (z-index).
Default: 0.|
[comment]: # ({/39c8847f-c7b92dfc})
[comment]: # ({850c4220-305dd3e0})
#### Map element Host
The map element Host object defines one host element.
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|hostid|ID|ID of the host.|
[comment]: # ({/850c4220-305dd3e0})
[comment]: # ({d8f65e8c-e1118d67})
#### Map element Host group
The map element Host group object defines one host group element.
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|groupid|ID|ID of the host group.|
[comment]: # ({/d8f65e8c-e1118d67})
[comment]: # ({b29a15a2-2d745dcc})
#### Map element Map
The map element Map object defines one map element.
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|sysmapid|ID|ID of the map.|
[comment]: # ({/b29a15a2-2d745dcc})
[comment]: # ({d5e7bb17-0283fd46})
#### Map element Trigger
The map element Trigger object defines one or more trigger elements.
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|triggerid|ID|ID of the trigger.|
[comment]: # ({/d5e7bb17-0283fd46})
[comment]: # ({1ac46cd0-a7495119})
#### Map element Tag
The map element Tag object has the following properties.
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|tag|string|Map element tag name.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|operator|integer|Map element tag condition [operator](/manual/config/visualization/maps/map#adding-elements).
Possible values:
0 - *(default)* Contains;
1 - Equals;
2 - Does not contain;
3 - Does not equal;
4 - Exists;
5 - Does not exist.|
|value|string|Map element tag value.|
[comment]: # ({/1ac46cd0-a7495119})
[comment]: # ({2860936e-5a112b10})
#### Map element URL
The map element URL object defines a clickable link that will be
available for a specific map element. It has the following properties:
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|sysmapelementurlid|ID|ID of the map element URL.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *read-only*|
|name|string|Link caption.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|url|string|Link URL.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|selementid|ID|ID of the map element that the URL belongs to.|
[comment]: # ({/2860936e-5a112b10})
[comment]: # ({c95f043b-1e44fd2a})
### Map link
The map link object defines a link between two map elements. It has the
following properties.
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|linkid|ID|ID of the map link.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *read-only*|
|sysmapid|ID|ID of the map the link belongs to.|
|selementid1|ID|ID of the first map element linked on one end.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|selementid2|ID|ID of the first map element linked on the other end.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|drawtype|integer|Link line draw style.
Possible values:
0 - *(default)* line;
2 - bold line;
3 - dotted line;
4 - dashed line.|
|color|string|Line color as a hexadecimal color code.
Default: `000000`.|
|label|string|Link label.|
|show\_label|integer|How to display the link label.
Possible values:
-1 - *(default)* map default;
0 - always display;
1 - auto-hide.|
|indicator\_type|integer|Select the link indicator type.
Possible values:
0 - *(default)* static link;
1 - trigger;
2 - item value.|
|linktriggers|array|Map link triggers to use as link status indicators.
The map link trigger object is [described in detail below](object#map-link-trigger).
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* if `indicator_type` is set to "trigger" (1).|
|itemid|ID|ID of the item.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* if `indicator_type` is set to "item value" (2).|
|highlights|array|Map link highlights to use as link status indicators.
The map link indicators object is [described in detail below](object#map-link-indicators).
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* if `indicator_type` is set to "item value" (2).|
|thresholds|array|Map link thresholds to use as link status indicators.
The map link indicators object is [described in detail below](object#map-link-indicators).
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required* if `indicator_type` is set to "item value" (2).|
|permission|integer|Type of permission level.
Possible values:
-1 - none;
2 - read only;
3 - read-write.|
[comment]: # ({/c95f043b-1e44fd2a})
[comment]: # ({775623bc-219c2bce})
#### Map link trigger
The map link trigger object defines a map link status indicator based on
the state of a trigger. It has the following properties:
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|triggerid|ID|ID of the trigger used as a link indicator.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|color|string|Indicator color as a hexadecimal color code.
Default: `DD0000`.|
|drawtype|integer|Indicator draw style.
Possible values:
0 - *(default)* line;
2 - bold line;
3 - dotted line;
4 - dashed line.|
[comment]: # ({/775623bc-219c2bce})
[comment]: # ({f89ab8e1-d49698db})
#### Map link indicators
The map link indicators object defines a map link status indicator based on
the item value. It has the following properties:
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|pattern|string|Regular expression to compare against. Available only for highlights.|
|sortorder|integer|Used for defining the sort order of highlights. Available only for highlights.|
|threshold|string|Numeric value to compare against. Available only for thresholds.|
|drawtype|integer|Indicator draw style.
Possible values:
0 - *(default)* line;
2 - bold line;
3 - dotted line;
4 - dashed line.|
|color|string|Indicator color as a hexadecimal color code.
Default: `DD0000`.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
[comment]: # ({/f89ab8e1-d49698db})
[comment]: # ({8b7be8a6-96c2bee0})
### Map URL
The map URL object defines a clickable link that will be available for
all elements of a specific type on the map. It has the following
properties:
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|sysmapurlid|ID|ID of the map URL.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *read-only*|
|name|string|Link caption.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|url|string|Link URL.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|elementtype|integer|Type of map element for which the URL will be available.
Refer to the [map element `type` property](object#map-element) for a list of supported types.
Default: 0.|
|sysmapid|ID|ID of the map that the URL belongs to.|
[comment]: # ({/8b7be8a6-96c2bee0})
[comment]: # ({385d7255-942f03ad})
### Map user
List of map permissions based on users. It has the following properties:
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|sysmapuserid|ID|ID of the map user.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *read-only*|
|userid|ID|ID of the user.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|permission|integer|Type of permission level.
Possible values:
2 - read only;
3 - read-write.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
[comment]: # ({/385d7255-942f03ad})
[comment]: # ({adad1979-f6e63a8f})
### Map user group
List of map permissions based on user groups. It has the following
properties:
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|sysmapusrgrpid|ID|ID of the map user group.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *read-only*|
|usrgrpid|ID|ID of the user group.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|permission|integer|Type of permission level.
Possible values:
2 - read only;
3 - read-write.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
[comment]: # ({/adad1979-f6e63a8f})
[comment]: # ({6cdb0526-9d0acde7})
### Map shapes
The map shape object defines a geometric shape (with or without text)
displayed on a map. It has the following properties:
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|sysmap\_shapeid|ID|ID of the map shape element.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *read-only*|
|type|integer|Type of map shape element.
Possible values:
0 - rectangle;
1 - ellipse.
Property is required when new shapes are created.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *required*|
|x|integer|X-coordinates of the shape in pixels.
Default: 0.|
|y|integer|Y-coordinates of the shape in pixels.
Default: 0.|
|width|integer|Width of the shape in pixels.
Default: 200.|
|height|integer|Height of the shape in pixels.
Default: 200.|
|text|string|Text of the shape.|
|font|integer|Font of the text within shape.
Possible values:
0 - Georgia, serif
1 - "Palatino Linotype", "Book Antiqua", Palatino, serif
2 - "Times New Roman", Times, serif
3 - Arial, Helvetica, sans-serif
4 - "Arial Black", Gadget, sans-serif
5 - "Comic Sans MS", cursive, sans-serif
6 - Impact, Charcoal, sans-serif
7 - "Lucida Sans Unicode", "Lucida Grande", sans-serif
8 - Tahoma, Geneva, sans-serif
9 - "Trebuchet MS", Helvetica, sans-serif
10 - Verdana, Geneva, sans-serif
11 - "Courier New", Courier, monospace
12 - "Lucida Console", Monaco, monospace
Default: 9.|
|font\_size|integer|Font size in pixels.
Default: 11.|
|font\_color|string|Font color.
Default: `000000`.|
|text\_halign|integer|Horizontal alignment of text.
Possible values:
0 - center;
1 - left;
2 - right.
Default: 0.|
|text\_valign|integer|Vertical alignment of text.
Possible values:
0 - middle;
1 - top;
2 - bottom.
Default: 0.|
|border\_type|integer|Type of the border.
Possible values:
0 - none;
1 - `—————`;
2 - `·····`;
3 - `- - -`.
Default: 0.|
|border\_width|integer|Width of the border in pixels.
Default: 0.|
|border\_color|string|Border color.
Default: `000000`.|
|background\_color|string|Background color (fill color).
Default: `(empty)`.|
|zindex|integer|Value used to order all shapes and lines (z-index).
Default: 0.|
[comment]: # ({/6cdb0526-9d0acde7})
[comment]: # ({a3759606-b1536eee})
### Map lines
The map line object defines a line displayed on a map. It has the
following properties:
|Property|[Type](/manual/api/reference_commentary#data-types)|Description|
|--|--|------|
|sysmap\_shapeid|ID|ID of the map shape element.
[Property behavior](/manual/api/reference_commentary#property-behavior):
- *read-only*|
|x1|integer|X-coordinates of the line point 1 in pixels.
Default: 0.|
|y1|integer|Y-coordinates of the line point 1 in pixels.
Default: 0.|
|x2|integer|X-coordinates of the line point 2 in pixels.
Default: 200.|
|y2|integer|Y-coordinates of the line point 2 in pixels.
Default: 200.|
|line\_type|integer|Type of the lines.
Possible values:
0 - none;
1 - `—————`;
2 - `·····`;
3 - `- - -`.
Default: 0.|
|line\_width|integer|Width of the lines in pixels.
Default: 0.|
|line\_color|string|Line color.
Default: `000000`.|
|zindex|integer|Value used to order all shapes and lines (z-index).
Default: 0.|
[comment]: # ({/a3759606-b1536eee})