iso.me Maps

iso.me Maps for Obsidian

Render interactive Leaflet maps inline in Obsidian notes from iso.me exports and compatible location-tracking formats.

The plugin registers an Obsidian Markdown code block named iso-me. Add a fenced block to any note, point it at one or more export files in your vault, and the plugin renders visits, routes, outliers, stats, and optional interactive filters.

---

Quick start

1. Install and enable iso.me Maps in Obsidian.
2. Export data from the iso.me iOS app. JSON combined exports are the easiest starting point.
3. Put the export in your vault, for example exports/iso.me-2026-05-04.json.
4. Add this to any note:

```iso-me
source: exports/iso.me-2026-05-04.json
title: Where I went
height: 500
show_visits: true
show_routes: true
```

source or sources is required. Every other block parameter is optional.

---

What it renders

• Visit markers — duration-encoded circle markers. Longer stays are larger and more opaque. Popups show place name, address, arrival/departure time, duration, and notes when available.
• Route polylines — connected GPS tracks with green start marker, red end marker, and route popup showing path distance and straight-line distance.
• GPS glitch / outlier markers — optional scatter markers for points flagged as outliers by iso.me. Outliers are hidden by default and are always excluded from routes, route distance, and average speed.
• Stats bar — export format badge, visit count, point count, distance, average speed, date range, and top repeated place.
• Interactive filters — optional day selector and time-of-day range slider.

Supported formats:

• iso.me JSON
• iso.me CSV
• iso.me Markdown
• OwnTracks JSON
• Overland JSON / GeoJSON
• GPX

---

Setup guide

1. Install the plugin

From Obsidian Community Plugins

If the plugin is available in Community Plugins:

1. Open Settings → Community plugins.
2. Disable Restricted mode if needed.
3. Click Browse.
4. Search for iso.me Maps.
5. Click Install, then Enable.

Manual install from a release

1. Download these files from the latest release:

   • manifest.json
   • main.js
   • styles.css

2. In your vault, create this folder:

   .obsidian/plugins/iso-me-maps/
   

3. Copy the three files into that folder.

4. Restart Obsidian or run Reload app without saving from the command palette.

5. Open Settings → Community plugins and enable iso.me Maps.

Development install from this repository

npm install
npm run build
ln -s "$PWD" "<your-vault>/.obsidian/plugins/iso-me-maps"

Then reload Obsidian and enable the plugin.

2. Export data from iso.me

In the iso.me iOS app, export the data you want to map. Recommended options:

• Use JSON for the simplest one-file workflow.
• Use a combined export containing both visits and points when possible.
• If exporting CSV or Markdown visits, enable Coordinates in iso.me export options. Visits without latitude/longitude cannot be plotted.
• If using One file per day, place all generated files in a single vault folder and use a folder source, glob source, or date keyword.

3. Put exports in your vault

A common layout is:

Your vault/
  Daily Notes/
  exports/
    iso.me - Monday 2026-05-04 - all.json
    iso.me - Tuesday 2026-05-05 - all.json

4. Configure plugin settings

Open Settings → iso.me Maps.

Recommended first-time settings:

5. Add a map block

```iso-me
source: yesterday
title: Yesterday
height: 500
interactive: true
```

With exportsFolder = exports, source: yesterday searches the exports/ folder for a file matching yesterday's date.

---

Complete code block parameter reference

Use parameters inside a fenced iso-me code block:

```iso-me
source: exports/day.json
height: 500
zoom: 12
center: [37.7749, -122.4194]
show_visits: true
show_routes: true
show_stats: false
interactive: false
title: April trip
```

Parameter syntax rules

• The code fence language must be exactly iso-me:

  ```iso-me
  source: exports/day.json
  ```
  

• Keys are case-insensitive, but the documented lowercase names are recommended.

• Blank lines are ignored.

• Lines beginning with # are comments.

• Unknown keys are ignored.

• Malformed values are ignored and the plugin falls back to defaults.

• Strings may be unquoted, single-quoted, or double-quoted:

  title: My trip
  title: "My trip"
  title: 'My trip'
  

• Boolean values accept all of these forms:

  True	False
  true	false
  yes	no
  on	off
  1	0

• center must be bracketed latitude/longitude:

  center: [37.7749, -122.4194]
  

sources syntax

Multi-line YAML-style list:

```iso-me
sources:
  - exports/visits.md
  - exports/points.md
```

Inline bracket list:

```iso-me
sources: [exports/visits.md, exports/points.md]
```

Inline comma list:

```iso-me
sources: exports/visits.md, exports/points.md
```

If both source and sources are present, all listed sources are loaded and merged.

---

Source resolution, date keywords, folders, and globs

A source can be any of the following:

Supported file extensions are:

.json, .csv, .md, .markdown, .gpx

Date keywords

Date keywords are available in source and in each item under sources.

Examples:

```iso-me
source: today
title: Today
```

```iso-me
source: yesterday
title: Yesterday
```

```iso-me
source: 2026-05-04
title: May 4, 2026
```

```iso-me
source: last 7 days
title: Last week
interactive: true
```

Date keyword settings

Date keywords use three settings:

With these settings:

Exports folder: exports
Export filename pattern: *{date}*
Export date format: YYYY-MM-DD

This block:

```iso-me
source: yesterday
```

resolves to a glob like:

exports/*2026-05-08*

That matches filenames such as:

exports/iso.me - Friday 2026-05-08 - all.json
exports/isome_complete_export_2026-05-08_121042.json

Filename pattern examples

If the pattern does not contain {date}, the plugin appends *<date>* to the pattern internally.

Glob rules

• * matches any characters within a filename component.
• ? matches one character within a filename component.
• Wildcards are supported in the filename only; the directory path must be literal.
• Matched files are sorted alphabetically before loading.
• Duplicate source paths are loaded only once.
• If any matched file fails to parse, the map block shows an error for that block.

---

Plugin settings reference

Open Settings → iso.me Maps to configure defaults.

Tile settings

Available tile provider IDs:

Tile setting changes apply to newly rendered maps. Already-open notes may need to be reloaded.

Export lookup settings

Map defaults and layer styling

---

Supported export formats and fields

The parser is intentionally permissive: rows or objects missing required plotting fields are skipped instead of breaking the whole export. A file-level parse error is shown only when the overall file shape is unrecognized or invalid.

iso.me JSON

File extension: .json

Supported root shapes:

{ "exportDate": "2026-05-04T12:00:00Z", "visits": [] }

{ "exportDate": "2026-05-04T12:00:00Z", "points": [] }

{ "exportDate": "2026-05-04T12:00:00Z", "visits": [], "points": [] }

Visit objects:

Point objects:

iso.me CSV

File extension: .csv

CSV type is detected by the header row.

Visits CSV

A visits CSV is detected when the header includes:

arrived_at

Required columns for plotted rows:

Optional columns:

Rows without arrived_at, latitude, or longitude are skipped.

Points CSV

A points CSV is detected when the header includes all of:

timestamp, latitude, longitude

Required columns for plotted rows:

Optional columns:

iso.me Markdown

File extensions: .md, .markdown

Markdown parsing assumes iso.me's default English date/time export format, for example:

Friday, March 14, 2025
3:24 PM
3:24:05 PM
15:24
15:24:05

Supported H1 sections:

Visits Markdown — bullet format

Expected structure:

# iso.me Export

## Friday, March 14, 2025

### Coffee Shop
- **Arrived:** 8:12 AM
- **Departed:** 8:45 AM
- **Duration:** 33m
- **Address:** 123 Market St
- **Coordinates:** 37.7749, -122.4194
> Optional notes

Supported bullet fields:

The ### heading is used as locationName unless the heading itself is just a time.

Visits Markdown — table format

The parser also accepts visit tables with at least these columns:

Arrived, Lat, Lon

Optional columns:

Departed, Duration, Location, Address, Notes

Points Markdown — table format

Expected H1:

# iso.me Location Points Export

The point table must include:

Time, Lat, Lon

Optional columns:

Altitude, Speed, Accuracy, Outlier

Outlier is true when the cell is yes or true.

OwnTracks JSON

File extension: .json

Detected when the JSON root is an array whose first object looks like an OwnTracks location:

[
  {
    "_type": "location",
    "lat": 37.7749,
    "lon": -122.4194,
    "tst": 1777891200,
    "acc": 10,
    "alt": 12,
    "vel": 18,
    "cog": 270,
    "vac": 5
  }
]

Supported fields:

OwnTracks files contain points only, so visit markers are not rendered.

Overland JSON / GeoJSON

File extension: .json

Detected when the JSON root has a locations array of GeoJSON point features:

{
  "locations": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-122.4194, 37.7749]
      },
      "properties": {
        "timestamp": "2026-05-04T12:00:00Z",
        "altitude": 12,
        "speed": 4.2,
        "horizontalAccuracy": 10,
        "deviceId": "iphone"
      }
    }
  ]
}

Supported fields:

Overland files contain points only, so visit markers are not rendered.

GPX

File extension: .gpx

The parser uses the browser's built-in DOMParser, available in desktop and mobile Obsidian.

Supported GPX content:

Waypoint visit fields:

Track point fields:

iso.me extension namespace:

xmlns:isome="https://isome.isolated.tech/gpx/1.0"

---

Layer behavior details

Visits

• Visits require latitude, longitude, and arrival time.
• Marker radius is based on durationMinutes using a logarithmic scale.
• Marker opacity increases for longer stays.
• Popup fields are escaped before rendering.

Routes

• Routes require location points.
• Outlier points are always removed before route rendering.
• Routes with more than 1,500 points are visually downsampled for rendering performance, but popup path distance is computed from the full clean point set.
• Single-point routes render as one point marker.

Outliers

• Outliers are points where isOutlier is true.
• They are hidden by default.
• When shown, they render as small markers with a timestamp popup.
• They never contribute to routes, route distance, or average speed.

Stats bar

The stats bar is hidden by default. Add show_stats: true to a map block to display it. It is best-effort and never blocks map rendering. It summarizes the loaded export data:

• Detected format
• Visit count
• Point count
• Total clean-point route distance
• Average speed from clean points with speed data
• Date range
• Top repeated place when a place appears at least twice

When interactive: true, filters update map layers but the stats bar remains a summary of the loaded export.

Interactive filters

interactive: true adds:

• Format badge
• Day selector with All days plus every local day present in visits or points
• Time-of-day range sliders from Start of day to End of day
• 15-minute slider steps
• Reset button

Filtering uses each timestamp's local day and local time in Obsidian.

---

Common recipes

Daily note template: yesterday's map

Set Exports folder to exports, then put this in a daily note template:

```iso-me
source: yesterday
title: Yesterday's movement
height: 450
interactive: true
```

Last 30 days from one-file-per-day exports

```iso-me
source: last 30 days
title: Last 30 days
height: 600
interactive: true
```

Separate visit and point files

```iso-me
sources:
  - exports/2026-05-04-visits.md
  - exports/2026-05-04-points.md
title: May 4, 2026
show_visits: true
show_routes: true
```

All files in a folder

```iso-me
source: exports/may-2026/
title: May 2026
interactive: true
```

Glob a subset of daily files

```iso-me
source: exports/iso.me*all*.json
title: Combined daily exports
```

Satellite map default

Set Tile provider to esri-world-imagery in settings, then use normal blocks:

```iso-me
source: exports/hike.gpx
title: Hike
show_routes: true
```

---

Examples included in this repository

The examples/ directory contains sample export files for all supported formats, plus examples/usage-examples.md with ready-to-paste Obsidian code blocks.

---

Troubleshooting

iso.me: Missing required source

Add either source: or sources: to the block.

File not found

Check:

• The path is relative to the vault root.
• The file is inside the vault.
• Exports folder is set correctly if you are using bare filenames or date keywords.
• Date keyword pattern matches the actual filename.

Date keyword does not find my file

Use a more specific or more permissive Export filename pattern.

For example, if files are named:

iso.me - Friday 2026-05-08 - all.json

use:

*{date}*all*

Visits do not appear from CSV or Markdown

Make sure the export includes coordinates. Visit rows without latitude and longitude are skipped.

Routes do not appear

Make sure the export includes location points. Visit-only exports can show visit markers but cannot render routes.

Outliers do not affect routes

This is intentional. Outliers are always excluded from routes, distance, and average speed.

OpenStreetMap tiles are blank on desktop

Use CartoDB Voyager, CartoDB Positron, CartoDB Dark Matter, OpenTopoMap, Esri World Imagery, or a custom provider. OSM's standard tile servers reject desktop Obsidian/Electron requests due to referer policy.

The map has the wrong timezone/day

Interactive day and time filters use the local timezone of Obsidian when parsing timestamps.

---

Privacy notes

• Export files stay in your Obsidian vault.
• The plugin reads local vault files and renders the map in Obsidian.
• Basemap tiles are requested from the selected tile provider, so map tile requests may reveal viewed map areas to that provider.
• Use a custom/self-hosted tile provider if you need stricter privacy.

---

Development

npm install
npm run dev          # esbuild watch mode
npm run build        # type-check and bundle for production

To test locally, symlink the plugin folder into a test vault:

ln -s "$PWD" "<test-vault>/.obsidian/plugins/iso-me-maps"

Reload Obsidian, disable Restricted mode if needed, and enable iso.me Maps.

---

License

MIT