Import and Export

Maparoni is an open toolbox. You can import data from various sources in various formats, share Maparoni collections, and export them for further processing in other tools.

For getting data into Maparoni, there’s the easy way - some predefined formats that are, more or less, handled out-of-the-box, and there’s the custom way when you have a custom format where you need to tell Maparoni where to find the relevant bits. And for getting data out, you can export as CSV or GeoJSON.

If any of those doesn’t match your use case, you can also use Maparoni’s scripting capabilities, and reach out in our community forum.

Import versus subscribing

There are two ways for getting data into Maparoni: Importing and subscribing.

When you import data, you do an initial one-off transformation of the original format to Maparoni’s format, and, once imported, you can then modify the content as you like, editing locations, adding new ones, and alike.

When you subscribe, you provide a location of where the data lives - typically on some server -, what format it’s in, and whenever the data changes the collection gets updated. You can’t add, edit or remove locations, but you can configure how the data should be displayed, configuring fields, formulas and views. See GeoSubscription for more details.

Regardless of whether you import or subscribe, Maparoni can deal with the formats described below.

Easy import

On the easy side, Maparoni supports files in GeoJSON, GPX, and KML formats, and also encoded polylines.

For importing the first three files, you can create a new collection and import their contents when creating a new collection using the ‘Import…’ option and then selecting the files. You can add their content to an existing collection, using the “+” > “Import…” option within a collection, or by dragging and dropping files onto the list of locations in your collection. Alternatively, you can subscribe to a URL that returns any of these format.

Importing encoded polylines

Google’s encoded polyline format is a compact representation of a series of coordinates, that is used by various APIs.

You can import a route in this format using the “+” > “Import…” > “Encoded polyline” option.

Importing (or opening) GeoJSON

Maparoni uses GeoJSON internally and supports this natively, so in addition to the above options, you can also open and edit GeoJSON files in-place.

Importing GPX

Maparoni can import a subset of the full GPX format.

Per-point time information and “extensions” are added as coordinate properties. Limitations are that rteType is ignored, properties intended for GPS devices are ignored, and track segments with single points are dropped.

Importing KML

Maparoni can import a subset of the full KML format. Styles, overlays and folders are not supported, but locations, routes and polygons can be imported.

If the KML import doesn’t work out-of-the-box, please provide the appropriate namespace URL.

Custom import

Maparoni can work with data provided in arbitrary CSV, JSON or XML format. In that case, you’ll need to provide more information on where to find the location-related data, how and what to extract from it. The general idea, at least for JSON and XML, is that you need to be able to point at somewhere within the JSON or XML structure at a list of objects that will then each be turned into one location in your collection, how to extract the geographic information for it, and what properties to extract.

Importing from CSV

Importing CSV is a bit simpler, as it’s assumed that each row represents a location. You can also merge rows into a single location.

Required is that 1) the CSV starts with a header row, and 2) you nominate which CSV colums to use to extract the location. This can be either two columns describing latitude and longitude, or a column identifying a country by name.

Optionally, you can define an identifier by selecting one or more columns to use.

Optionally, you can also opt into merging rows that have a matching identifier. When merging rows, all rows that have the same identifier will be collapsed into a single location (or GeoJSON Feature) in the collection. You can select other columns that should be maintained, by merging them into a new field (with a new name, that you have to provide). The value for that field will be a list, with one element for each merged row. When specifying multiple columns each element in the list is again a list with one value per column.

Importing from JSON

To import (or subscribe to) JSON, the underlying JSON needs to have a structure that can be traversed in a simple way to get to, firstly, the locations each encoded in some JSON object, and, secondly, to get to the location-information within that JSON object. Optionally, you can also specify where to find the ID and other properties in that JSON object. (If you want to visualise JSON data that does not have this format, you can use Maparoni’s support for scripting apps.)

For example, you want to see all the free-floating bicycles from Nextbike in Berlin, which are available via a GBFS API at https://gbfs.nextbike.net/maps/gbfs/v1/nextbike_bn/de/free_bike_status.json which returns a JSON such as:

{
  "last_updated": 1616028066,
  "ttl": 60,
  "data": {
    "bikes": [
      {
        "bike_id": "13450",
        "lat": 52.5161296,
        "lon": 13.3313414,
        "is_reserved": 0,
        "is_disabled": 0
      },
      ...
    ]
  }
}

In this case data.bikes is the path that points to the list of the JSON objects where each element will be a location in our Maparoni collection. And for the location we’ll want to specify that within that JSON object lat defines the latitude and lon defines the longitude to use for each location.

The paths can include periods (.), array lookups (e.g., [0]), array extensions (i.e., []), and optionals (?). For example, root.something?[0] would point to the first element within something within root, but only if something exists. Or countries[].cities would point to a list of all cities across all countries.

The following location typles are supported when importing JSON:

  • Latitude & longitude: define the coordinates of a single point
  • Encoded polyline: define a route (GeoJSON LineString)
  • Encoded polygon: define a polygon (GeoJSON Polygon with no cut-outs)
  • GeoJSON geometries: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon and GeometryCollection.

Import from XML

Importing XML works similar to JSON, but paths are XPaths.

When importing XML, be mindful of Namespaces. If the XML is clarifying a separate namespace in the root tag, then you can’t just use //element to get to any <element> but you need to 1) specify a prefix for the main namespace, and then use 2) //prefix:element (where prefix is the prefix you specified) to get to every <element>.

  • Latitude & longitude: define the coordinates of a single point
  • Encoded polyline: define a route (GeoJSON LineString)
  • Encoded polygon: define a polygon (GeoJSON Polygon with no cut-outs)
  • GeoRSS: Simple variant of either point, line or polygon
  • KML geometries: <Point>, <MultiGeometry>, <Polygon> or <LineString>

Export

Exports always export a snapshot of the current view of a collection, including filter, sorting or map style, and they also export formula results (rather than the formulas themselves).

Exporting is done using the “Export As…” action in the share menu.

Exporting as CSV

Note: CSV export will only include points on the map, no routes or polygons. If your have location in your collection that are routes or polygons, you can use a pin(coordinate) formula for the “style” of your view, to turn every location into a point coordinate.

The CSV contains latitude, longitude, and then one column per field (sorted alphabetically by their keys). It also includes a header row.

Exporting as GeoJSON

Exporting as GeoJSON includes the entire collection, with the current view and formula results applied.