search

esm7 / obsidian-map-view

Interactive map view for Obsidian.md
MIT License
546 stars 25 forks source link

readme

Obsidian.md Map View

"Buy Me A Coffee"

Intro

This plugin introduces an interactive map view for Obsidian.md. It searches your notes for encoded geolocations (see below), places them as markers on a map and offers many tools to interact with them.

It effectively turns your Obsidian vault into a personal GIS system that adds a geographical layer to your notes, journals, trip planning and pretty much anything you use Obsidian for.

You can set different icons for different note types according to custom rules, save geolocations from a variety of sources (Google Maps and many others), save custom views, embed maps in notes, switch between map layers, run powerful queries and so much more.

I wrote this plugin because I wanted my ever-growing Zettelkasten to be able to answer questions like...

Map View can integrate with your note-taking flow in order to answer all of these questions and much more.

Just like the Obsidian graph view lets you visualize associative relations between some of your notes, the map view lets you visualize geographic ones.

With Obsidian Mobile

The main limitation of the plugin right now is that the Obsidian Mobile app has no location permission, so on mobile you cannot see your current location natively.

To overcome this, Map View introduced a companion Geo Helper app.

Support the Development

If you want to support the development of this plugin, please consider to buy me a coffee.

Quick How To

Map View is a powerful tool with many ways to use it. If you wanna learn it thoroughly, you may wanna start from understanding how it works. But if you wanna dive right in and give it a try, or get a quick glimpse of what it can do, continue reading.

Log a Geolocation

Here are a few examples for logging a favorite location you want to see in a map.

Option 1: from a Note

Starting from a note, e.g. your daily note, a note referring to a trip plan or anywhere else, launch the Obsidian Command Palette and choose "Map View: add inline geolocation link". A link in the format of [](geo:) will be added where your cursor is. Start typing a location name inside the bracket, and some geolocation results will pop up. Choose one and your inline location is complete.

Option 2: from the Map

Open Map View (e.g. from the Obsidian ribbon icon). Search or locate a location, e.g. using the search tool. Right-click the map and choose "new note here (front matter)" to create a note logging the selection point, or choose "copy geolocation" to copy an inline location to paste in some other note.

There are many other ways to log geolocations in Map View, see here for more details.

Create a Trip Plan Map

There are many flows you can use to create custom maps, interact with them and use them for research and planning -- here's one that I typically use for trip planning.

Step 1: log some locations.

For most trips, I like to use a single note with sections, for example:

## To Visit

- [Place 1](geo:...) tag:activity
  - Some information about this place
- [Place 2](geo:...) tag:activity
  - Information about this place

## To Eat

- [Restaurant1](geo:...) tag:food
  - Opening hours, other data...
- [Restaurant2](geo:...) tag:food
  - Opening hours, other data...

I add the places using one of the methods above (by searching with "add inline geolocation link") or by one of the many other methods described below. Notice the inline tags, these can be used for custom filters and/or creating different icons for different types of places.

Step 2: map them!

In the case of a single note, just click the note's menu (3 dots) and choose "focus (note name) in Map View". You should immediately see a map of all your locations, and if you spend some moments to configure marker icons, you can easily get different shapes and colors for your various tags.

Step 3: save this map

You have a few options here.

One thing you can do is to open the Presets section on the map and save the current view, then open it from Map View anytime.

Another option is to save an embed: in Presets click 'Copy block' (or "Copy Map View code block" from the note menu), then paste the resulting code into a note.

There are many more options of how to build a trip plan, present it and use it. This post gives a more detailed example, and diving into the details of how Map View works will help you find your own optimal flow.

Build Your Personal Geographic Information System (GIS)

The most powerful way to use Map View is to build a complete personal GIS (Geographic Information System) from your notes vault. I personally do this as follows.

1. Collection

This part isn't specific to Map View, but the main idea is that I collect pieces of information from various sources, that often contain some geographic information.

For example, I can save a Facebook post that recommends a new restaurant, clip a cool hike from a hiking group, or draft a quick note when a friend tells me about a place that I want to remember.

I later turn these into notes, but of course if that's not how you do things, you can skip to Processing.

2. Processing

When I turn my clipped pieces of information into notes, I add geolocations as follows.

3. Querying

There are countless occasions that I query my Personal GIS.

See also this Reddit post about planning a vacation with Map View.

Understanding Map View: Parsing Location Data

Map View provides several methods to log locations in notes and can manage the technicalities for you. You can skip to that section if you want to just get started, or continue reading the more technical explanation below.

To clarify, you can use Map View without entering geolocations manually at all. You will, however, need to understand the difference between the front matter and the inline formats, and decide when to use which.

So, the plugin works by scanning your notes and parsing two types of location data.

First is a location tag in a note's front matter:

---
location: "40.6892494,-74.0466891"
---

This is useful for notes that represent a single specific location.

There is an alternative syntax used by Map View previously: location: [40.6892494, -74.0466891]. While this format is compatible with obsidian-leaflet, it doesn't play very well with Obsidian's property editor. Both format are supported by the new one is encouraged for Obsidian version 1.4 and above.

Another way that the plugin parses location data is through inline location URLs in the format of [link-name](geo:40.68,-74.04), which allow multiple markers in the same note. To prevent the need to scan the full content of all your notes, it requires an empty locations: tag in the note front matter ('locations' and not 'location'). (In most methods of entering geolocations Map View will do this automatically.) Example:

---
locations:
---

# Trip Plan

Point 1: [Hudson River](geo:42.277578,-76.1598107)
... more note content ...

Point 2: [New Haven](geo:41.2982672,-72.9991356)

Notes with multiple markers will contain multiple markers on the map with the same note name, and clicking on the marker will jump to the correct location within the note.

For many cases inline locations are superior because geo: is a native URL scheme, so if you click it in Obsidian (including mobile), your default maps app (or an app selector for a location) will be triggered. The front matter method, however, is currently better if you want interoperability with plugins that use it, if you want to store lots of filterable meta-data on a location, or if you heavily express yourself with links.

Inline locations also support inline tags in the format of tag:dogs (without the # sign). For example:

Point 1: [Hudson River](geo:42.277578,-76.1598107) tag:dogs

This will add the tag #dogs specifically to that point, regardless of the note's own tags. This is useful for notes that contain tags of different types (e.g. a trip log with various types of locations). Note that the tag: format should be used without the # sign, because this sets the tag for the whole note. Map View will internally add # for the purpose of queries and marker icons, as explained below.

Multiple inline tags can be separated with a whitespace: [](geo:42.2,-76.15) tag:dogs tag:trip.

Multiple inline locations can be added in the same line, and the tags that follow them will be associated to the location on the left, but the right-click editor context menu will not know to choose the location that was selected.

Instead of using a locations: YAML tag, you can use a custom note tag. See "tag name to denote inline geolocations" in the settings. (This also works with wildcards.) It will not be automatically added when you need it like the locations: YAML tag, however if you add an inline geolocation to an existing note where your custom tag is found, Map View will not add a locations: YAML tag. IMPORTANT NOTE: for the time being, using this feature (i.e. having a non-empty "tag name to denote inline geolocations") slows down Map View by an order of magnitude. I'm looking into speeding it up in future releases.

For interoperability with Obsidian's property editor and possibly other plugins, Map View will also parse the syntax of:

location:
    - '39.100105'
    - '-94.5781416'

Adding a Location to a Note

Map View offers many ways to add geolocations to notes.

Anywhere in Obsidian

Map View adds an Obsidian command named "New geolocation note", which you can map to a hotkey and use anywhere in Obsidian.

This opens a dialog on which you can search (address or location based on your configured geocoding provider) or paste a URL using the built-in or custom URL parsing rules.

In an Existing Note

There are multiple ways to add a geolocation to an existing note.

  1. Create an inline geolocation link in the format of [](geo:), and if you start typing inside the link name (the brackets), Map View will initiate a location search. If you confirm one of the options, it will fill-in the location's coordinates. See more on this in the "In-Note Location Search" section below.

To make this more streamlined, Map View adds to Obsidian a command named 'Add inline geolocation link' which you can map to a keyboard shortcut.

  1. Add a front matter geolocation by using the Obsidian command 'Add geolocation (front matter) to current note'. This opens the same dialog as "new geolocation note" which allows you to search for a location name or paste a URL parsing rules.

  2. If you have a geolocation in some other mapping service that you wish to log, e.g. from Google Maps, you can copy the URL or "lat,lng" geolocation from that service, right-click in your note and select "Paste as Geolocation". The supported services are configurable, see below for more details.

From the Map

The map offers several tools to create notes.

  1. Use "new note here" when right-clicking the map. This will create a new note (based on the template you can change in the settings) with the location that you clicked. You can create either an empty note with a front matter (single geolocation) or an empty note with an inline geolocation.

The map can be searched using the tool on the upper-right side, so you can quickly jump to the place you want to mark. URL parsing rules also work here, so you can copy a geolocation from Google Maps (or any other service) and jump to it.

  1. If you prefer to enter geolocations as text, use one of the "copy geolocation" options when you right-click the map and paste them in a note.

Paste as Geolocation

Map View monitors the system clipboard, and when it is is detected to contain an encoded geolocation (e.g. a Google Maps "lat, lng" location), a "Paste as geolocation" entry is added to the editor context menu. For example, if you right-click a location in Google Maps and click the first item in the menu (coordinates in lat,lng format, see below), you can then paste it as a geolocation inside a note.

Alternatively, you can right-click a URL or a supported formatted string that is already present in a note and choose "Convert to geolocation".

By default Map View can parse URLs from two services: the OpenStreetMap "show address" link and a generic "lat, lng" encoding used by many URLs.

Tip: Copying from Google Maps

Google Maps on desktop web offers a very easy shortcut for copying universal lat, lng coordinates.

  1. Right-click anywhere in the Google map.
  2. The first menu item should be the universal coordinates. By clicking it, the coordinates are copied to the clipboard.
  3. In any Obsidian note, right click and choose "paste as geolocation", or paste the coordinates into any Map View search box.

Embedding Maps in Notes

Map View supports the Obsidian code block format for embedding maps in notes. There are several ways to do this:

  1. Embedding an existing map. To embed an existing map from Map View, including its query and any other settings, click 'Copy Block' from the map's Presets dropdown and paste the block into a note.

  1. Embedding directly from a note. From the editor, right-click and choose "embed a Map View" from the context menu, then enter a search term that will be used for the center of the map. Alternatively, there's an Obsidian command named "Map View: add an embedded map" that you can assign to a keyboard shortcut.

Once a map is embedded in a note, it represents a live view that updates according to your notes. Geolocations that are added or modified in the viewed area, and match the query that is saved in the embed, will be updated live.

You can make light adjustments to the view from within the embed (change its zoom, pan or height), and if you want these to be saved, click the 'Save' button that will appear.

To make bigger adjustments, such as updating the query or changing the view completely, use the Open button, make your changes, then click 'Update from open Map View' in the embed's View menu. Note that if you have multiple full instances of Map View open, 'Update from open Map View' may not do what you intended, and you may need to close the unwanted views first.

Embeds also work really nicely in Canvas including live updates.

Advanced Additional Options

Known annoyance: the $filename$ replacement is currently performed when processing the code block and sent to Map View as a final result. Therefore, if you edit the embed interactively (e.g. by zoom or pan and clicking Save), the query field will be overwritten with the actual file name rather than the template.

Queries

Map View supports powerful queries that are roughly similar to Obsidian's query format.

The query string can contain the following search operators:

All operators are case insensitive.

You can combine the above with logical operators: AND, OR, NOT, and grouping with parenthesis. This differs from Obsidian's own query language which uses - instead of NOT and treats spaces as 'AND'.

For examples:

There are many creative ways to organize your notes with geolocations that utilize these query abilities. You may represent location types with tags (e.g. #hike or #restaurant), or use tags to represent traits of places (#hike/summer, #hike/easy). You can use paths for indexes using Zettelkasten back links (e.g. link to "Hikes that I Want" from notes you want to denote as such), then use linkedto: to find places that link to it. And/or you can have notes to plan a trip and link to places from it, then use linkedfrom: to focus on your plan.

In all cases you can save presets that include the filter or sub-filters of it.

Marker Icons

Map View allows you to customize notes' map marker icons based on a powerful rules system. These rules can be edited using the plugin's settings pane or edited as JSON for some even more fine-grained control.

Icons are based on either emojis or Font Awesome, so to add a marker icon you'll need to copy the emoji or find the name in the Font Awesome catalog. Additionally, there are various marker properties (shape, color and more) that are based on Leaflet.ExtraMarkers. An additional shape of simple-circle, that draws a circle at the given color without a pin shape, is supported on top of these.

To change the map marker icons for your notes, go to the Map View settings and scroll to Marker Icon Rules.

A single marker is defined with a tag pattern and icon details. The tag pattern is usually a tag name (e.g. #dogs), but it can also be with a wildcard (e.g. #trips/*). Icon details are a few properties: icon name (taken from the Font Awesome catalog), color and shape.

A single marker is defined in the following JSON structure: {"prefix": "fas", "icon": "fa-bus", "shape": "circle", "color": "red"}

To add a marker with a bus icon, click New Icon Rule, search Font Awesome (in the link above) for 'bus', choose this icon, then see that its name is fa-bus. Once you enter fa-bus in the icon name, you should immediately see your icon in the preview. To make this icon apply for notes with the #travel tag, type #travel in the Tag Name box. Alternatively, just paste an emoji of a bus (e.g. from Emojipedia) into the icon name box.

Tag Rules

To apply an icon to a note with geolocation data, Map View scans the complete list of rules by their order, always starting from default. A rule matches if the tag that it lists is included in the note, and then the rule's fields will overwrite the corresponding fields of the previous matching rules, until all rules were scanned. This allows you to set rules that change just some properties of the icons, e.g. some rules change the shape according to some tags, some change the color etc.

Here's the example I provide as a probably-not-useful default in the plugin:

    {ruleName: "default", preset: true, iconDetails: {"prefix": "fas", "icon": "fa-circle", "markerColor": "blue"}},
    {ruleName: "#trip", preset: false, iconDetails: {"prefix": "fas", "icon": "fa-hiking", "markerColor": "green"}},
    {ruleName: "#trip-water", preset: false, iconDetails: {"prefix": "fas", "markerColor": "blue"}},
    {ruleName: "#dogs", preset: false, iconDetails: {"prefix": "fas", "icon": "fa-paw"}},

This means that all notes will have a blue fa-circle icon by default. However, a note with the #trip tag will have a green fa-hiking icon. Then, a note that has both the #trip and #trip-water tags will have a fa-hiking marker (when the #trip rule is applied), but a blue marker, because the #trip-water overwrites the markerColor that the previous #trip rule has set.

Tag rules also support wildcards, e.g. a rule in the form of "#food*": {...} will match notes with the tag #food, #food/pizza, #food/vegan, #food-to-try etc.

The settings also allow advanced users to manually edit the configuration tree, and there you can use more properties based on the Leaflet.ExtraMarkers properties. Manual edits update the GUI in real-time.

In-Note Location Search & Auto-Complete

Map View adds an Obsidian command named 'Add inline geolocation link', that you can (and encouraged) to map to a keyboard shortcut, e.g. Ctrl+L or Ctrl+Shift+L. This command inserts an empty inline location template: [](geo:).

When editing an inline location in this format, whether if you added it manually or using the command, if you start entering a link name, Map View will start offering locations based on a geocoding service. Selecting one of the suggestions will fill-in the coordinates of the chosen locations and not change your link name (assuming you prefer your own name rather than the formal one offered by the geocoding service).

If your note is not yet marked as one including locations (by a locations:) tag in the front matter, this is added automatically.

Changing a Geocoding Provider

By default, Map View is configured to use OpenStreetMap as the search provider. If you prefer to use the Google Maps search, you can configure this in the plugin settings.

The Google Geocoding API is practically free or very cheap for normal note-taking usage, but you'd need to setup a project and obtain an API key from Google. See here for more details.

If you want, you can add to your API key the slightly more expensive Places API, then turn on "Use Google Places for searches" in the Map View settings. For most reasonable note-taking usage, you will not likely go beyond the Places API free tier.

Note: usage of any geocoding provider is at your own risk, and it's your own responsibility to verify you are not violating the service's terms of usage.

Map Sources

By default, Map View uses the CartoDB Voyager Map, which is free for up to 75K requests per month. However, you can change or add map sources in the configuration with any service that has a tiles API using a standard URL syntax.

There are many services of localized, specialized or just beautifully-rendered maps that you can use, sometimes following a free registration. See a pretty comprehensive list here.

For providers that use an API key (e.g. MapTiler or Mapbox), consult the provider documentation for how to add the key to the API URL. For example, in MapTiler it would be https://api.maptiler.com/maps/outdoor/{z}/{x}/{y}.png?key=ABCDEFGH.

Although that's the case with this plugin in general, it's worth noting explicitly that using 3rd party map data properly, and making sure you are not violating any terms of use, is your own responsibility.

Note that Google Maps is not in that list, because although it does provide the same standard form of static tiles in the same URL format, the Google Maps terms of service makes it difficult to legally bundle the maps in an application.

If you have multiple map sources, they can be switched from the View pane. Additionally, you can set an optional different dark theme URL for each map source. If a dark theme is detected, or if you specifically change the map source type to Dark (using the drop down in the View pane), you will get the Dark URL if one is configured.

Presets

If there is a map state you would like to save and easily come back to, you can save it as a preset. To do so, open the Presets pane in the main plugin's controls, and click 'Save as' to save the current view with a name you can easily go back to.

If you enter an already-existing name, that preset will be overwritten.

The saved preset includes the map state (zoom & pan), the filters used, and if you check the box in the "save as" dialog -- also the chosen map source. If you do not include the map source as part of the preset, switching to the newly-saved preset will use the currently-selected map source.

Presets do not store the map's theme (light/dark).

The Default preset is special; you can save it using the 'Save as Default' button, and come back to it by clicking the Reset button, by choosing the Default preset from the box, or by opening a fresh Map View that has no previously saved state.

Open In

Many context menus of Map View display a customizable Open In list, which can open a given location in external sources. These sources can be Google Maps, OpenStreetMap, specialized mapping tools or pretty much anything you use for viewing locations.

The Open In list is shown:

This list can be edited through the plugin's settings menu, with a name that will be displayed in the context menus and a URL pattern. The URL pattern has two parameters -- {x} and {y} -- that will be replaced by the latitude and longitude of the clicked location.

Popular choices may be:

And you can figure out many other mapping services just by inspecting the URL.

URL Parsing Rules

As described above, Map View uses URL parsing rules in several places to provide the ability to parse URLs (or other strings) from external sources and convert them to standard geolocations.

  1. When right-clicking a line with a recognized link, a "Convert to Geolocation" entry will be shown in the editor context menu.
  2. When a recognized link is detected in the system clipboard, a "Paste as Geolocation" entry will be added in the editor context menu.
  3. In the "New geolocation note" dialog and map search, pasting a supported URL will parse the geolocation.

URL parsing rules can be configured in the plugin's configuration pane and requires familiarity with regular expressions.

The syntax expects two captures group and you can configure if they are parsed as lat, lng (most common) or lng, lat.

And if you think your added regular expressions are solid enough, please add them to the plugin using a PR so others can benefit!

View URLs

You can save the current map state as a URL, which will open from other apps or from within Obsidian.

Click "Copy Map View URL" from the view's "more options" context menu, or "Copy URL" from the map Presets control. You can paste the resulting obsidian:// URL in any local app on your computer or phone, and it will launch Obsidian with Map View in the same view you saved.

Alternatively, you can paste this link inside a note and make it clickable by making it a Markdown link: [Link name](url...). This is really useful for going to a specific view (with its query, map source, zoom, pan etc) that is related to a note, e.g. a trip plan.

Follow Active Note

Map View has a mode on which the map refocuses according to the currently active file, so if you have Map View open in its own pane, it can follow whatever file you are currently focused on.

This is closely related to the setting of "map follows search results", and probably works most intuitively when it is on.

The specific behavior of how to "follow" the active note can be configured via the 'query format for "follow active note"' setting in the configuration. By default, Map View uses the query path:"$PATH$", which means that when you switch to a note, the view automatically updates the query to show only the markers within the path of this note. You can edit this setting to achieve more fine-grained behaviors, for example:

GPS Location Support

This still in early beta.

Map View works inside Obsidian, and as such, is limited by some restrictions that Obsidian enforces. One of these restrictions is that the Obsidian apps (both desktop and mobile) do not ship with location permission enabled, and as such, plugins that run within Obsidian cannot access the device location. This has been discussed in the past with the Obsidian developers, but as a notes app, they prefer to keep this unavailable for the time being.

As a workaround, Map View supports an external geo helper app, which has separate permissions, and can report the current location to Map View from outside the app. This is currently in an early beta, and the experience may not be optimal. However, it answers the basic need of adding proper GPS support to Map View in many cases.

There are currently two variants of the Geo Helper app: a web app and an Android app. Visit the Geo Helper repo for instructions how to install and use it (the web app requires no installation, but you should still read the instructions).

Either way, the Geo Helper runs completely locally and your location is not sent to any server. Feel free to inspect the code (and improvements are welcome).

To use the Geo Helper, first turn on "GPS" in the Map View settings. Then, select the Geo Helper type: external URL (default), installed app or command line. The use for "command line" is for more advanced usages where you want the web app saved locally, or if you want it launched with a browser that is not your default.

This adds the following functionality:

Many of these can also be launched directly from the geo helper after it finds your location.

Help needed: the geo helper mobile app is currently only available for Android. If you are an iOS developer who wishes to build and maintain the corresponding app, please reach out.

Links View

Map View can optionally draw edges between markers of linked notes.

To turn this on, open the "Links" drop-down on the map controls and choose "show links".

The way it works is that all the markers of a given file (sources) are shown as linked to the markers pointed by the links in that file (destinations). A destination can be:

Finally, you can configure the color used for the edges on the map using any valid HTML color name or a hex value like #faebd7.

Warning! heavily-linked maps are resource-intensive, so it's advisable to turn on links display only when your markers are reasonably filtered. Due to the way they work, links may need to be recalculated every time notes with geolocations are changed. Open Map Views (even background ones) with thousands of visible links may cause hiccups when typing inside geolocation notes that are included in these views' filters.

Relation to Obsidian Leaflet

Users who are looking to add mapping capabilities to Obsidian may want to also look at the great Obsidian Leaflet plugin. And while both plugins are about maps and use Leaflet.js as their visual engine, they represent different approaches.

What’s similar?

What's different?

Changelog

5.0.2

5.0.1

5.0.0

This is a major Map View release with tons of new features and fixes.

Forward compatibility warning: front-matter notes you create with this version will not show in previous Map View versions.

The Big Changes:

Smaller Improvements:

4.0.1

4.0.0

3.1.1

3.0.2

Many small improvements and fixes:

3.0.1

Fixes:

3.0.0

New:

Fixes:

2.2.0

New:

Fixes:

2.1.1

Fix for OpenStreetMap geolocation search stopped working for some users.

2.1.0

BREAKING: this release requires Obsidian 0.15.3 or newer.

New:

Fixes:

2.0.5

2.0.4

2.0.3

2.0.0

This is a massive version with a huge number of updates, pushing Map View to the next level of functionality!