Scripting

When you find yourself in a situation where you have something that you want to add to Maparoni, either to an existing collection but as a new collection, but just dragging and dropping it into Maparoni or opening the file doesn’t work, you’re in the right place: Welcome to Scripting & Automation.

While Maparoni doesn’t have built-in support for a scripting language, it is backed by the text-based GeoJSON format and exposes different URL schemes to work with existing scripting tools on iOS, such as Pythonista, Scriptable or Shortcuts (pre-installed on iOS 13).

With these scripting tools, you can generate content for map collections and then use Maparoni to view and work with them:

  1. Individual locations our routes to add to an existing collection, for example, importing a route or area from OpenStreetMap,
  2. Entire collection as one-off export, for example, you have data in another format and want to migrate this to Maparoni.
  3. Entire collection and then subscribe to that content from Maparoni, so that you can update it later again, for example, you have data available in a web API that get’s updated and you want to visualise and work with that data in Maparoni.

Adding to existing collections

Write a script which generates the data that you want to view, and then use of the different maparoni://add-* URL schemes to import it into Maparoni. When the URL scheme is launched, you can then select which collection to add it to.

One-off export of entire collections

This offers a one-way street where you generate the collection first in your scripting app, then export it to Maparoni. This is best used for one-off exports of data into Maparoni, when you want to modify the collection further in Maparoni afterwards, or while working on a script to quickly see the content.

This is relatively straight forward. You generate the GeoJSON content in your script and then pass it to Maparoni using the maparoni://show-data URL scheme. This will create a new temporary collection for it, and triggering that URL scheme again will update that collection in place. This will be a temporary collection and Maparoni will ask you save it when you close it. (Alternatively, you can also take the filesystem approach without any URL schemes by saving your collection to a file and then opening that in Maparoni.)

Dynamic subscriptions to entire collections

This offers a two-way street where you tell Maparoni that the data for a collection is backed by an external script. This is best used where you later want to re-fresh and update the data. This works similar to following to a collection that lives on the web, just that you don’t provide a web URL for the collection but rather a URL scheme to the respective scripting app.

If you have a script that generates a GeoJSON collection that you want to update and regenerate regularly, it is best to use the “script collection” approach. This consists of the following workflow:

  1. You subscribe to a URL scheme that points to (and runs) your script in the scripting app.
  2. When getting the content, Maparoni will run that URL scheme, switching to your script, which should then at the end call back to Maparoni with the new data using the maparoni://load-data URL scheme.
  3. Maparoni then updates the content of that collection with that data.

You can then use Maparoni as usual to using expressions, filters, grouping the content and more. Maparoni will also keep track of the previous content and will highlight locations in the collection that were added or updated since the last time you ran the script. However, Maparoni will not update the content itself (as it requires switching to the scripting app), so you will need to press the “Update” button yourself whenever you want to get the latest content or use the ⌘+R keyboard shortcut.

Note: You cannot edit the locations themselves as that would be overwritten the next time you run the script. However, you can modify the collection’s meta data, i.e., the name, description, as well as adding fields and views.