Immich and Mapsake's Biggest Travel Passport Update

The biggest Mapsake update so far

Mapsake started with a fairly simple promise: mark the places you have visited, lived, and want to see next, then keep that record private and portable. The map is still the center of the app, but this release changes how quickly a real travel history can get into it and what you can do once it is there.

The two largest pieces are deeper Immich support and a rebuilt Travel Passport. One turns a self-hosted photo library into useful travel evidence; the other turns that history into something worth exploring and sharing.

This is the biggest Mapsake update so far, not because it adds the longest list of settings, but because it closes the loop from private source data to a finished personal atlas.

Immich is now a first-class photo source

Many people who care about owning their photo library use Immich. It is a self-hosted photo and video system, which makes it a natural fit for Mapsake's local-first approach. The tricky part was supporting it without turning Mapsake into another photo uploader or asking a server in the middle to process someone's travel history.

The connection is direct. In Record, enter the URL for your Immich server and an API key created from Immich's user settings. Mapsake stores the key in the Apple Keychain and talks from the device to that server. There is no Mapsake account to create and no Mapsake service receiving the library.

Mapsake reads located assets in pages, including their coordinates, capture dates, and available camera model. It saves the small amount of metadata needed to build the atlas, then resolves those points through the same place pipeline used by Apple Photos. Immich thumbnails can appear in place stories, while a larger preview is fetched from the user's server only when it is opened.

That last detail matters. The app does not need to duplicate an Immich library in order to make it useful. It keeps a reference to each source asset, a compact local travel index, and a regenerable thumbnail cache. The original remains where its owner put it.

The first Immich importer was useful, but incomplete

The earliest implementation used Immich's map-marker endpoint. It was an appealing starting point: one request returned every located asset with coordinates and place names already resolved by Immich. There was no need to throttle Apple's network geocoder, and there was no arbitrary cap on the size of the library.

That version could paint countries quickly, but it was not yet a true photo source. A marker alone did not give Mapsake enough durable identity to show the image again, preserve its capture date, apply the same camera filters as Apple Photos, or remove one image from the map without removing an entire place.

The importer therefore moved to Immich's paged metadata search. Each asset now has a stable source identifier, date, coordinates, and available EXIF camera model. Mapsake namespaces the identifier with an Immich prefix before placing it in the shared photo metadata store, so it can never collide with an Apple Photos identifier that happens to contain the same text.

That migration also fixed a subtle product inconsistency. Before it, an Immich-derived place could report a photo count but open to an empty photo grid. The map knew that images existed, while the place story did not know how to retrieve them. Treating Immich as the same kind of indexed source as Photos made counts, filters, thumbnails, exclusions, heatmaps, and stories agree.

One importer, several sources

Immich also forced a useful refactor. The original photo import mixed source access, place resolution, merging, progress, and presentation in one model. That was workable for Apple Photos but would have grown a separate branch for every new service.

Mapsake now separates those responsibilities. A source produces normalized located records. The headless import engine clusters or resolves them, applies the same hierarchy rules, and merges the result into the atlas. The foreground screen supplies progress and review; background sync can call the same engine without constructing the interface.

The payoff reaches beyond Immich. File importers, Nomads, and later integrations can preserve their source-specific parsing while sharing the rules that decide when a city implies a region and country, how duplicates are handled, and which existing mark should be updated rather than recreated.

This is less glamorous than a new card, but it is the kind of internal boundary that keeps a feature-rich app comprehensible. A new importer should mostly answer “how do I read this source?” rather than re-answering “what does a place mean?”

Background sync without continuous tracking

After the first import, Immich can be enabled as an optional background source. When the system gives Mapsake background time, the app checks the server again, updates its local asset snapshot, and merges newly discovered places into the map. Notifications for new places remain optional.

This is not continuous GPS tracking. Mapsake reconstructs the record from photo dates and locations already stored in Immich. It also keeps the review and editing tools that matter when metadata is imperfect: device filters, minimum-photo thresholds, place inspection, and the ability to exclude an individual image from the map without deleting it from its source.

Immich does not expose every field Apple Photos can provide. In particular, altitude and speed are not available through this path, so filters based on those fields do not affect Immich assets. I would rather state that boundary clearly than pretend every source is identical.

Sync has to fail safely

Background work is opportunistic on Apple platforms. The app can request time, but it cannot promise that iOS will wake it at an exact minute. A self-hosted server can also be offline, reachable only through a home network, or temporarily return an authorization error after an API key changes.

Mapsake treats the source snapshot as authoritative only after a successful fetch. A failed request does not erase the last good atlas. The app records source status, reschedules the work, and counts consecutive failures. After repeated network-source failures it disables that automation and tells the user rather than silently retrying forever.

The same service runs a lightweight check when the app returns to the foreground, which gives sync a practical path even when background scheduling has been conservative. A manual Sync Now remains available because user intent should always beat a scheduler heuristic.

The API key never appears in logs, exports, or a Passport share. Logs name the source and report counts or status codes, which is enough to diagnose most failures without turning a debugging trail into a credential leak.

The Passport became a real second home for the atlas

The original Passport was a compact statistics screen. It counted countries and continents and produced a shareable card. Useful, but much smaller than the map behind it.

The new Passport is a collection of swipeable stories built from the same travel record:

• A world map and percent-of-the-world card for Visited, Lived, Next, or a combined view.
• Country flags, continent progress, regions, cities, airports, photo counts, and days on the ground.
• Region and year filters, so a lifetime atlas can become one continent or one chapter.
• Data maps shaded by photo count, recency, or time spent.
• Colorful card variants and per-card color controls.
• A rotating-globe reel that renders on the device as a social-ready video.

Every card uses the same underlying Passport data model. That keeps the totals consistent when someone changes a lens, region, or year, and it lets the main Passport, friend Passport, share cards, widgets, and Apple TV reuse the same calculations instead of inventing seperate versions of the truth.

The first alternate-card prototype revealed why that shared model matters. It is easy to make a beautiful continent grid that counts countries one way and a map card that counts territories another way. Both can look plausible in isolation. Side by side, the contradiction is obvious.

Passport data is therefore calculated before any particular card is drawn. It carries the selected travel lens, time and region scope, counts, flags, photo totals, date ranges, coverage, crop bounds, and map colors. A card chooses how to express those values; it does not decide them again.

That split made horizontal card variants possible. Swiping does not load a new dataset or re-run an import. It changes the visual argument: map-first, numbers-first, flags-first, or a ranked list. The share button receives the visible variant, so the exported image is the card the user actually chose rather than the first card in its family.

A Passport should feel personal without losing legibility

The vivid card system began as an attempt to move beyond generic white statistic panels. Lens colors now seed gradients and highlights, continents can use their own palettes, and map cards can add a flight path or glowing globe without changing the facts underneath.

Customization introduced another boundary. Text, accent, and background colors can be edited per card, but the renderer still has to preserve contrast in both light and dark appearances and at social-export resolution. Defaults do most of the work; editing is there for someone who wants their Passport to match their own map or a particular trip.

Region filtering became more than a dropdown. Selecting a continent changes map crop bounds and swaps global coverage for useful subregions: Southeast Asia, the Balkans, Nordic countries, or state and province coverage in North America. Year filtering applies the same idea to time. The Passport can describe the whole life, or only what was true by the end of 2016.

The data-map card was another unification point. Photos, recency, and time spent were first Atlas modes. Moving their shared metric and color logic below both surfaces meant Passport could export exactly the heatmap the Atlas was showing, complete with a discrete legend.

The reel follows the same rule. It is not a recording of the app interface. Mapsake renders the globe, highlighted countries, statistics, and branded overlay into a proper video, then hands the finished file to the normal share sheet. Nothing is posted automatically.

Why render a reel instead of recording the screen?

A screen recording would capture navigation bars, touch indicators, device dimensions, and whatever frame rate the live interface happened to sustain. It would also make the exported result depend on the user performing the same gesture cleanly every time.

The reel renderer uses a dedicated SceneKit globe and a transparent statistics overlay. Frames are written into an H.264 video at a known vertical size, with a controlled rotation duration and no interface chrome. The live Passport card uses the same globe speed, so tapping Share feels like exporting the thing already on screen rather than switching to a different animation.

This offscreen renderer is deliberately separate from the Apple Maps globe used for day-to-day exploration. MapKit is excellent at streamed interactive maps, but it is not a deterministic video renderer. Keeping the older geometry and SceneKit paths for cards, reels, widgets, and Apple TV is duplication with a purpose: those surfaces need repeatable pixels without a live map service.

Video generation stays local and displays progress because several seconds of high-resolution frames are real work. When it is finished, the user can save to Photos, send it through Messages, or open the system share sheet. Mapsake does not need a social account or an upload endpoint to create a social-ready result.

One source of truth, many ways back into it

Immich and Passport may look like unrelated features, but they solve adjacent parts of the same problem. Importing makes the atlas complete enough to trust. Passport makes that complete record easy to revisit.

A located photo can become a city, region, and country; contribute to photo and recency heatmaps; add time to a trip; fill a Passport card; and strengthen the story of a place. Correct the underlying mark once and every surface should agree.

That is the architectural direction for Mapsake: one durable travel history, with multiple views rather than multiple databases.

There are still honest limits. Immich has to be reachable from the device for thumbnails and new syncs. iOS ultimately decides when background work runs. Photo metadata can prove that a camera was somewhere, not why the traveler was there. Passport statistics are only as accurate as the dates and marks underneath them.

Those limits are why every layer remains editable. Automation should get someone close to a trustworthy atlas quickly; it should never make the record feel uncorrectable.

How to try it

1. Open Record, choose Add locations from Immich Server media, and connect your server URL and API key.
2. Test the connection, run the import, and review the places before saving.
3. Optionally enable Immich under background sync if you want the atlas to keep catching up.
4. Open Passport, switch lenses, then try the region and year filters.
5. Swipe a card for alternate layouts, recolor one, or create a rotating-globe reel.

Mapsake remains free, with no ads, subscription, or required account. The point of a bigger update is not to create more things to sell. It is to make the atlas more useful to keep.

• See everything Mapsake can import
• Explore the Travel Passport
• Read the local-first privacy model