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: make

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.

Here's an example Makefile target:

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

Option two: 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: 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 returns output files to a callback, instead of writing output files to the filesystem. The content of input files can be passed via the input parameter. Files not contained in the input object will be read from the filesystem.

Example: Convert a CSV string to GeoJSON

var csv = 'lat,lng,value\n40.3,-72.3,1000';
var cmd = '-i input.csv -points x=lng y=lat -o output.geojson';
mapshaper.applyCommands(cmd, {'input.csv': csv}, function(err, output) {
	var geojson = JSON.parse(output['output.geojson']);
});

Note on importing Shapefiles: To input a Shapefile using applyCommands(), in addition to passing the contents of the .shp file (as a Buffer or ArrayBuffer), you'll probably want to pass the .dbf file (as a Buffer or ArrayBuffer), which contains attribute data, and the .prj file (as a string), which contains coordinate system data.

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 coordinate data for all of the polygon and polyline 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