Wayfarer

Import and export

Bring location history into Wayfarer, save a copy of your records or move Trip plans between tools. Location imports add recorded history; Trip imports add plans. Choose the matching workflow rather than treating every map file as the same kind of data.

Import location history

1. Open Location imports from your name menu and choose Upload New File.
2. Select the file and its File Type. Choose the actual format, not merely a different filename extension.
3. Decide whether to continue filling missing addresses after import. This is optional and requires a configured personal provider.
4. Choose Upload File, then review progress on the imports page.
5. When processing finishes, open Timeline or All Locations and check a few dates, coordinates and details from the file.

Large files process in the background, so you can leave the page and return later. Your administrator controls the upload-size limit and whether uploads are enabled. Check the displayed limit before uploading a large export.

Supplied valid Activity names reuse an existing Activity or automatically create a missing entry. Activities form a shared catalog: names you import become visible to all authenticated users. Your locations remain private under their existing visibility settings. Only newly accepted locations can create catalog entries; duplicates keep their original classification. Source numeric Activity IDs and descriptions do not change the destination catalog.

Matching ignores capitalization, normalizes Unicode and trims surrounding whitespace. Interior whitespace remains significant, and different names such as Walking and Hiking stay separate. Missing or blank names are optional. Invalid values leave the location without an Activity and add a visible Invalid Activity warning count to the import history. The count remains after refresh or restart; correct those accepted locations through ordinary location editing.

Choose a supported format

Generic GeoJSON is not supported for new location-history uploads. Google My Maps and Wayfarer Trip KML belong in the Trip importer, not this history workflow.

All five history formats require finite latitude in [-90, 90] and longitude in [-180, 180], including the endpoints. (0,0) is valid. Points with missing, malformed, non-finite or out-of-range coordinates are skipped without changing the valid records. Malformed GeoJSON syntax can still fail the import.

For CSV, the required columns are Latitude, Longitude and TimestampUtc. Use decimal latitude/longitude coordinates and timestamps with an explicit UTC or timezone offset. For example:

Latitude,Longitude,TimestampUtc
37.9838,23.7275,2026-06-01T08:00:00Z

A Wayfarer CSV export is a useful template when preparing your own file. Preserve quoted notes and address text; do not split fields on commas by hand.

In CSV and Wayfarer GeoJSON, a missing, null, empty or whitespace-only IdempotencyKey remains keyless. Valid UUID spellings, including braces, retain their identity. A supplied nonblank malformed UUID fails the entire file. GeoJSON UUID values must be strings or null; numbers, booleans, arrays and objects fail. Validation reads the complete file before adding locations and checks identities even on records whose coordinates, timestamps or geometry are skipped.

Follow progress and control an import

The imports list shows status, processed records, the last processed record and errors. Records carrying portable identifiers are recognized by those identifiers; other records are checked for matching times and coordinates within a small tolerance. An import can finish with fewer new records than its source contains because of duplicates, invalid rows or retained deletion decisions.

Skipped invalid points do not contribute to the total or last processed record; duplicates and deleted records still do. Deleted records skipped counts records suppressed by your prior deletion separately from duplicates, including repeated copies of a deleted UUID. Counters and processed progress commit together and survive stop/restart. Completed means the file was processed; it is not a receipt that every source record was stored. Repeating an import does not restore filtered invalid points or deliberately deleted UUIDs.

The deletion-count capture renders the production import view with synthetic records for illustration.

Deleting a UUID-bearing Location through Web or an authorized device retains only its account and UUID as suppression metadata for your account’s lifetime. Old CSV and Wayfarer GeoJSON exports cannot restore it, even after Delete all Locations. Suppressed records create no Activity or enrichment work. Another account’s UUIDs remain independent. No restore override is provided.

Coverage begins when this mechanism is deployed. Already-deleted records cannot be reconstructed from absent rows, and keyless history cannot prove exact UUID deletion. Complete account erasure removes the markers; ordinary Location deletion does not. An older database backup cannot recover deletion intent missing from that backup. See the API identity contract for deleted, present and unknown discovery and successor-client behavior.

For records without a UUID, matching is approximate (within one second and ten metres); concurrent live uploads and imports, or capture timestamps that differ from server receipt timestamps, can still create duplicates.

• Stop pauses processing. Already imported locations remain in your history. Wait for Stopping to become Stopped before restarting it.
• Start resumes a stopped or failed import.
• Delete removes the import entry and uploaded file. It does not delete the locations already added to your Timeline.

If an import fails, inspect the reported error and progress before retrying; some records may already be saved. Confirm the format, CSV headers and timestamps. If progress appears stuck, refresh once and contact your administrator if it persists. If a saved checkpoint no longer matches the parsed record count, Start fails with an instruction to upload the file as a new import. This can affect older imports whose invalid coordinates are now skipped. The failed import retains its saved progress and locations; restarting it again cannot repair the checkpoint. A new import can recover remaining valid records without overwriting existing UUID-bearing locations or owner edits. Matching records without a UUID remains approximate. Previously stored invalid points are not automatically repaired.

For an invalid UUID or multiple zero UUIDs, correct the identities in a copy and upload it as a new import. Start on the unchanged failed upload fails again. Failure preserves earlier saved totals, checkpoints, counters and locations; a fresh import adds no locations from the invalid file. Keep the staged upload unchanged and retain the original as a reference.

If Activity reconciliation fails, the current batch is rolled back together with its classifications and progress. Earlier committed batches remain saved. Start resumes from that checkpoint once catalog contention or the database problem has cleared; replay does not overwrite existing classifications. If an uploaded file cannot be removed, ask the administrator to investigate rather than assuming that deleting the row removed every copy.

Optionally fill missing addresses

The upload option Continue filling missing addresses after the import completes starts a separate enrichment task. You can also use Start under Missing-address enrichment later.

Import completion means history processing has finished, not that every address has been found. Enrichment can take days for a large history and can pause when a provider is unavailable or its usage limit is reached. Your imported locations remain available throughout.

Cancelling enrichment does not cancel or delete an import. Deleting an import entry does not stop enrichment or erase locations. The provider guide owns the enrichment controls and address-repair choices.

Export location history

Open All Locations and choose Export Location Data. Pick the format for the tool you will use:

All four native history formats preserve the current catalog Activity name and the independent LocationType value. Importing into another Wayfarer instance reuses or creates its Activity by name; source numeric Activity IDs have no authority. Renaming a catalog Activity changes the name in subsequent exports. Missing or empty LocationType values import as null; other text retains its case and whitespace. Older files without this field remain supported. GPX and KML retain these details in Wayfarer extensions and ExtendedData respectively; other tools may remove them. LocationType text containing characters XML cannot represent uses a reversible Wayfarer field in GPX/KML; native imports restore the original text, while other tools may ignore this field. These two formats remain keyless.

Owner CSV and Wayfarer GeoJSON exports preserve each record’s stored UUID as IdempotencyKey. Records without a UUID remain keyless; export does not generate one. Reimporting a UUID already present in your account skips that record without overwriting edits. Different UUIDs remain distinct even at the same time and position. Another account can import the same UUID independently; numeric Id values belong to the destination database and are not portable identity.

For historical compatibility, each CSV or Wayfarer GeoJSON file may contain at most one all-zero UUID (00000000-0000-0000-0000-000000000000). It stays a real key: an account without zero imports it unchanged, including a transfer from another account; replay in an account already holding zero skips it and preserves owner edits. A second zero occurrence fails the entire file, even for identical or otherwise skipped records, or when the account already holds zero.

Zero alone cannot identify whether a record is a replay or a different capture. A distinct capture supplied as the sole zero in a later separate file can still match the account’s existing zero and count as a skipped duplicate. Give distinct new captures distinct nonzero UUIDs. Existing stored keys are never rekeyed.

Keep an untouched export when using another tool to transform the data. These files can include precise positions, times, notes and device metadata. Store and share them as private history unless you intend otherwise. History transfer is not a database backup or a cross-installation synchronization system: it does not reconcile edits or deletions between installations or recreate a pending queue.

Move your phone Timeline

For everyday phone-history portability, open Mobile’s Settings > Timeline Data. Choose Export CSV for spreadsheets or Export GeoJSON for map/GIS tools and another phone. These exports contain the history retained locally. Use Import Timeline to read a CSV or Wayfarer GeoJSON file, then open the phone Timeline and check a few dates and location details.

A phone import changes local history only. It does not upload those records, recreate a pending delivery queue or establish server linkage from the file’s numeric IDs. To add history to Wayfarer too, use the Web location importer and verify server history separately. For undelivered recordings, follow queue recovery.

Move Trip plans

From your personal Trips list:

• Import Trip reads Wayfarer-native KML. If the Trip already exists in your account, review the choice to update it or create a separate copy before proceeding.
• Import My Maps reads Google My Maps KML. Review the imported structure and choose transport profiles where needed for duration estimates; the source may not contain reliable transport information.
• Export Wayfarer KML when you want to preserve a plan for reimport into Wayfarer. Export Google My Maps KML when compatibility with that tool is the priority.
• Export a PDF Guide for a printable itinerary with notes, map snapshots, distances and links. Follow generation progress and cancel if you no longer need it. Links to external searches or maps contact those services when opened.

Google My Maps KML coordinates use decimal points regardless of the server’s number-formatting locale, preserving their precision when moved between tools.

For planning, routes and visits, see Trips. Downloading a Trip to Mobile is a separate action from exporting a file.

Metadata and format compatibility

Wayfarer history formats carry available accuracy, speed, altitude, heading, activity, source, notes and address information. Wayfarer exports can also retain provider display text and supported mapped-feature information. Older files remain accepted, but another tool may drop unfamiliar fields. Supplied addresses are retained rather than silently rewritten by import.

The published Mobile app uses its existing full-address fields. Its local import and export do not promise to retain newer server-only address fields such as ProviderAddressLine1. Keep the original server export if you need that detail.

Web CSV and Wayfarer GeoJSON history exports preserve stored UUIDs (IdempotencyKey), while older keyless files remain accepted. Android 1.3.0 Timeline exports still omit that identifier. Queue-recovery files carry it for delivery reconciliation.

Native Trip KML preserves Regions, Places, Areas, ordered From/Via/To connections, route geometry, the saved distance and duration, and automatic/manual duration choices. Current exports use native version 3 so provider estimates, fractional seconds and retained route attribution survive import and copying. Wayfarer estimates are equally valid; a provider connection is not required to transfer a Trip. A different planning speed at the destination does not replace the saved version 3 values.

Existing version 1 and 2 files remain readable under their established import rules. Older Wayfarer releases that support only those versions cannot read new version 3 exports. Creating a new copy keeps a loop’s shared endpoint and waypoint order consistent. Generic KML and older native files still use their established geometry/planning reconciliation; import never calls a provider to invent a route. See the native measurement contract for version and precision details.

Generic interchange formats cannot promise Wayfarer’s full planning semantics. Route coordinates alone do not establish which saved Places are Via stops. Supported note formatting is retained, but arbitrary imported HTML layouts and styles do not have exact visual fidelity. For custom integrations and exact fields, use the API reference.

Recover Mobile queue and local history safely

Use this section when moving to another phone or delivering queued records through a file. Normal Mobile synchronization does not require these recovery steps.

Know which copy you are recovering

Exporting recovery data does not clear the queue. Do not uninstall, clear app data, clear pending records or lower a queue limit in a way that discards undelivered records to fix synchronization.

Deliver queued records through a server import

1. On the original phone, open Settings > Offline Queue and choose Prepare recovery. Wait until delivery is suspended and active work has finished.
2. Export a recovery CSV or GeoJSON. Keep the original file intact. Export also establishes the suspended-delivery boundary and leaves the queue in place.
3. In Wayfarer’s web Location imports, import CSV with CSV, or the recovery GeoJSON with Wayfarer GeoJSON.
4. Wait for the import’s final result. Inspect errors and verify the imported server history before proceeding. A failed or partial import needs inspection or retry, not queue clearing.
5. On the original phone, use Resume and reconcile. Wayfarer recognizes records already imported for the same user by their portable identifiers; missing records can upload normally. Confirmed queue rows become synced and follow ordinary retention.

The portable GUID is carried as IdempotencyKey. Removing or changing it can prevent exact reconciliation. Use the same Wayfarer instance and user account for the import and resumed delivery. A success message about exporting a file is not confirmation that the server has those records.

Restore history on another phone too

Import the recovery file into the replacement phone’s Timeline and verify that local history separately. Also import it into Wayfarer and verify server history as above. These are two imports: neither one repairs the other copy, and neither recreates the original delivery queue. Resume and reconcile the original phone only if its queue still exists.

Recovery files can include locations, times, notes, activity/check-in information, device/app/OS/battery metadata, delivery diagnostics and identifiers. Transfer them securely and retain them until both histories are verified. Remove unnecessary copies afterward.

User guide · Documentation home