Journey Importer: Polarsteps Export Support

[elmocito]

Summary

Add support for importing past trips from a Polarsteps data export (JSON) into Trek Journeys.

Motivation

Polarsteps allows users to request a full data export of their travel history via GDPR/data portability request. The export contains structured data per trip including stops with coordinates, timestamps, step titles, and travel notes — making it a great source for reconstructing past journeys in Trek.

Currently there is no way to import this data into Trek without manually recreating every stop and journal entry. For users migrating from Polarsteps, this is a significant barrier.

Proposed Behavior

• User uploads or pastes a Polarsteps trip.json export file
• Trek parses the stops (all_steps) into Journey entries, mapping:
  • name → entry title
  • description → entry content
  • start_time → entry date
  • location.lat / location.lon → place coordinates
  • location.name → place name
• A new Journey is created with all entries pre-populated

Export Format Reference

Polarsteps exports a ZIP archive containing one folder per trip, each with a trip.json. Relevant fields:

{
  "name": "Trip to Japan",
  "start_date": 1609459200,
  "all_steps": [
    {
      "name": "Arrived in Tokyo",
      "description": "First impressions...",
      "start_time": 1609459200,
      "location": {
        "name": "Tokyo, Japan",
        "lat": 35.6762,
        "lon": 139.6503
      }
    }
  ]
}

Acceptance Criteria

• Upload or import of a Polarsteps trip.json creates a new Journey
• Each step becomes a Journey entry with date, title, content, and linked place
• Duplicate detection if the same trip is imported twice
• Graceful error handling for missing or malformed fields

Additional Context

Polarsteps is one of the most widely used travel logging apps, so this would lower the migration barrier significantly for new Trek users.

[Exafit]

I feel the same way. I'd like to use Trek in the future, but I can't find a way to import my old trips from Polarsteps. It would be a shame not to be able to transfer them. Many of my friends are struggling with the same problem: they can't switch travel apps without losing everything.
I was just about to submit the same request.
Here's some more information about the data export:
https://support.polarsteps.com/hc/en-us/articles/24266264821138-How-can-I-export-a-copy-of-my-data

[raduwolf12]

I'll add a plugin for this in the following days.

[Exafit]

wow that's awesome!

[raduwolf12]

Hi, i have reworked it a bit to be a bit more general, but it also supports Polarsteps.
If you want to test it out before i fully release it https://github.com/raduwolf12/trip-importer
Note: There is an issue with uploading the pictures to the days in the journey

[elmocito]

I added a few fixes and features, but I still can't make it upload the pictures in the journal. Maybe with the next update, I could make that change happen

Hey,
Are you planning more? :-) Otherwise I would pick your code and try it myself.
BR

[raduwolf12]

Hey, just pushed a few changes, but I couldn't make it work for pictures. Feel free to pick it up and try

[adberger]

Probably a limitation of the plugin implementation, maybe @mauriceboe could shed some light?

[elmocito]

I picked this up and opened a PR here: raduwolf12/trip-importer#1
Diagnosis from testing with my Polarsteps export: the large-trip failure was not caused by the ZIP size directly, but by individual resumable /import requests exceeding TREK's plugin route body limit. The importer paginated by item count, but some Polarsteps stops contain long stories, so 40 stops could still be too large.
The PR also fixes imported Polarsteps descriptions not showing in TREK Journey entries: the plugin wrote them to content, while the current Journey editor reads story.
Weather can be imported through the existing flexible entry payload, so the PR maps Polarsteps weather conditions to TREK's Journey weather keys.

Photos are different: the plugin can upload them as trip files / place-linked files, but automatic attachment to the Journey entry photo field seems to require a TREK Plugin SDK addition. TREK has internal Journey photo routes, but the current plugin SDK does not expose a journal.addPhoto / journal.addProviderPhoto style method. @mauriceboe - would be great if you could pick this up.

Other than that the plugin works awesome. Kudos, @raduwolf12 - Thanks so much! Will update everything as soon as it is possible to import pictures to the journey.

[keunes]

I haven't tried it yet but this is a great prospect!
For the images I was wondering: would it be possible to make the Trek importer upload the images to Immich and create and do all the subsequent organisation and linking? I reckon that because there's Immich integration already a user may already have an API key to make this possible?

[mauriceboe]

Built it: #2105 adds journal.addEntryPhoto to the plugin SDK, so a plugin can hand an entry the photo bytes directly. It takes { name, content_base64, caption? }, and it refuses exactly what the upload form refuses, images only and no SVG, the operator's allowed-file-types setting, 10MB per photo, and it only ever reaches entries the acting user could edit by hand. The stored filename is the host's, so nothing collides in the gallery.

@raduwolf12 thanks for building trip-importer in the first place, and for leaving it open when you ran into the wall instead of quietly dropping it. @elmocito your diagnosis was the useful part of this thread: the body limit on the resumable requests, content vs story, and pinning down that the photos needed something from my side rather than yours. That is what I built against. @Exafit thanks for the export documentation, and @adberger for pulling me in.

@keunes on the Immich idea: not with this method. The upload form mirrors to Immich when the user has that switched on, and I deliberately left that out of the plugin path for now, so photos a plugin attaches stay local. Worth doing later, but it is a bigger question than this one method, and I did not want to hold the fix for it.

It goes out with 4.1.0. Ping me before then if the shape does not fit what the importer actually needs: changing it now is cheap, changing it after a release is not.

[elmocito]

Lovely, thanks 🙏