Introduction to the Command Line Tool

Some useful commands, with examples

Get help using mapshaper

# List all the available commands
mapshaper -h

# See detailed options for one command
mapshaper -h simplify

Get information about a dataset

# Summarize a dataset and list attribute fields
mapshaper mystery_data.json -info

# Calculate some statistics about attribute data (INCOME is a field name)
mapshaper provinces.shp -calc 'min(INCOME)' -calc 'median(INCOME)' -calc 'max(INCOME)'

Convert between file formats

# Convert all the Shapefiles in a directory into GeoJSON.
mapshaper *.shp -o format=geojson

# Convert a CSV file with lat/lng fields to a GeoJSON file containing point features.
mapshaper locations.csv -points x=lng y=lat -o format=geojson

Simplify a polygon layer (works for polylines too)

# Retain 10% of removable vertices
mapshaper counties.shp -simplify 10% -o out.shp

Clip a layer of polygons, lines or points using polygons in a second layer

mapshaper states.shp -clip land_area.shp -o clipped.shp

Erase parts of a polygon, line or point layer using a second polygon layer

mapshaper land_areas.shp -erase water_bodies.shp -o erased.shp

Aggregate polygons by dissolving edges

# Dissolve polygons in a feature layer into a single polygon
mapshaper states.shp -dissolve -o country.shp

# Generate state-level polygons by dissolving a layer of counties
# (STATE_FIPS, POPULATION and STATE_NAME are attribute field names)
mapshaper counties.shp -dissolve STATE_FIPS copy-fields=STATE_NAME sum-fields=POPULATION -o states.shp

Join an external data table to a feature layer

# Join a csv table to a Shapefile
# Tip: the FIPS:str type definition prevents the values in the FIPS field from being converted to numbers
mapshaper states.shp -join demographics.csv keys=STATE_FIPS,FIPS field-types=FIPS:str -o joined.shp

# Join the dbf table from one Shapefile to another Shapefile
mapshaper states.shp -join states2.dbf keys=STATE,STATE -o joined.shp

Use an attribute as an id

# Add data field to use as identifier
mapshaper -i counties.shp -o counties.svg id-field=gID format=svg

Edit the attribute table

# Add data fields using a JavaScript expression.
mapshaper counties.shp -each "STATE_FIPS=CNTY_FIPS.substr(0, 2), AREA=$.area"

Use a sequence of commands

# Generate a tract-level Shapefile of populated areas by dissolving census blocks with non-zero population.
mapshaper tabblock2010_36_pophu.shp \
  -each 'TRACT=BLOCKID10.substr(0,11)' \
  -filter 'POP10 > 0' \
  -dissolve TRACT sum-fields=POP10 \
  -o out.shp

# From a county-level Shapefile, generate files for state and national boundaries.
mapshaper counties.shp \
  -dissolve STATE_FIPS name=states \
  -dissolve + name=usa \
  -o out.shp

Working with layers

Most of mapshaper's commands apply to layers of data features. A layer is a collection of features with the same geometry type and a consistent set of data properties (or no data properties). Mapshaper supports polygon, polyline and point layers. For all of these types, a single feature may contain one geometric shape, multiple shapes, or no shapes (i.e. null/empty geometry).

The simplest way to use mapshaper is to import a single layer of features, edit it, and save to a file:

mapshaper counties.shp -filter '$.isNull === false' -o counties_notnull.shp

Version 0.2.0 introduced support for multiple layers along with new syntax for selecting which layer or layers a command should target. The -target <layers> command takes a (comma-separated) list of one or more layers for the subsequent command to target. As an alternative, most commands support the target=<layer(s)> option.

The following example shows how to import a layer of province boundaries, create a second layer consisting of just the shared boundaries, simplify the geometry and save both layers as GeoJSON files. In this example, the -innerlines command is invoked with two options: +, which creates a new layer instead of replacing the target layer, and name=lines, which renames the new layer. The output is two files, out/provinces.json and out/lines.json.

mapshaper provinces.shp \
  -simplify 20% \
  -innerlines + name=lines \
  -target provinces,lines \
  -o format=geojson out/

When importing TopoJSON files, mapshaper treats each named object as a separate layer. The next example shows how to import a TopoJSON file containing a layer named states along with several other layers, extract the feature for Hawaii and save it as a GeoJSON file. In this example, invoking -filter with target=states applies the filter command to the layer named states. The subsequent -o command targets the output of the previous command.

mapshaper usa.topojson \
  -filter 'STATE == "HI"' target=states \
  -o out/hawaii.json format=geojson