Route Bookmarks

_{Last updated: September 14, 2026 | 5 minutes read}

This guide explains how to store, manage, and retrieve route collections as bookmarks between application sessions.

Create a bookmarks collection

Create a new bookmarks collection using the RouteBookmarks.create method with a unique name:

final bookmarks = RouteBookmarks.create('my_trips');

If a collection with the same name exists, it opens the existing collection.

Access the file path using the filePath property:

String path = bookmarks.filePath;

Add routes

Add a route to the collection using the add method. Provide a unique name and waypoints list as List<Landmark>. Optionally include route preferences and specify whether to overwrite existing routes.

final GemError err = bookmarks.add(
  'Home to Office',
  [homeLandmark, officeLandmark],
  preferences: myPreferences,
  overwrite: false,
);

if (err != GemError.success) {
    showSnackbar('Could not store the route: $err');
}

Parameters:

• name - Unique route name
• waypoints - List of landmarks defining the route
• preferences - Optional route preferences
• overwrite - Replace existing route with same name (default: false)

add returns a GemError describing the outcome:

Value	Significance
GemError.success	The route was stored.
GemError.exist	name is already used by another route and overwrite is false.
GemError.invalidInput	name is empty.
GemError.general	The route could not be stored.

Generate a unique route name

Use RouteBookmarks.getBaseUniqueName to derive a name from the waypoint coordinates. The name is unique for a given sequence of coordinates, which makes it a convenient default identifier when storing a route:

final name = RouteBookmarks.getBaseUniqueName([homeLandmark, officeLandmark]);
bookmarks.add(name, [homeLandmark, officeLandmark]); // check the result as above

The method is static, so it does not require an existing collection, and it does not check whether a route with that name is already stored. It returns an empty string when the waypoint list is empty.

info

The generated name is an encoded token derived from the coordinates, not a human-readable label. Use it as a stable identifier and keep a separate display name if the collection is shown in the UI.

Import routes from files

Import multiple routes from a file using addTrips. Returns the number of imported routes or GemError.invalidInput.code on failure.

final int count = bookmarks.addTrips('/path/to/bookmarks_file');
if (count == GemError.invalidInput.code){
    showSnackbar('Invalid file path provided for import.');
} else {
    showSnackbar('$count trips imported successfully.');
}

Export routes to files

Export a specific route to a file using exportToFile with the route index and destination path.

final result = bookmarks.exportToFile(0, '/path/to/exported_route');
showSnackbar('Export completed with result: $result');

Return values:

• GemError.success - Export successful
• GemError.notFound - Route does not exist
• GemError.io - File cannot be created

Access route details

Get the number of routes in the collection using the size property:

final int count = bookmarks.size;

Get details of a specific route by index:

String? name = bookmarks.getName(0);
List<Landmark>? waypoints = bookmarks.getWaypoints(0);
RoutePreferences? prefs = bookmarks.getPreferences(0);
DateTime? timestamp = bookmarks.getTimestamp(0);

info

Methods return null if the index is out of bounds or data is unavailable. The getTimestamp method returns when the route was added or modified.

Find the index of a route by name using the find method:

final int index = bookmarks.find('Home to Office');
if (index >= 0) {
    showSnackbar('Route found at index $index.');
} else {
    showSnackbar('Error finding route: $index');
}

Return values:

• Route index if found (positive value)
• GemError.notFound.code if not found

Sort bookmarks

Change the sort order using the sortOrder property:

Available sort orders:

• RouteBookmarksSortOrder.sortByDate (default) - Most recent first
• RouteBookmarksSortOrder.sortByName - Alphabetical order

Configure auto-delete mode

Enable or disable auto-delete mode using the autoDeleteMode property. When enabled, the bookmarks database is deleted when the object is destroyed.

Update routes

Update an existing route using the update method with the route index and new details:

final GemError err = bookmarks.update(
    0,
    name: 'New Name',
    waypoints: [newStart, newEnd],
    preferences: newPrefs,
);

if (err != GemError.success) {
    showSnackbar('Could not update the route: $err');
}

info

The update method only modifies provided fields, leaving others unchanged. An empty waypoints list also leaves the waypoints unchanged.

update returns a GemError describing the outcome:

Value	Significance
GemError.success	The route was updated.
GemError.exist	name is already used by another route.
GemError.notFound	index does not identify a route.
GemError.invalidInput	name is empty.
GemError.general	The route could not be stored.

Remove routes

Remove a route by index using the remove method:

final GemError err = bookmarks.remove(0);

if (err != GemError.success) {
    showSnackbar('Could not remove the route: $err');
}

remove returns GemError.success on success, or GemError.general when the index does not identify a route or the route could not be deleted.

Clear all routes from the collection using the clear method:

bookmarks.clear();