Waze Ireland Townland Datasets

Documentation for the townland-clipper script and the accompanying wme-datasets website.

Townland Clipper

Documentation for the townland clipper script which splits up open townland datasets provided by the Irish government into counties to enable better performance when they are loaded into the Waze Map Editor.

Townland Clipper

How to use the script

This document is equivalent to the project’s README markdown file and will be added to the repository soon.

Installation and setup

There is no installation required to use this software, but there is a pre-requisite. To use this software you must be able to run node. There is no particular version required, but for your information, the software was developed using version 10.0.8.

The project has a small number of dependencies, which are for parsing input arguments, which is described in the “Usage” section. Dependencies are installed like any other npm project after checking out the repository:

git clone https://github.com/cw1998/townland-clipper
cd townland-clipper
npm install


After this has completed, the script can be run using the following syntax:

node ./ [--arg=arg_value --arg2=arg2_value ...]

This script cannot produce any output without an input file. The input townland files can be retrieved from data.gov.ie

The script is compatible with all variations of the open townland data. Both ungeneralised and all variations of the generalised datasets. It processes one input file per execution and produces a file for each of the Southern counties in a specified target directory.

Required Input arguments

Required arguments:

Optional arguments:

Townland Clipper

Specification and current implementation


User input/configuration

The software must mandate that the user provides a path to a single file, be this by configuration file, command line argument or appropriate component(s) in a GUI.

The software must also allow the user to supply a destination for the output files. The output file destination directory doesn’t have to be empty.

The software must also be able to allow the user to choose to have the geometry precision reduced if required (details below).

Supported input file format

The software should be able to parse files in the GeoJSON format. A typical townland dataset that the software should be able to read can be quite large, up to sizes of a few hundred megabytes. Implementations of this software specification should remain performant when working with these large files.

The software should check that the user-provided path to the input file is valid (it exists) and that it can be read. The software should also check that the file contents are valid (valid JSON) before proceeding.

Output files

The software should produce output files in valid GeoJSON format that can be read by the script called “WME Geometries” available for the Waze Map Editor. There should be an output file produced in a user-provided target directory for each of the counties in the Republic of Ireland. The six counties of Northern Ireland may be included, but this is not strictly necessary as a typical input file does not contain townland boundaries for Northern Ireland.

Output files should follow this naming convention:
For “reduced” files (see below for details on reduction):

For non-reduced files:

Where [county] is the uncapitalised name of the county.

While not required, every effort should be made to make the files as small as possible. Please minify output where possible.

County GeoJSON file structure

Each county GeoJSON file should have the same structural elements. Each file should contain a single object which will contain an array of other objects which contain the townland geometries.

The root object will look similar to this:

  "type": "FeatureCollection",
  "features": [
    ...// Townland objects here.
Townland objects

Each townland is represented in the features array by its own JSON object. GeoJSON specifies that there are two root elements in the object, and these should be included in the output:

The properties object should contain the following keys:

All other values (as specified in this document) can be discarded in the output files.

Supporting the reduce argument

The user can request “reduced” output files. These files contain the same number of townlands, but with reduced precision in order to reduce file size and thus improve performance in the editor.

Each coordinate in the file should be rounded to four decimal places. This has been found to be the best number of places to round to while maintaining enough precision in order to reconstruct townland boundaries with acceptable accuracy in the editor.

Current implementation

Details for the relevant headings above can be found below regarding the current implementation of the software as found on GitHub at https://github.com/cw1998/townland-clipper/ 

Input files

The software reads a GeoJSON file and parses it in its entirety to a normal JavaScript object. This allows for relatively good performance (as opposed to streaming the file) at the expense of memory efficiency.

The software consumed around 8GB of memory when the largest open dataset of townlands was input.

Output files

A minified output file is produced for each of the following counties:

Dataset Download Website

Documentation for the website where files can be downloaded by county as created by the Townland Clipper script.