# Route Bookmarks
Last updated:
October 18, 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-bookmarks-collection "Direct link to Create a bookmarks collection")
Create a new bookmarks collection using the `RouteBookmarks.create` method with a unique name:
```dart
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:
```dart
String path = bookmarks.filePath;
```
## Add routes[](#add-routes "Direct link to Add routes")
Add a route to the collection using the `add` method. Provide a unique name and waypoints list as `List`. Optionally include route preferences and specify whether to overwrite existing routes.
```dart
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[](#generate-a-unique-route-name "Direct link to 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:
```dart
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-routes-from-files "Direct link to Import routes from files")
Import multiple routes from a file using `addTrips`. Returns the number of imported routes or `GemError.invalidInput.code` on failure.
```dart
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-routes-to-files "Direct link to Export routes to files")
Export a specific route to a file using `exportToFile` with the route index and destination path.
```dart
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[](#access-route-details "Direct link to Access route details")
Get the number of routes in the collection using the `size` property:
```dart
final int count = bookmarks.size;
```
Get details of a specific route by index:
```dart
String? name = bookmarks.getName(0);
List? 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:
```dart
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[](#sort-bookmarks "Direct link to 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[](#configure-auto-delete-mode "Direct link to 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-routes "Direct link to Update routes")
Update an existing route using the `update` method with the route index and new details:
```dart
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-routes "Direct link to Remove routes")
Remove a route by index using the `remove` method:
```dart
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:
```dart
bookmarks.clear();
```