Skip to content

Introduction to the Command Line Tool

Jump to bottom Edit New page
mbloch edited this page Nov 20, 2014 · 13 revisions

Some useful commands, with examples

Get help using mapshaper
# List all the available commands
mapshaper -help

# See the options for one command
mapshaper -help simplify
Get information about a dataset
# Summarize a dataset and list attribute fields
mapshaper mystery_data.json -info

# Calculate some statistics about attribute data
# (POPULATION and INCOME are names of attribute fields)
mapshaper provinces.shp -calc 'sum(POPULATION), min(INCOME), max(INCOME), count()'
Convert between Shapefile, GeoJSON and TopoJSON formats
# Convert all the Shapefiles in a directory into GeoJSON.
mapshaper *.shp -o format=geojson
Simplify a polygon layer (works for polylines too)
# Retain 10% of removable vertices
mapshaper counties.shp -simplify 10% -o
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 :str suffix prevents FIPS field from being converted to numbers
mapshaper states.shp -join demographics.csv keys=STATE_FIPS,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
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
# From a county-level Shapefile, generate files for state and national boundaries.
mapshaper counties.shp \
  -dissolve STATE_FIPS name=states \
  -dissolve + name=usa \
  -o

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. 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 \
  -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 an object named states, 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. Invoking -o with the option target=states tells mapshaper to export just the states layer. Without the target= option, mapshaper would export all of the layers from the original TopoJSON file as separate GeoJSON files.

mapshaper usa.topojson \
  -filter 'STATE == "HI"' target=states \
  -o hawaii.json format=geojson target=states
Add a custom footer
Clone this wiki locally