Using mapshaper programmatically

This page is for developers who want to use mapshaper's geoprocessing functions in their own Node applications. Updated for version 0.4.0

Option one: use make (or equivalent)

One way of scripting mapshaper is to call the mapshaper command line program from make or other build tool.

If you include mapshaper as a dependency in the package.json file of a Node.js project, the executable program can be found at this path: node_modules/.bin/mapshaper.

Note: Starting with version 0.4.0, the -o force flag is no longer needed, mapshaper will overwrite existing files by default.

Here's an example Make target:

europe.json: shp/europe.shp
	@./node_modules/.bin/mapshaper auto-snap $< encoding=utf8  \
	-rename-layers countries \
	-filter "CONTINENT == 'Europe'" \
	-simplify 15% keep-shapes \
	-o force format=topojson $@

Option two: mapshaper.runCommands()

mapshaper.runCommands(commands, done)

• commands A command line string or an array of parsed command objects, starting with the -i command
• done A Node-style callback: function(Error)

Example Convert a directory of Shapefiles to GeoJSON

var mapshaper = require('mapshaper');
mapshaper.runCommands('-i shapefiles/*.shp -o geojson/ format=geojson');

Option three: mapshaper.applyCommands()

mapshaper.applyCommands(commands, input, done)

• commands A string containing command line arguments or an array of parsed commands.
• input JS object containing contents of files referenced by -i commands, indexed by file name.
• done A Node-style callback: function(Error, output). Output is a JS object containing the contents of generated files, indexed by file name.

Similar to runCommands(), but receives input files from an object and returns output files to a callback, instead of using file I/O.

Note Prior to version 0.4.0, applyCommands() received a single JSON or CSV dataset as the input parameter and returned either a single dataset or an array of datasets as the output parameter of the done callback. This usage still works, but a deprecation notice is printed.

Data types

The following data types are used internally.

dataset

Datasets are groups of one or more layers containing arc references to a single ArcCollection. A dataset is an object with the following properties:

• layers An array of layer objects (see below)
• arcs (optional) ArcCollection type containing paths for all of the polygon and polygon layers in the dataset
• info (optional) Metadata about the dataset, collected on file import

layer

Layers are objects with the following properties:

• name (optional)
• geometry_type supported types: "polygon", "polyline", "point"
• shapes Array of geometry data for each feature.
• data (optional) DataTable object containing attribute data for each feature