Routing

MapLayr provides powerful routing capabilities that allow you to calculate paths between locations and display them on your map. This guide explains how to calculate routes and use reactive routing features.

Basic Route Calculation

To calculate a route between two points, use the calculateRoute method of the Map:

const route = await map.calculateRoute(
  new maplayr.Coordinates(36.69200, -6.41178), // origin
  new maplayr.Coordinates(36.69541, -6.41551)  // destination
);

console.log(`Route distance: ${route.distance} metres`);

// Display the route on the map
const shape = new maplayr.Shape(route.path);
shape.strokeColor = "#007aff";
shape.strokeWidth = 4;
mapView.addShape(shape);
Copy

Route Properties

Each route object contains:

Property	Description
path	A Path object containing the geographic route information, which can be supplied to a Shape
distance	The total route distance in metres

Multiple Destinations

You can calculate routes to the closest of several destinations:

const destinations = [
  new maplayr.Coordinates(36.69200, -6.41178),
  new maplayr.Coordinates(36.69541, -6.41551),
  new maplayr.Coordinates(36.69878, -6.41632)
];

const route = await map.calculateRoute(
  userLocation,
  destinations // The route will go to whichever destination is closest via the paths
);
Copy

Any iterable value returning Coordinates can be provided.

Route Options

Customise route calculation with optional parameters:

const route = await map.calculateRoute(
  origin,
  destination,
  {
    avoidFlags: [ "reducedAccessibility" ] // Avoid paths with these flags
  }
);
Copy

Available route options:

Option	Description
avoidFlags	Array or Set of string flags to avoid when calculating routes

Reactive Routes

Reactive routes automatically recalculate when the origin location changes by using a PositionProvider. This is particularly useful when combined with user location markers:

// Create a user location marker which uses the Geolocation API to update
const userLocationMarker = new maplayr.UserLocationMarker();
mapView.addUserLocationMarker(userLocationMarker);

const destination = new maplayr.Coordinates(36.69541, -6.41551);

// Create a reactive route that updates when the user moves
const reactiveRoute = map.createReactiveRoute(
  userLocationMarker,
  destination
);

// Display the route with two shapes for a nice visual effect
const outerShape = new maplayr.Shape(reactiveRoute);
outerShape.strokeColor = "#0066cc";
outerShape.strokeWidth = 8;
mapView.addShape(outerShape);

const innerShape = new maplayr.Shape(reactiveRoute);
innerShape.strokeColor = "#3399ff";
innerShape.strokeWidth = 5;
mapView.addShape(innerShape);
Copy

Working with Shape Objects

Routes are displayed using Shape objects that can be styled and added to the map:

const shape = new maplayr.Shape(route.path);

// Customise the route appearance
shape.strokeColor = "#ff6b35";
shape.strokeWidth = 6;

// Add to map
mapView.addShape(shape);
Copy

Multiple shapes can use the same path or reactive route, allowing you to create visual effects like outlined paths.

Error Handling

Handle routing errors gracefully:

try {
  const route = await map.calculateRoute(origin, destination);
  // Use the route
} catch (error) {
  console.error("Failed to calculate route:", error);
  // Handle the error - perhaps show an alternative or error message
}
Copy

Common routing errors include:

• No route available between the specified points
• Routing data failed to load
• Invalid coordinates provided

Rather than throwing an error, reactive routes will simply set their currentRoute to null.

Best Practices

• Use reactive routes when the origin position changes frequently (e.g., user location)
• Use regular route calculation for static routes or one-time calculations
• Create visual depth with multiple shapes using different colors and stroke widths
• Handle routing errors to provide a good user experience