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 (opens in a new tab) and Google Maps (opens in a new tab) 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:

Provide static route path coordinates and related information alongside your application
Provide a remote URL from which route path coordinates and related information will be requested from
Provide waypoint locations as a series of individual coordinates or place names and use a third-party directions API service, such as Mapbox or Google Maps, to automatically generate the route for you

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 (opens in a new tab) or Google Maps (opens in a new tab), 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 (opens in a new tab) 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.

Configuring Data Sources Map View