Introduction to the Geospatial Plugin


For the last few months I’ve been working on a new TiddlyWiki plugin that provides interactive maps and other features needed by geospatial applications. The goal of the Geospatial Plugin is to enable non-developers to build sophisticated interactive applications that ingest, transform and display geospatial data.

The Geospatial Plugin is now almost ready for the first release but it would be useful to get some early feedback/suggestions/questions from the community before that point.

You can try out the preview build here.

The usual warning: preview builds are liable to further change, and should not be relied upon for important work. However, it is perfectly possible to download the preview build and work with it locally for experimental purposes. An empty build is available that includes the plugin here. Note that the Geospatial Plugin needs the associated custom version of the core, and will not work with the regular v5.3.2-prerelease.

The development of the Geospatial Plugin has been made possible through the generous sponsorship of @Hans_Wobbe via his company Datafix. If you or your company is interested in sponsoring my work, please contact me.



A number of features can be seen on the map within the greeting tiddler of the demo:

  • Markers (the blue pin) and marker groups (the green circles) that represent multiple markers that are close to each other at the current zoom level
  • Clicking on a marker displays a popup with associated information
  • Clicking on a marker group zooms in to show the constituent markers
  • Layers (the purple and blue areas) are essentially polygons defined by points with latitude and longitude. Again, clicking on a layer displays a popup with associated information
  • Zoom and pan with a mouse or via touch gestures
  • Layer menu at the top right that allows the base layer of the map to be selected from an extensible list including ordinary maps, satellite views, terrain, and attractive “watercolour” maps
  • The layer menu also allows the individual map overlays to be hidden and shown

Scroll down further to see the plugin tiddler itself. The documentation is available under the “docs” tab:

How does it work?

Most of the functionality of the Geospatial Plugin is provided by third party libraries and online services:

The plugin itself is mostly the glue necessary to expose this functionality as TiddlyWiki primitives such as widgets and operators.

What does Geospatial mean?

Geospatial may be a new term. It refers to data that is directly linked to specific geographical locations. Thus geospatial data may be anything from a spreadsheet that includes columns with latitudes and longitudes to a complex JSON structure that encodes the boundaries of geographic areas like countries.

The Geospatial Plugin uses GeoJSON for the complex cases but also allows simpler representations, such as giving tiddlers latitude and longitude fields.

What is GeoJSON?

GeoJSON is a widely used industry standard representation for geospatial data. There is an enormous variety of publicly available data in GeoJSON format, and it is generally quite easy to find.

For example, Googling “geojson uk county boundaries” yields as the top match a good quality site that allows a variety of UK GeoJSON data to be downloaded, including the local authorities that define counties.

GeoJSON uses the following fundamental features:

  • A point is a simple pair of latitude and longitude coordinates, with an optional altitude
  • A linestring is a sequence of points that together define a path made up of straight line segments between the points
  • A polygon is a sequence of paths that together define an area bounded by straight line segments that can have holes or discontinuous sections

GeoJSON features are often combined into “feature collections”, a single GeoJSON file

GeoJSON features can also contain an optional “properties” field containing user defined JSON data. For example, a GeoJSON file containing data about US states might be a feature collection of polygons, each with a “properties” field containing the name and population of the state.

The Geospatial Plugin offers many primitives for working with GeoJSON data. For example, the “geounion” operator takes any number of GeoJSON feature collections, and returns a new feature collection that is the union of them all combined.

Geospatial Plugin features

The main feature of the plugin is the <$geomap> widget. It uses the Leaflet.js library to draw a map with markers and layers overlaid over it. There is great flexibility as to loading and selecting background layers.

Other features include:

  • Operator to compute the distance between two points
  • Operator to lookup data within a GeoJSON object given a point
  • Operator to find the nearest point to an anchor from a collection of points
  • Operators to compute the difference, intersection and union of GeoJSON shapes
  • Procedures to retrieve photos from Flickr (requires an API key to be set)
  • Procedures to use Traveltime’s API to compute isochrones

The new <$testcase> widget

The Geospatial plugin includes full documentation, with many interactive examples that allow the source tiddlers to be inspected alongside the output that they generate:

The user can use the tabs on the left to see the tiddlers that comprise the example, with a live preview on the right. The tiddlers are actually editable so that you can modify the examples to see the effect. (Currently these changes are volatile and will vanish if the test case widget is refreshed. Nonetheless, being able to temporarily tweak examples is very helpful for simple experiments.

These interactive examples use a proposed new core widget that is currently called <$testcase>. It works like a lightweight version of the Innerwiki plugin by creating and displaying an embedded wiki. The difference is that the test case widget doesn’t generate an iframe like the Innerwiki plugin, but instead utilises a lightweight embedded wiki object that is rendered directly.

Some more work is needed on the test case widget before it can be merged to the core: for example, it would be useful to give it an optional iframe-based mode for examples that don’t work within the lightweight embedded wiki. The name might need tweaking too.

The documentation for the test case widget is available in the main preview wiki on Vercel.

In a pleasing bit of recursion, the documentation uses the test case widget to show an example of how to use the test case widget:

Finishing Up

There’s a lot of information in this post, but hopefully the simple use cases for the Geospatial Plugin are easy enough. It is a work in progress and so your feedback, suggestions and questions are very helpful. I’d also love to hear about the kinds of applications you’d like to see for these new capabilities.


Cool, will this be a free plugin? (though I don’t think we have an in-wiki-purchase system :stuck_out_tongue: )

Mobile browsers all have location API, how does this plugin calls them?
I care about this because I may need to patch them to make them work in TidGi-mobile, which uses Android native location API.

The testcase widget looks great! While exploring it, I encountered a leaflet javascript error.

Visiting the geodifference-interactive tiddler directly gives “Error: Bounds are not valid.” javascript error in leaflet.js.

Also, the geodifference example doesn’t seem to work for me. I don’t see anything colored blue. The similar geointersect demo is working fine. The intersection of the two regions is showing blue.

I am very excited about the possibilities of this plugin. Within my Kansas Railroad wiki, I’m envisioning using this to plot the routes of many of the railroads on a Kansas map. I could even plot the routes of proposed railroads that were never built potentially. I am going to have a lot fun with this plugin. Thanks @jeremyruston.


@EricShulman’ s Action-get-GPS could be useful with this

Interesting! Can we use that “lightweight” wiki to embed a set of tiddlers inside another application? To share a set of “context-aware” tiddlers inside some application.

Geospatial plugin looks great and useful! Kudus :slight_smile:


Thanks @jeremyruston this is exciting. I am interested in tying this to a current GPS location and connecting it to the what3words solution which also allows one to seek directions from Google maps.

  • in the what3words solution each 3m square on earth has a three.word.address which lends itself to a tiddler title and we can retrieve the long lat, or retrieve the three words with their simple APIs.
  • I am also keen to import GPS trails I collect on bushwalks. Ideally one day I could use mapping to follow a saved trail inside or outside tiddlywiki but with tiddlywiki being the manager or database of choice.

Great stuff thanks

There seem to be two ways to to this. One is

The other one could be extracting GPS locations from exif-data oft images to rebuild a trail using fotos.

I use trail mapping software and can export a trail in a number of formats, even display them on google maps.

  • I have used erics (I think) tool to see the current location on my phone from within tiddlywiki. Impressive.

I’ve fixed this by adding support for a tm-request-geolocation message. It asks the browser for the current location and then passes the details as variables to an action string.

The updated code can be seen here on GitHub

A direct link to the docs for the new message: Geospatial Plugin — Geographic Data Features for TiddlyWiki


There is a misspelling in both the documentation and the code:
altitudeAccurary should be altitudeAccuracy

ref: GeolocationCoordinates: altitudeAccuracy property - Web APIs | MDN

Thanks @EricShulman fixed here

The Flickr examples should be interesting in this regard.

I very much look forward to playing with this. I’ve rarely done work that requires this, but I have a use-case that I will probably start on in the next two weeks. This looks like it could be perfect for that.

In the meanwhile, I just want to point out some missing documentation:

The setquerystring Operator entry seems to be missing.

Thank you, @jeremyruston for all you do for the community!

@jeremyruston I have extensively implemented the leaflet plug-in for a geospatial solution in The Memory Keeper. If you are familiar with this plug-in, can you comment on the differences and potential impact to convert from leaflet?



It is also good to have accurate attitude

One of the reason Flickr was included in this GeoSpaitial plugin is to enhance the mapping experiences that currently exist in other tools.

Also, Pictures can be attractive - for Viewers, Photographers and Travelers.

I’ve tagged a few of my images on the assumption that a “picture is worth (more than) a thousand words”

Next, I intend to use the new TW primitives provided by this plugin to build some trip Tours.

Enjoy and Participate!

1 Like

I would be interested to hear the answer to this too for similar reasons. At first sight Jeremy’s plugin offers far more functionality but if the Leaflet plugin meets your needs I’d stick with it.


I just got around to testing this, and am wondering if the plugin limits the number of pins to the first ten supplied? Or should I look to the underlying leaflet library? (And if the latter, how much of its API is made available through the plugin?)

In my small town of perhaps 1200 addresses, I’m trying to extend a wiki I’ve built for a local political party to map the locations of its political lawn signs. I was hoping to assign each of the nine sign designs its own colored pin and be able to map usually the location of all the signs of that design (from 10 - 25)… and occasionally show all the signs. (Eventually 160 or so.) My first test just chose 20 random addresses and created tiddlers for them including lat, long, and alt fields.

But only ten markers show on the screen. Any ideas why?

IMO there should be no such limit. If you have a look at the demo maps there are easily over 1000 geo definitions in the JSON.

So you will need to make sure that your JSON data is valid. IMO TW most of the times fails silently.