1. Help Center
  2. Documentation
  3. Toolkits
  4. Javascript SDK
  5. Map Modules

Javascript SDK

Routing Module

Our Routing module allows you to create and display custom transportation routes in your Interactive Map and/or Interactive Map App instances in the Javascript SDK. Additionally, critical weather-related information specific to each route can be rendered both along the entire route and at critical waypoints, such as departure and destination locations.

Routing Module

Getting Started

To start using the Routing module, you’d set up your project as you would with any of our other built-in modules. Therefore, you’ll need to follow the module setup instructions for Interactive Map or Interactive Map App depending on which mapping component you are using in your project from our SDK.

For instance, you’re initial setup for an Interactive Map App instance would be as follows:

aeris.apps().then((apps) => {

    const app = new apps.InteractiveMapApp('#app', {
        // map app config
    });

    aeris.modules().then((modules) => {
        // Add the built-in Routing module
        app.modules.add(modules.Routing, null, {
            // configuration options...
        });
    });

});

You’ll need to provide additional configuration options when adding an instance of the Routing module to your application. Include these options as the third argument to the app.modules.add method as demonstrated in the code above:

Option Type Description
id string The route group identifier.
title string The title of the route group (only used when multiple routes are defined with this group).
weatherTypes string[] Array of weather type codes to include in the weather options for the layer group’s control. Default value is all codes, e.g. ['temps', 'winds', 'windgust', 'weather', 'alerts']. The active weather type determine which weather data is plotted along the route.
url string or Function The URL string or a callback function that receives the currently active route and returns the URL path to use when requesting route data from a remote source.
service object An object that defines the third-party directions API service to use to generate the route from.
service.type mapbox or google The directions service to use. Only Mapbox and Google Maps are currently supported.
service.accessKey string The access key to use with the third-party directions API. Refer to the desired service’s documentation for more information.
routes object[] An array of route configuration objects defining the routes to display within this group. See the Configuring Routes section below.
refresh number Route update interval in seconds. Setting this value to 0 will disable auto-updating of route data (default). Only the active routes on the map will be updated at this interval.
onRouteData Function A callback function called when remote route data has been loaded and configured but before rendering.
onWeatherData Function A callback function called when weather data for the active route has loaded but before rendering.

For example, the following configuration would configure the Routing module instance to load routes from a remote URL which will then return the proper configurations for each requested route as required by the module:

app.modules.add(modules.Routing, {}, {
    id: 'my-remote-routes',
    title: 'My Routes',
    dataType: 'weather',
    url: (value) => {
        return 'https://mydomain.com/routes/data/route.json?id=' + value
    },
    routes: [{
        id: 'remote-route-1',
        title: 'Route 1'
    },{
        id: 'remote-route-2',
        title: 'Route 2'
    },{
        id: 'remote-route-3',
        title: 'Route 3'
    }]
});

Once you have this initial setup completed, you can now start configuring and adding your custom routes to your application.

Configuring Routes

There are several methods you can use for adding routes to your mapping application:

Configuration

Routes will need to be configured in a specific way to use them with the Routing module. The following are the available options when configuring a route:

Option Type Description
id string The route identifier.
title string The route name.
points string[] or ICoordiate[] An array of route waypoints as strings or ICoordiate objects that define the start, end and intermediate locations for the route. This is only used when using a third-party directions API and have configured your Routing module’s service options. These values can be coordinates or place names as strings (47.25288,-122.44429, or austin,tx) or coordinate objects ({ lat: 47.25288, lon: -122.44429 }.
data object An object containing all route-related information and details. This
data.departure object Information about the departure route point. See Route Point below.
data.destination object Information about the destination route point. See Route Point below.
data.current object Information about the asset’s current position along the route when available. See Route Point below.
data.feature object GeoJSON object providing the route path for the map. This should typically be a single LineString type. This value is required when configuring your routes statically or using a remote data source, but not when using a third-party directions service.
data.waypoints object[] An array of GeoJSON objects specifying a series of waypoints along the route to plot on the map. Each waypoint in the array should be a Point feature.
data.durationSeconds number Total travel time for the route in seconds.
data.distanceMeters number Total travel distance for the route in meters.
data.asset object Additional information about the asset associated with the route when available, such as truck and/or payload information and current status.
data.asset.title string Asset or payload title.
data.asset.description string Asset or payload description.
data.asset.imageUrl string URL path to an image to display alongside the asset in the info panel.
data.asset.loc ICoordinate Current coordinate of the asset.
data.asset.status.label string Current status of the asset or trip.
data.asset.status.color string Status badge color to use for the status (e.g. #ffcc00, etc).

Route Point

A route point provides the necessary configuration needed for a route’s departure, destination and current information:

Option Type Description
id string Route point identifier.
title string Custom name to display for the point instead of the default value. This could be the name of a business or facility.
place string Custom place name to display for the point, such as city or address.
loc ICoordinate Point coordinate. This value should only be provided for waypoints and not the departure or destination points as those will be automatically set based on the route path.
timestamp number Epoch timestamp specifying the expected time the asset will depart from or arrive at the point, in milliseconds. Provide this value with the departure point to display the appropriate departure and arrival times and to fetch the weather data corresponding to the correct travel times.
markerStyle MarkerStyle The custom marker style to use when rendering this point on the map. See Styling Point Data for more details.

Configuring Routes Using Static Data

Static routes are configured as part of your code rather than being requested from a remote source or service. Therefore, you would need to provide all required route information when adding the Routing module instance to your mapping application.

The following is an example of setting up a route group using a static configuration:

app.modules.add(modules.Routing, {}, {
    id: 'custom-routes',
    title: 'My Routes',
    dataType: 'weather',
    routes: [{
        id: 'route-1',
        title: 'Route 1',
        data: {
            distanceMeters: 567,
            durationSeconds: 720.65,
            departure: {
                timestamp: Date.now() + 3600 * 1 * 1000
            },
            feature: {
                type: 'Feature',
                properties: {},
                geometry: {
                    type: 'LineString',
                    coordinates: [
                        [-122.48369693756104, 37.83381888486939],
                        [-122.48348236083984, 37.83317489144141],
                        [-122.48339653015138, 37.83270036637107],
                        [-122.48356819152832, 37.832056363179625],
                        [-122.48404026031496, 37.83114119107971],
                        [-122.48404026031496, 37.83049717427869],
                        [-122.48348236083984, 37.829920943955045],
                        [-122.48356819152832, 37.82954808664175],
                        [-122.48507022857666, 37.82944639795659],
                        [-122.48610019683838, 37.82880236636284],
                        [-122.48695850372314, 37.82931081282506],
                        [-122.48700141906738, 37.83080223556934],
                        [-122.48751640319824, 37.83168351665737],
                        [-122.48803138732912, 37.832158048267786],
                        [-122.48888969421387, 37.83297152392784],
                        [-122.48987674713133, 37.83263257682617],
                        [-122.49043464660643, 37.832937629287755],
                        [-122.49125003814696, 37.832429207817725],
                        [-122.49163627624512, 37.832564787218985],
                        [-122.49223709106445, 37.83337825839438],
                        [-122.49378204345702, 37.83368330777276]
                    ]
                }
            }
        }
    }, {
        id: 'route-2',
        title: 'Route 2',
        data: {
            distanceMeters: 1217617.25,
            durationSeconds: 42455.547,
            departure: {
                timestamp: Date.now() + 3600 * 12 * 1000
            },
            feature: {
                type: 'Feature',
                properties: {},
                geometry: {
                    type: 'LineString',
                    coordinates: [
                        [-87.624337, 41.875601],
                        [-87.624295, 41.87315],
                        [-87.617309, 41.873239],
                        [-87.614708, 41.853136],
                        [-87.626818, 41.84732],
                        [-87.631319, 41.842783],
                        [-87.63127, 41.791507],
                        [-87.631086, 41.778384],
                        [-87.517719, 41.661053],
                        [-87.305584, 41.59601],
                        [-87.30305, 41.592284],
                        [-87.307316, 41.593325],
                        [-87.270693, 41.008105],
                        [-87.162077, 40.815043],
                        [-86.346339, 39.93931],
                        [-86.144869, 39.782797],
                        [-84.201106, 39.864832],
                        [-84.205476, 39.751259],
                        [-84.205954, 39.749929],
                        [-83.98331, 39.694881],
                        [-83.645282, 39.64486],
                        [-82.94155, 39.323044],
                        [-82.427055, 38.886531],
                        [-82.160201, 38.838176],
                        [-81.977188, 38.739733],
                        [-82.016321, 38.577214],
                        [-81.905277, 38.459683],
                        [-81.554075, 38.316506],
                        [-81.568826, 38.243551],
                        [-81.259465, 37.958022],
                        [-81.043262, 37.376647],
                        [-81.139284, 37.045605],
                        [-81.050689, 36.946732],
                        [-80.929019, 36.948117],
                        [-80.709921, 36.674281],
                        [-80.742424, 36.498388],
                        [-80.856936, 35.57034],
                        [-80.873398, 35.489036],
                        [-80.863924, 35.423914],
                        [-80.850358, 35.38767],
                        [-80.848495, 35.331112],
                        [-80.850872, 35.289154],
                        [-80.844655, 35.250661],
                        [-80.838081, 35.234964],
                        [-80.835541, 35.232534],
                        [-80.843154, 35.22715]
                    ]
                }
            }
        }
    }]
});

Configuring Routes Using Remote Data

Using remote routes allow you to define your routes when adding the Routing module instance to your application but use your own server or backend service to provide the relevant route information. This is especially useful if you are including route asset’s current position and status in your application which may need frequent updates.

The following is an example of setting up a route group configuring to request route data from a remote service. A callback function is used for the url option so that the url can be adjusted based on the currently selected route:

app.modules.add(modules.Routing, {}, {
    id: 'custom-routes',
    title: 'My Routes',
    dataType: 'weather',
    url: (value) => {
        return `./data/${value}.json`
    },
    routes: [{
        id: 'route-1',
        title: 'Route 1'
    },{
        id: 'route-2',
        title: 'Route 2'
    },{
        id: 'route-3',
        title: 'Route 3'
    }]
});

Then the remote data source would return the required route data as JSON for each route when selected:

{
    "distanceMeters": 1217617.25, 
    "durationSeconds": 42455.547, 
    "departure": {
        "title": "Distribution Warehouse",
        "place": "Chicago, IL"
    },
    "destination": {
        "title": "Warehouse #3245",
        "place": "Charlotte, NC"
    },
    "asset": {
        "title": "Asset #3487",
        "description": "This is just some random information about the asset or its payload.",
        "imageUrl": "/routes/images/atego-3487.jpg",
        "status": {
            "label": "In-Transit",
            "color": "#f7c619"
        }
    },
    "feature": {
        "type": "Feature",
        "properties": {},
        "geometry": {
            "type": "LineString",
            "coordinates": [
                [-87.624337, 41.875601],
                [-87.624295, 41.87315],
                [-87.617309, 41.873239],
                [-87.614708, 41.853136],
                [-87.626818, 41.84732],
                [-87.631319, 41.842783],
                [-87.63127, 41.791507],
                [-87.631086, 41.778384],
                [-87.517719, 41.661053],
                [-87.305584, 41.59601],
                [-87.30305, 41.592284],
                [-87.307316, 41.593325],
                [-87.270693, 41.008105],
                [-87.162077, 40.815043],
                [-86.346339, 39.93931],
                [-86.144869, 39.782797],
                [-84.201106, 39.864832],
                [-84.205476, 39.751259],
                [-84.205954, 39.749929],
                [-83.98331, 39.694881],
                [-83.645282, 39.64486],
                [-82.94155, 39.323044],
                [-82.427055, 38.886531],
                [-82.160201, 38.838176],
                [-81.977188, 38.739733],
                [-82.016321, 38.577214],
                [-81.905277, 38.459683],
                [-81.554075, 38.316506],
                [-81.568826, 38.243551],
                [-81.259465, 37.958022],
                [-81.043262, 37.376647],
                [-81.139284, 37.045605],
                [-81.050689, 36.946732],
                [-80.929019, 36.948117],
                [-80.709921, 36.674281],
                [-80.742424, 36.498388],
                [-80.856936, 35.57034],
                [-80.873398, 35.489036],
                [-80.863924, 35.423914],
                [-80.850358, 35.38767],
                [-80.848495, 35.331112],
                [-80.850872, 35.289154],
                [-80.844655, 35.250661],
                [-80.838081, 35.234964],
                [-80.835541, 35.232534],
                [-80.843154, 35.22715]
            ]
        }
    }
}

Configuring Routes Using a Third-Party Directions API

Configure your routes to use a third-party directions API, such as Mapbox or Google Maps, if you need to have your route paths generated for you. You just need to provide the start and end locations at a minimum and optionally any intermediate locations along the route. The Routing module will then use this service to generate your route path before rendering it to the map.

The following example will use the Mapbox Directions API to request the route’s path that is rendered to the map. This route information will also be used to request relevant weather information along the route when active:

app.modules.add(modules.Routing, {}, {
    id: 'custom-routes',
    title: 'My Routes',
    dataType: 'weather',
    service: {
        type: 'mapbox',
        accessKey: 'MAPBOX_ACCESS_KEY'
    },
    routes: routes: [{
        id: 'route-1',
        title: 'Route 1',
        points: [
            'vancouver,bc,ca',
            'whistler,bc,ca',
            'kamloops,bc,ca'
        ]
    },{
        id: 'route-2',
        title: 'Route 2',
        points: [
            { lat: 47.60621, lon: -122.33207 },
            { lat: 48.643442, lon: -120.211281 },
            { lat: 49.24966, lon: -123.11934 }
        ]
    },{
        id: 'route-3',
        title: 'Route 3',
        points: [
            'austin,tx',
            'minneapolis,mn'
        ]
    }]
});

The primary difference between relying on a third-party directions API to generate the routes versus using a remote server is that you must provide any additional route-related information when you instantiate your Routing module instances.

If you need to display real-time asset location information, then we recommend setting up a remote service that is used for requesting route information from.

Last modified: February 09, 2023