Skip to main content

Building routes

You can build optimal routes between multiple points on the map (up to 10 points) using the Directions plugin.

Getting started​

The plugin uses the Routing API. To work with the API of the service, you need to get an access key:

  1. Get an access key.
  2. Install the plugin.
  3. Initialize the plugin.

1. Get an access key​

The plugin uses Directions API. Since Directions API is deprecated, get an access key for Routing API:

  1. Sign in to the Platform Manager.
  2. Create a demo key or purchase a subscription for using API.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.

2. Install the plugin​

Using script tag​

To install the plugin, add the following line to your HTML page (after initializing the MapGL):

<script src="https://unpkg.com/@2gis/mapgl-directions@^2/dist/directions.js"></script>

Using npm package​

If you use npm, you can install the plugin using the @2gis/mapgl-directions package:

npm install @2gis/mapgl-directions

3. Initialize the plugin​

Using script tag​

Initialize a Directions object:

const directions = new mapgl.Directions(map, {
    directionsApiKey: 'Your Directions API key',
});

Using npm package​

Import the plugin as an ES module:

import { Directions } from '@2gis/mapgl-directions';

Or as a CommonJS module:

const { Directions } = require('@2gis/mapgl-directions');

const directions = new Directions(map, {
    directionsApiKey: 'Your Directions API key',
});

Plugin usage​

After initialization, you can call the following methods:

Both methods accept an array of geographical coordinates as the points parameter. For example:

directions.carRoute({
    points: [
        [55.27887, 25.21001],
        [55.30771, 25.20314],
    ],
});
directions.pedestrianRoute({
    points: [
        [55.27887, 25.21001],
        [55.30771, 25.20314],
    ],
});

To clear a route, call the clear() method:

directions.clear();

Usage examples​

Car route​

Select two points on the map to build a car route between them.

Pedestrian route​

Select two points on the map to build a pedestrian route between them.

Display settings​

Graphically, a route consists of multiple sublines located one under the other:

  • the main route line at the top (route line)
  • the base line in the middle (substrate line)
  • the outline at the bottom (halo line)

You can change the width of any of these sublines using the style parameter. The width can be specified in pixels or as an InterpolateExpression (in this case, the width changes depending on the current map zoom level). To hide a subline, set its width to 0.

Example:

directions.carRoute({
    points: [
        [55.28273111108218, 25.234131928828333],
        [55.35242563034581, 25.23925607042088],
    ],
    style: {
        // Main line (green)
        routeLineWidth: [
            'interpolate',
            ['linear'],
            ['zoom'],
            10,
            30, // Main line width will change from 30 px at zoom level 10 and below...
            14,
            3, // ...to 3 px at zoom level 14 and above
        ],
        // Base line (white)
        substrateLineWidth: [
            'interpolate',
            ['linear'],
            ['zoom'],
            10,
            3, // Base line width will change from 3 px at zoom level 10 and below...
            14,
            50, // ...to 50 px at zoom level 14 and above
        ],
        // Outline width is 60 px at all zoom levels
        haloLineWidth: 60,
    },
});

Zoom in and zoom out to observe the width interpolation in action.