Arrows

You can add animated arrows to the map using the Arrow object. This object accepts coordinates as a vector (a set of points describing a path).

The primary practical use case for arrows is visualizing building entrances, which can be retrieved via the Places API. In the API response, each entrance contains a geometry.vectors field with directed segments from the road to the entrance point. These vectors are represented in WKT format LINESTRING(startLon startLat, endLon endLat), which corresponds to the coordinate format for Arrow.

To display building entrances on the map:

Get entrance data via the Places API.
Create an Arrow object and use the retrieved vectors as arrow coordinates.
Configure the display of entrance information when clicking an arrow and other parameters.

Getting entrance data

To get entrance data from the 2GIS directory:

Get an access key for the Places API. Additionally, contact the 2GIS sales team to get access to the items.links.database_entrances field with entrance information.
Send a GET request to the /3.0/items/byid method, specifying the ID of the desired object (building or organization) and the fields=items.links.database_entrances parameter to include entrance data in the response:
```
https://catalog.api.2gis.com/3.0/items/byid?id=5348660212691856&fields=items.links.database_entrances&key=YOUR_KEY
```

The response will contain an items.links.database_entrances array. Each element (an individual entrance) is described by the following fields:

id - entrance identifier
entity_name - display name of the entrance (e.g., "Entrance 2")
entity_number - entrance number
is_visible_on_map - whether the entrance is visible on the map
has_poi - whether the entrance has a POI
geometry - geometric data of the entrance:
- geometry.points - array of entrance points in WKT format (POINT(longitude latitude))
- geometry.vectors - array of directed segments (vectors) from the road to the entrance point in WKT format (LINESTRING(startLon startLat, endLon endLat))
- geometry.normals - array of normals to the building in WKT format

See the full response schema in the API reference.

Example structure for a single entrance:

{
    "entity_name": "Entrance 2",
    "entity_number": "2",
    "geometry": {
        "normals": [
            "LINESTRING(31.339675 59.883814,30.34093 59.93391)"
        ],
        "points": [
            "POINT(30.340930109645146 59.933909825566758)"
        ],
        "vectors": [
            "LINESTRING(30.341108 59.933901,30.34093 59.93391)"
        ]
    },
    "has_poi": true,
    "id": "5349068278782309",
    "is_visible_in_ui": true,
    "is_visible_on_map": true,
    "name": "2"
}

The geometry.vectors field contains the coordinates required to draw the arrow.

Creating an arrow

To create an arrow, create an Arrow object and pass coordinates from the geometry.vectors field as an array of [longitude, latitude] points. The arrow is drawn along the given points, with the tip (arrowhead) placed at the last point.

// Entrance vector from the Places API: LINESTRING(30.341108 59.933901, 30.34093 59.93391)
const arrow = new mapgl.Arrow(map, {
    coordinates: [
        [30.341108, 59.933901],  // Vector start (at the road)
        [30.34093, 59.93391],    // Vector end (entrance point), where the tip points
    ],
    color: '#0085a0',
    width: 4,
    strokeColor: '#ffffff',
    strokeWidth: 1,
    animate: true,
    interactive: true,
});

Key parameters (see the full list in ArrowOptions):

Parameter	Type	Default	Description
`coordinates`	`number[][]` \| `number[][][]`	-	Arrow path coordinates. The tip is placed at the end of the path.
`color`	`string`	`'#0085a0'`	Fill color in HEX format.
`strokeColor`	`string`	`'#ffffff'`	Stroke color in HEX format.
`width`	`number`	`4`	Line width in pixels.
`animate`	`boolean`	`false`	Enable tip animation.
`iterationCount`	`number`	`Infinity`	Number of animation repetitions.
`tipMovementAmplitude`	`number`	`6`	Tip movement amplitude during animation in pixels.
`interactive`	`boolean`	`false`	Enable pointer events: click, hover, and others.

Multiple arrows in one object

If an entrance has multiple vectors (e.g., the entrance is accessible from different sides of the building), you can pass all paths into a single Arrow object using the number[][][] format (an array of arrays of points):

// Entrance with two vectors: accessible from two sides
const arrow = new mapgl.Arrow(map, {
    coordinates: [
        [   // Vector 1: approach from one side
            [30.340455, 59.933728],
            [30.340498, 59.933815],
        ],
        [   // Vector 2: approach from the other side
            [30.340606, 59.934033],
            [30.340563, 59.933946],
        ],
    ],
    color: '#0085a0',
    animate: true,
});

Arrow along a polyline

An arrow can follow not only a straight line but also an arbitrary polyline defined by multiple points. This is useful for displaying a path that follows road curves.

const arrow = new mapgl.Arrow(map, {
    coordinates: [
        [30.339214, 59.934282],
        [30.339027, 59.933919],
        [30.339372, 59.933880],
        [30.339603, 59.933883],
        [30.339900, 59.933817],
        [30.340129, 59.933814],
        [30.340350, 59.933809],
    ],
    color: '#d81b60',
    animate: true,
});

The arrow is drawn through all the specified points. The tip is always placed at the end of the path - at the last point of the array.

Animation

The Arrow object supports built-in tip animation. To enable animation, set the animate: true parameter:

const arrow = new mapgl.Arrow(map, {
    coordinates: [...],
    animate: true,
});

The number of animation repetitions is controlled by the iterationCount parameter:

Infinity (default) - infinite loop, the tip pulses continuously.
1 - one animation cycle, then the arrow stops.
Any positive number N - the animation repeats N times.

The tip movement amplitude is configured with tipMovementAmplitude in pixels (the default value is 6). Higher values produce more noticeable movement:

const arrow = new mapgl.Arrow(map, {
    coordinates: [...],
    animate: true,
    iterationCount: 3,         // Three animation cycles
    tipMovementAmplitude: 10,  // Increased amplitude
});

In the example below, entrance arrows animate infinitely (iterationCount: Infinity), while the polyline arrow (path from a neighboring building) animates only 3 times (iterationCount: 3).

Interactivity

By default, the Arrow object does not respond to pointer events (interactive: false). To enable interactivity, set the interactive: true parameter:

const arrow = new mapgl.Arrow(map, {
    coordinates: [...],
    interactive: true,
});

The Arrow object supports all standard events for dynamic objects.

Customizing appearance

Color and stroke

The main arrow color is set with color, and the stroke color with strokeColor. Both values are specified in HEX format (RGB or RGBA):

const arrow = new mapgl.Arrow(map, {
    coordinates: [...],
    color: '#e65100',       // Fill color
    strokeColor: '#ffffff', // Stroke color
    width: 5,               // Line width (pixels)
    strokeWidth: 2,         // Stroke width (pixels)
});

The roundingRadius parameter sets the corner rounding at polyline bends in pixels (the default value is 2). It is recommended to choose a value proportional to width.

Tip size

Arrow tip dimensions are controlled by multipliers relative to the line width (width):

tipWidthMultiplier (default 1.5) - arrow tip width multiplier
tipHeightMultiplier (default 2.8) - arrow tip height multiplier

const arrow = new mapgl.Arrow(map, {
    coordinates: [...],
    width: 6,
    tipWidthMultiplier: 2.0,   // Arrow tip width - 2× the line width
    tipHeightMultiplier: 3.5,  // Arrow tip height - 3.5× the line width
});

Removing an arrow

To remove an arrow from the map, call the destroy() method:

arrow.destroy();

Example

In the example below, an animated Arrow object is created for each building entrance. Arrow coordinates are taken from the geometry.vectors field - directed segments from the road to the entrance. Clicking an arrow shows a popup with the entrance name.

Demo with pre-collected data

In this example, the Places API request block is commented out. Pre-collected entrance data is used for illustration.

Getting entrance data​

Creating an arrow​

Multiple arrows in one object​

Arrow along a polyline​

Animation​

Interactivity​

Customizing appearance​

Color and stroke​

Tip size​

Removing an arrow​

Example​