Routing

Route helpers let you manage saved multi-stop routes inside a map control. A route can include a name, waypoint list, route color, transport mode, waypoint optimization, and avoid preferences.

Why you'd use these helpers

• Save repeatable route plans for dispatch, inspections, or service runs.
• Update a route definition when stops or constraints change.
• Quickly navigate the map to a selected route context.
• Keep route behavior predictable by explicitly setting transport, optimize, and avoid options.

Usage pattern

const control = globalThis.MaptaskrControlManager.getControl(controlId);

All examples below assume you already have a valid control reference.

Types

export interface RouteWaypoint {
  name: string;
  lng: number;
  lat: number;
}

export interface RouteAvoidOptions {
  motorways?: boolean;
  tollRoads?: boolean;
  ferries?: boolean;
}

export interface CustomRoute {
  routeId?: string;
  routeName: string;
  waypoints: RouteWaypoint[];
  routeColor?: string;
  transportationMethod?: 'car' | 'truck' | 'walk';
  optimize?: boolean;
  avoid?: RouteAvoidOptions;
}

API reference

getRoutes

List all currently available routes for the current map context.

Parameters: None

Returns: CustomRoute[]

Usage:

const routes = control.getRoutes();

routes.forEach((route) => {
  console.log(`${route.routeName} (${route.routeId})`, route.waypoints.length);
});

Example response:

[
  {
    routeId: 'eb00c94d-1459-41ad-95c6-d112967717e6',
    routeName: 'New Route 2',
    transportationMethod: 'car',
    routeColor: 'rgb(0, 230, 52)',
    optimize: false,
    avoid: { motorways: false, tollRoads: false, ferries: true },
    waypoints: [
      { name: 'test3', lng: 115.9086, lat: -31.9753 },
      { name: 'Test Account 1', lng: 115.83754, lat: -32.11547 },
    ],
  },
];

info

Some optional fields may be omitted if they were not set when the route was created.

addOrUpdateRoute

Create a new route or update an existing route by ID.

When updating, pass the existing routeId and the full route payload you want saved.

Parameters:

Field	Type	Required	Description
routeId	string	No	If provided, updates that route. If omitted/empty, creates a new route.
routeName	string	Yes	Display name for the route.
waypoints	RouteWaypoint[]	Yes	Ordered waypoint list (maximum 150).
routeColor	string	No	Route color, for example rgb(0, 230, 52).
transportationMethod	'car' | 'truck' | 'walk'	No	Routing mode to use.
optimize	boolean	No	Enables/disables waypoint optimization.
avoid	RouteAvoidOptions	No	Optional avoid flags: motorways, tollRoads, ferries.

Returns: Promise<CustomRoute>

Usage - create a route:

const waypoints = [
  { name: 'Depot', lng: 115.9086, lat: -31.9753 },
  { name: 'Test Account 1', lng: 115.83754, lat: -32.11547 },
];

 await control.addOrUpdateRoute({
  routeName: 'Adding a new route',
  waypoints,
  routeColor: 'rgb(0, 230, 52)',
  transportationMethod: 'car',
  optimize: false,
  avoid: {
    motorways: false,
    tollRoads: false,
    ferries: true,
  },
});

Usage - update an existing route:

const routes = control.getRoutes();
const existing = routes.find((r) => r.routeName === 'Adding a new route');

if (existing?.routeId) {
  const updated = await control.addOrUpdateRoute({
    routeId: existing.routeId,
    routeName: 'Adding a new route (Updated)',
    waypoints: existing.waypoints,
    routeColor: existing.routeColor,
    transportationMethod: existing.transportationMethod,
    optimize: existing.optimize,
    avoid: existing.avoid,
  });

}

---

deleteRoute

Deletes a single route by its route ID.

Parameters:

Field	Type	Required	Description
routeId	string	Yes	Route ID of the route to remove.

Returns: Promise<void>

Usage:

const routes = control.getRoutes();

const routeId = routes[0].routeId;

await control.deleteRoute(routeId);

---

navigateToRoute

Navigate the map view to a saved route by ID.

Parameters:

Field	Type	Required	Description
routeId	string	Yes	Route ID to navigate to.

Returns: Promise<void>

Usage:

const routes = control.getRoutes();
const target = routes.find((r) => r.routeName === 'Adding a new route (Updated)');

if (target?.routeId) {
  await control.navigateToRoute(target.routeId);
  console.log('Navigated to route:', target.routeName);
}

Common workflows

Save or refresh a daily dispatch route

const routes = control.getRoutes();
const existing = routes.find((r) => r.routeName === 'Daily Dispatch');

const saved = await control.addOrUpdateRoute({
  routeId: existing?.routeId,
  routeName: 'Daily Dispatch',
  waypoints: [
    { name: 'Depot', lng: 115.9086, lat: -31.9753 },
    { name: 'Client A', lng: 115.83754, lat: -32.11547 },
    { name: 'Client B', lng: 115.7921, lat: -32.0522 },
  ],
  transportationMethod: 'truck',
  optimize: true,
  avoid: { tollRoads: true },
});

console.log('Saved route:', saved.routeId);

Navigate to route by name

async function navigateRouteByName(name: string) {
  const routes = control.getRoutes();
  const match = routes.find((r) => r.routeName === name);

  if (!match?.routeId) {
    console.warn(`Route not found: ${name}`);
    return;
  }

  await control.navigateToRoute(match.routeId);
}

await navigateRouteByName('Daily Dispatch');

Delete a temporary route

const routes = control.getRoutes();
const temp = routes.find((r) => r.routeName === 'Temporary Route');

if (temp?.routeId) {
  await control.deleteRoute(temp.routeId);
  console.log('Deleted route:', temp.routeName);
}

Best practices

• Persist the returned routeId after create so updates and navigation are reliable.
• Keep waypoint order explicit unless optimize is intentionally enabled.
• Set transportationMethod and avoid options deliberately to prevent unexpected route behavior.
• Use clear route naming conventions (for example team, shift, or workflow prefixes).
• Wrap async route operations in your own error handling when wiring them to UI actions or automations.