Routing Module

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

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:

OptionTypeDescription
idstringThe route group identifier.
titlestringThe title of the route group (only used when multiple routes are defined with this group).
weatherTypesstring[]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.
urlstring or FunctionThe 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.
serviceobjectAn object that defines the third-party directions API service to use to generate the route from.
service.typemapbox or googleThe directions service to use. Only Mapbox (opens in a new tab) and Google Maps (opens in a new tab) are currently supported.
service.accessKeystringThe access key to use with the third-party directions API. Refer to the desired service's documentation for more information.
routesobject[]An array of route configuration objects defining the routes to display within this group. See the Configuring Routes section below.
refreshnumberRoute 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.
onRouteDataFunctionA callback function called when remote route data has been loaded and configured but before rendering.
onWeatherDataFunctionA 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:

OptionTypeDescription
idstringThe route identifier.
titlestringThe route name.
pointsstring[] 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 }.
dataobjectAn object containing all route-related information and details. This
data.departureobjectInformation about the departure route point. See Route Point below.
data.destinationobjectInformation about the destination route point. See Route Point below.
data.currentobjectInformation about the asset's current position along the route when available. See Route Point below.
data.featureobjectGeoJSON 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.waypointsobject[]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.durationSecondsnumberTotal travel time for the route in seconds.
data.distanceMetersnumberTotal travel distance for the route in meters.
data.assetobjectAdditional information about the asset associated with the route when available, such as truck and/or payload information and current status.
data.asset.titlestringAsset or payload title.
data.asset.descriptionstringAsset or payload description.
data.asset.imageUrlstringURL path to an image to display alongside the asset in the info panel.
data.asset.locICoordinateCurrent coordinate of the asset.
data.asset.status.labelstringCurrent status of the asset or trip.
data.asset.status.colorstringStatus 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:

OptionTypeDescription
idstringRoute point identifier.
titlestringCustom name to display for the point instead of the default value. This could be the name of a business or facility.
placestringCustom place name to display for the point, such as city or address.
locICoordinatePoint 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.
timestampnumberEpoch 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.
markerStyleMarkerStyleThe 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.